setup-codex-devcontainer

Files (7)

• SKILL.md
• capability-seam-entries.json · templates/
• install-block.sh · templates/
• network-manifest-entries.json · templates/
• post-start-block.sh · templates/
• readme-bullet.md · templates/
• yolo-alias-block.sh · templates/

SKILL.md (first lines)

# Setup Codex Devcontainer

Adds Codex to a devcontainer already generated by the
[setup-devcontainer](../setup-devcontainer/SKILL.md) skill. This skill never
edits `devcontainer.json` directly — the one exception is appending its own
entries to the Capability Seam (`runArgs`), a designated extension point any
CLI skill may idempotently append to, via a JSON-aware primitive distinct
from the line-oriented one everything else here uses. It also idempotently
ensures its own Network Manifest entry exists in
`.devcontainer/network-manifest.json`, via the same JSON-aware primitive.

## 0. Security & Trust

This skill's generated automation touches three areas an external audit may flag. Each is
opt-in, scoped to this container, and exists for a specific reason — none of it runs on the
host, only inside the generated devcontainer.

- **Installer Provenance**: installs Codex CLI via OpenAI's own official installer
  (`https://chatgpt.com/codex/install.sh`, documented at developers.openai.com/codex/cli).
  Runs once, at container creation (`postCreateCommand`), not on every start — and only if
  `~/.local/bin/codex` doesn't already exist.
- **Agent Authority**: the optional `codex-yolo` alias uses `--ask-for-approval on-request`,
  deliberately not `--dangerously-bypass-approvals-and-sandbox` — that flag removes both the
  sandbox and any approval checkpoint, while `on-request` gives Codex a real internal
  checkpoint where the model itself judges when to escalate to a human. Off by default; only
  added if accepted during setup.
- **Skill Source Trust**: if skill sync is accepted, the source(s) you name are re-synced into
  the Shared Skills Directory (`~/.agents/skills`) on every container start — the same shared
  directory Copilot's and Antigravity's skill-sync also write into. Nothing is wiped — a skill
  removed upstream stays until deleted by hand. The real trust decision is the source itself:
  naming one means trusting its skills unattended, with no per-skill review step, every time
  the container starts. Off by default.

Separately, this skill also unconditionally grants three Capability Seam entries
(`--cap-add=SYS_ADMIN`, `--security-opt=seccomp=unconfined`,
`--security-opt=systempaths=unconfined`) so Codex's own Bubblewrap sandbox — its normal
execution mode, not a YOLO-only feature — can construct its namespace at all. That's a
Blast-radius Containment question, not one of the three above; it was decided and composed
against this container's baseline cap-drop posture in
[ADR-0006](../setup-devcontainer/docs/adr/0006-capability-drop-reject-readonly-rootfs-and-seccomp.md).

See [ADR-0007](../setup-devcontainer/docs/adr/0007-agent-trust-hub-audit-response.md) for the
full Installer Provenance / Agent Authority / Skill Source Trust reasoning and the
alternatives rejected.

## 1. Detect the base devcontainer

```bash
test -f .devcontainer/devcontainer.json && test -f .devcontainer/post-create.sh && echo ok
```

If either file is missing, **refuse** — tell the user to run
`setup-devcontainer` first, and stop. Do not generate or patch anything.

## 2. Ask this tool's options

- **YOLO alias**: add `codex-yolo` for fast, unattended iteration? Uses
  `--ask-for-approval on-request`, not Codex's full-bypass equivalent — see
  the template's own comment for why.
- **Automatic skill sync**: sync AI-agent skills into the Shared Skills
  Directory (`~/.agents/skills`) automatically on every container start?
  Same mechanism as the other CLI skills — two ready-made suites
  (`mattpocock/skills`, `ken-guru/skills`) plus any individually named
  skill, validated live via `npx -y skills add <source> --list` before
  rendering anything.

## 3. Patch `post-create.sh`

Append [templates/install-block.sh](templates/install-block.sh) verbatim:

```bash
scripts/patch-if-absent.sh append .devcontainer/post-create.sh "# --- Codex ---" templates/install-block.sh
```

If YOLO alias was accepted, also append
[templates/yolo-alias-block.sh](templates/yolo-alias-block.sh), under its
own independent marker:

```bash
scripts/patch-if-absent.sh append .devcontainer/post-create.sh "# --- Codex yolo-alias ---" templates/yolo-alias-block.sh
```

## 4. Patch the Capability Seam — unconditional, every run

Codex's Bubblewrap sandbox is its normal execution mode, not a YOLO-only
feature — append its capability requirements to `devcontainer.json`'s
`runArgs` **regardless of the YOLO-alias answer**:

```bash
scripts/patch-json-array-if-absent.sh .devcontainer/devcontainer.json .runArgs templates/capability-seam-entries.json
```

## 5. Patch the Network Manifest — unconditional, every run

Ensure Codex's own `.codex.networkAllowlist` entry exists in
`.devcontainer/network-manifest.json`, regardless of the YOLO-alias answer —
this is what lets an opted-in network firewall (a separate, base-owned
layer) allow the hosts Codex itself needs:

```bash
scripts/patch-json-array-if-absent.sh .devcontainer/network-manifest.json .codex.networkAllowlist templates/network-manifest-entries.json
```

## 6. Patch `post-start.sh` (only if skill sync was accepted)

Render [templates/post-start-block.sh](templates/post-start-block.sh) with
`{{SKILLS_SOURCES_COMMANDS}}` substituted to one `npx -y skills add <source>
--skill '*' -a codex -y --copy -g` line per whole-suite source (or `--skill
'<name>'` per individual pick), then append it:

```bash
scripts/patch-if-absent.sh append .devcontainer/post-start.sh "# --- Codex skill-sync ---" <rendered-block>
```

## 7. Patch `README.md`

```bash
scripts/patch-if-absent.sh append .devcontainer/README.md "- Codex" templates/readme-bullet.md
```

From ken-guru/skills, MIT.

More from ken-guru/skills