Summary

• Problem: On macOS bind mounts (VirtioFS), the entrypoint's chown -Rh appuser:appuser /.archon fails because the host controls ownership and host UIDs (e.g. 501) don't map to container's appuser (1001). The script then exit 1s and the container crash-loops.
• Why it matters: Affects every macOS user running Archon via Docker Desktop with the default bind-mount setup. Currently the only workaround is to run Archon outside Docker entirely.
• What changed: Failed chown is now treated as a warning. Container falls back to running as root, with IS_SANDBOX=1 exported so ClaudeProvider skips its UID-0 safety check (we're still inside Docker — sandboxed in the meaningful sense).
• What did not change (scope boundary): No changes to safe.directory-loop (already fixed by fix(docker): register safe.directory for all repos on bind-mount restart #1307), Linux behaviour (chown succeeds → unchanged path), Kubernetes/non-root behaviour (id != 0 → unchanged path), or the security model on Linux.

UX Journey

Before

User on macOS                     Container start
─────────────                     ───────────────
docker compose up ──────────────▶ entrypoint: chown -Rh appuser /.archon
                                    │
                                    └─ FAILS (host UID, VirtioFS)
                                       │
                                       └─ "ERROR: Failed to fix ownership"
                                          exit 1
                                  Container crash-loops
container never starts ◀────────  user blocked

After

User on macOS                     Container start
─────────────                     ───────────────
docker compose up ──────────────▶ entrypoint: chown -Rh appuser /.archon
                                    │
                                    └─ FAILS (host UID, VirtioFS)
                                       │
                                       └─ [warning logged]
                                          [export IS_SANDBOX=1]
                                          [RUNNER=""]   ←── run as root
                                  Server starts as root
                                  ClaudeProvider sees IS_SANDBOX=1,
                                  skips UID-0 check
container running ◀──────────────  user can use Archon

Architecture Diagram

Before

docker-entrypoint.sh
        │
        ├─▶ chown /.archon (fail-fatal)
        ├─▶ RUNNER="gosu appuser"
        └─▶ exec $RUNNER bun run setup-auth

After

docker-entrypoint.sh
        │
        ├─▶ chown /.archon (try)
        │      ├─ ok  ──▶ RUNNER="gosu appuser"
        │      └─ fail ──▶ warn + export IS_SANDBOX=1 + RUNNER=""   [+]
        └─▶ exec $RUNNER bun run setup-auth

Connection inventory:

Label Snapshot

• Risk: risk: low
• Size: size: XS
• Scope: core
• Module: core:docker-entrypoint

Change Metadata

• Change type: bug
• Primary scope: core

Linked Issue

• Closes # — none directly; complements docker-entrypoint.sh: git "dubious ownership" on macOS bind mounts after container restart #1279 / fix(docker): register safe.directory for all repos on bind-mount restart #1307 which addressed the related safe.directory issue but not this chown failure mode.
• Related docker-entrypoint.sh: git "dubious ownership" on macOS bind mounts after container restart #1279, fix(docker): register safe.directory for all repos on bind-mount restart #1307

Validation Evidence (required)

# Locally on macOS (Docker Desktop, VirtioFS bind mount):
docker compose down
docker compose build --no-cache
docker compose up
# Container starts, "WARNING: Could not fix ownership..." appears once,
# then server reaches gh_auth.status_ok and serves on :5174.

• Evidence: container logs show single warning then normal startup. No crash-loop. Web UI reachable. Functional integration test (chat-message → soft-sync) confirmed working in the same session.
• Skipped commands: bun run type-check, bun run lint, bun run test — touched file is a shell script, not TS; lint-staged was a no-op for .sh.

Security Impact (required)

• New permissions/capabilities? No — when fallback fires, the process runs as root inside the container, but it would have run as root before too (the difference is exit 1 vs continuing).
• New external network calls? No.
• Secrets/tokens handling changed? No.
• File system access scope changed? No — chown itself is unchanged; only the failure handling differs.
• Security note: running as root is undesirable but not a regression — the alternative is "container does not start", which strictly speaking is more secure but also unusable. IS_SANDBOX=1 mirrors how Claude SDK itself handles known-sandboxed contexts; the container is still isolated by Docker.

Compatibility / Migration

• Backward compatible? Yes — Linux setups where chown succeeds are unchanged. Only the previously-fatal failure path is altered.
• Config/env changes? Yes (passive): IS_SANDBOX=1 is exported in the fallback path. Users who already set IS_SANDBOX explicitly are not overridden if chown succeeds.
• Database migration needed? No.

Human Verification (required)

• Verified scenarios:
  • macOS Docker Desktop, default bind-mount setup → was failing before this patch, now starts cleanly.
  • Server reaches gh_auth.status_ok and cleanup_completed log lines.
  • Web UI on :5174 is reachable.
  • Subsequent chat-tick / soft-sync flow works (validated as part of git reset --hard origin/<default_branch> on source/ every message — destroys any local state that has diverged from origin for managed clones #1516 testing in the same session).
• Edge cases checked: chown-success path (Linux Docker host emulator) still goes through the appuser branch; verified by inspection of the conditional, no code path duplication.
• What was not verified: Kubernetes / --user-flag invocation (the else branch is unchanged structurally; behaviour-equivalent to pre-PR).

Side Effects / Blast Radius (required)

• Affected subsystems: container startup only.
• Potential unintended effects: a Linux user who intentionally configured chown to fail (highly unusual) would now silently get root-execution instead of exit. Mitigated by the explicit WARNING: log line.
• Guardrails: warning is logged on stderr, visible in docker compose logs. IS_SANDBOX=1 is observable in process env.

Rollback Plan (required)

• Fast rollback: revert this single commit (git revert <sha>). One-file change, no DB/state to migrate.
• Feature flags: none.
• Observable failure symptoms: macOS container would resume crash-looping with the original ERROR: Failed to fix ownership message — same symptom as before this PR.

Risks and Mitigations

• Risk: A misconfigured Linux host where chown fails for an unrelated reason (filesystem error, capability missing) would now log a warning and run as root instead of failing fast.
  • Mitigation: Warning is loud and explicit. Discovery via logs is easy. The previous behaviour (exit 1) was equally hostile to debugging in that case (no remediation hint either).
• Risk: IS_SANDBOX=1 skips a ClaudeProvider UID safety check that exists for a reason.
  • Mitigation: The check is for "user is running Claude as root on a host system" — that's not what's happening here (we're inside a container). The flag is purpose-named for exactly this pattern.

Summary by CodeRabbit

• Bug Fixes
  • Container startup no longer always fails if permission adjustment fails during initialization; it now logs a warning and can continue in restricted environments.
  • Continuing as root requires explicit opt-in via ARCHON_ALLOW_ROOT_FALLBACK=1; without that the container will still exit with an error.