setup

Set up aicontainer in a project

Your job is to take a project from "no sandbox" to "the AI agent runs behind the aicontainer devcontainer boundary, configured for this project's stack." You detect the stack, sanity-check that a Linux devcontainer is even the right tool, propose a concrete customization plan, and — once the user approves — apply it.

aicontainer's whole point is letting Claude Code / Codex / OpenCode run with permissions skipped without handing a prompt-injected dependency your real $HOME, .env, SSH keys, or gh token. Good setup is what makes that sandbox actually usable for the project — a Python repo needs a writable .venv, an agent that uses go-to-definition needs a language server on PATH, a Postgres app needs the DB reachable. That per-project wiring is the work here.

The other half is the person: their tool settings, prompt, aliases, and statusline. Some of that is seeded automatically, some is deliberately dropped, and some needs an explicit opt-in they'd never guess at. Step 6 walks them through it — a sandbox the user can't stand working in doesn't get used.

Golden rules (read first — they shape everything below)

These come straight from how aicontainer is designed; violating them creates work that silently gets wiped or breaks aic sync.

• Run aic from the host, never from inside the container. Setup happens before (or outside) the sandbox. If you detect you're inside an aicontainer already (see Step 0), stop and tell the user to run this from a host terminal — .devcontainer/ is mounted read-only in the sandbox by design.
• Never hand-edit .devcontainer/devcontainer.json or .devcontainer/docker-compose.yml. They are template-managed: aic init writes them and aic sync overwrites them (only the AIC_TOOLS / AIC_SHELL choices survive). All per-project customization goes in the project-owned files instead (listed in Step 5). Edits to the managed files get reset on the next sync.
• All customization lives in project-owned files that aic sync never touches: Dockerfile.project, docker-compose.override.yml, chown-paths, post-create.project.sh, vscode-extensions, vscode-settings.json, firewall-allowlist, shell-rc.zsh, p10k.zsh, statusline.{sh,mjs,js,py}. These are opt-in by presence.
• aic rebuild is the verb that builds — aic up is not. aic up runs a plain devcontainer up, and the managed pull-mode Compose sets pull_policy: missing: when the resolved image tag is already cached, Compose reuses it and never runs your Dockerfile.project. The stack comes up looking healthy on the plain base image, with every baked tool missing and every named volume still root:root. aic rebuild adds --remove-existing-container --build-no-cache, which is what actually builds. So: if the plan writes a Dockerfile.project, the first boot is aic rebuild, and so is every boot after you edit it.
• Host-boundary trust is the user's to grant — you can't, and shouldn't. A Dockerfile.project (or an added mount, a protected env key, Docker socket exposure) makes aic validate / up / rebuild fail closed until the human runs aic trust, which requires a TTY and so cannot run from your Bash tool. Hand it to them; never route around it with --allow-unsafe. Trust binds to an exact config hash, so any later edit to docker-compose.override.yml or Dockerfile.project revokes it — settle the config completely before you ask (Step 8).
• Show the plan, then apply. Detect and confirm first, present the full plan, get a yes, then write files and run aic init / aic sync. Confirm before the first boot — it pulls or builds a multi-gigabyte image and can take minutes — but once the user says go, drive it yourself: verify the container actually boots and fix what's broken (Step 9). Don't just hand back a command and hope.