sha256:847dc44a1f996e9431dca10c72de88a4933017272fa54fa4ae68e8f01eef573a
Last pushed
10 days by cdupuis
Type
Sandbox Kit
Manifest digest
sha256:847dc44a1f996e9431dca10c72de88a4933017272fa54fa4ae68e8f01eef573a
schemaVersion: "3"
displayName: Codex over ACP
author: Docker, Inc.
description: 'A sandbox an ACP client can drive: a shell base, Codex CLI, and the Agent Client Protocol adapter that fronts it — published as one kit. The same three kits compose by hand; this exists so an editor can be pointed at one reference instead of three that have to agree.'
sourceUrl: https://github.com/docker/sandbox-kit-spec
version: 1.0.4
licenses:
- Apache-2.0
kind: workload
provides:
- [email protected]
- [email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/ca-certificates-java@20240118
- deb/ca-certificates@20250419
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/iputils-ping@20240905
- deb/[email protected]
- deb/[email protected]
- deb/less@668
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
- deb/[email protected]
capabilities:
- type: com.docker.sandbox/network-policy@1
config:
runtime:
allow:
- api.openai.com:443
- openai.com:443
- auth.openai.com:443
- chatgpt.com:443
- files.openai.com:443
- releases.openai.com:443
- api.github.com:443
- github.com:443
- release-assets.githubusercontent.com:443
- codeload.github.com:443
- deb.debian.org
- dhi.io
- type: com.docker.sandbox/credential@1
optional: true
config:
apiKey:
inject:
- domain: api.openai.com
format: Bearer %s
header: Authorization
- domain: openai.com
format: Bearer %s
header: Authorization
name: OPENAI_API_KEY
proxyManaged: true
oauth:
resourceHosts:
- chatgpt.com
sentinels:
accessToken: oai-oat01-proxy-managed
refreshToken: oai-ort01-proxy-managed
tokenEndpoint:
host: auth.openai.com
path: /oauth/token
phase: runtime
service: openai
description: OpenAI API access (API key or ChatGPT OAuth)
- type: com.docker.sandbox/agent-skills@1
optional: true
config:
path: /home/agent/.agents/skills
- type: com.docker.sandbox/agent-context@2
optional: true
config:
content: |
Codex CLI is installed at `/usr/local/bin/codex`. Run `codex` for an
interactive session or `codex exec "<prompt>"` for a one-shot run.
Authentication is proxy-mediated: `OPENAI_API_KEY` in this container is a
sentinel — the sandbox proxy substitutes the real key bound on the host
(`sbx secret set openai`) on requests to `api.openai.com`. Without a
bound key, `codex` will ask you to log in.
directory: /home/agent/.codex
filename: AGENTS.md
- type: com.docker.sandbox/acp@1
optional: true
config:
agent: codex
command:
- codex-acp
env:
INITIAL_AGENT_MODE: agent-full-access
description: Drive codex sessions over the Agent Client Protocol
- type: com.docker.sandbox/agent-context@2
optional: true
config:
content: |
## Codex ACP adapter
`codex-acp` is installed at `/usr/local/bin/codex-acp`. It is an Agent
Client Protocol (ACP) server on stdio: a client spawns it and drives a
Codex session through the protocol. It is not an interactive command —
with no client on the other end of stdio it sits silent, so do not run it
from this shell to "check" it.
Host tools must attach it to a non-TTY stdin/stdout stream, for example
`sbx exec -i <sandbox> codex-acp`. In Zed, configure an agent server
whose command runs that.
The adapter drives the same `codex` binary this sandbox already has
(`CODEX_PATH=/usr/local/bin/codex`), so authentication is the surface
`codex` uses: the proxy-mediated OpenAI credential behind
`~/.codex/auth.json` and the `~/.codex/config.toml` this composition
seeds. If `codex` works here, the adapter works with no extra setup and
nothing separate to log in to. Sessions created through ACP and
interactive `codex` runs share the same `~/.codex` state, which this
composition keeps in the sandbox filesystem rather than on a volume.
The Kit declares an optional `acp@1` endpoint, so supporting hosts can
find the adapter without hard-coding its command. It starts in
`agent-full-access` mode to match the interactive Codex entrypoint.
Pinned `codex-acp` 2.2.2 handles stdin closure but has no `SIGTERM`
cleanup handler. Cancellation and session flushing on `SIGTERM` have
not been verified against `acp@1`'s shutdown guarantee. Hosts should
close the ACP stdin stream and allow the adapter to finish before
terminating it.
The optional declaration enables discovery; it does not certify full
adapter conformance.
- type: com.docker.sandbox/sbx@1
- type: com.docker.sandbox/agent-context@2
optional: true
config:
content: |
This is a plain shell sandbox on the shell-docker template: bash,
git, apt, Docker (compose/buildx), curl, gh, jq, make, gcc,
Python 3, and Node/npm. Install more with apt; composed kits list
their own capabilities below.
filename: AGENTS.md
- type: com.docker.sandbox/agent-context@2
optional: true
config:
content: |
# Codex over ACP
This sandbox is a published *set*: one kit whose content was merged from
a shell base, Codex CLI, and the Agent Client Protocol adapter. Run
`cat /usr/share/sandbox/kit/codex-acp-set/kit.yaml` to see the three, each pinned
by digest, and `ls /usr/share/sandbox/kit/` to see their own sources
staged beside each other.
Two ways to work here, and they are the same agent either way:
- Interactively, `codex` — the binary at `/usr/local/bin/codex`.
- Over ACP, `codex-acp` on stdio, which an editor spawns and speaks the
protocol to. It execs the same binary, so editor-driven and terminal
sessions share the version, credential, configuration, and state.
The adapter opens no sockets of its own. Its egress and OpenAI credential
are the ones Codex already has, so the merged policy does not need a
second copy of either declaration.
directory: /home/agent/.codex
filename: AGENTS.md
- type: com.docker.sandbox/lifecycle@1
config:
install:
- command:
- sh
- -c
- |
set -e
mkdir -p /home/agent/.codex /home/agent/.agents
MODE="${SBX_CRED_OPENAI_MODE:-none}"
cat > /home/agent/.codex/config.toml << 'EOF'
# Codex configuration for Docker sandbox
# This configuration enables "yolo mode" - no approvals, full access
approval_policy = "never"
sandbox_mode = "danger-full-access"
mcp_oauth_credentials_store = "file"
# Turn-complete hook for sbx Desktop (see /usr/local/bin/sbx-codex-hook):
# raises the desktop notification and forwards the session's model,
# effort, token usage and git state read from this thread's rollout
# file. `notify` is top-level and needs no hook trust; Codex spawns
# it fire-and-forget with the event JSON as the last argument, and
# the script is a silent no-op when no desktop server is loaded.
notify = ["/usr/local/bin/sbx-codex-hook", "codex"]
EOF
# Model selection from the create-phase args. These are
# top-level keys, so they must land here, before the
# model_providers and projects tables below would capture
# them. The args' patterns admit no quote or backslash, so
# the expanded value is safe inside the TOML string.
model=''
effort=''
[ -z "$model" ] || printf 'model = "%s"\n' "$model" >> /home/agent/.codex/config.toml
[ -z "$effort" ] || printf 'model_reasoning_effort = "%s"\n' "$effort" >> /home/agent/.codex/config.toml
# Managed modes must not let remote clients replace the proxy
# placeholder with sandbox-local ChatGPT OAuth. None mode
# deliberately permits login.
case "$MODE" in
oauth|apikey)
cat >> /home/agent/.codex/config.toml << 'EOF'
forced_login_method = "api"
EOF
;;
esac
if [ "$MODE" = oauth ]; then
cat >> /home/agent/.codex/config.toml << 'EOF'
model_provider = "sandboxd"
[model_providers.sandboxd]
name = "Sandbox Proxy"
base_url = "https://chatgpt.com/backend-api/codex"
experimental_bearer_token = "oai-oat01-proxy-managed"
requires_openai_auth = false
EOF
fi
# Pre-trust the workspace so codex skips its "do you trust this
# directory" onboarding — the v2 kit skipped it via its
# --dangerously-bypass-approvals-and-sandbox entrypoint, which a
# mixin (plain `codex` from the base shell) doesn't have. MUST
# stay after every top-level key append: [projects."…"] opens a
# TOML table, and any key appended after it would silently land
# inside that table (which is exactly how model_provider once
# vanished, sending codex to api.openai.com with a ChatGPT
# token and a scopes 401).
ws="${WORKSPACE_DIR:-/home/agent/workspace}"
esc=$(printf '%s' "$ws" | sed 's/\\/\\\\/g; s/"/\\"/g')
cat >> /home/agent/.codex/config.toml <<EOF
[projects."$esc"]
trust_level = "trusted"
EOF
case "$MODE" in
oauth|apikey)
cat > /home/agent/.codex/auth.json << 'EOF'
{
"OPENAI_API_KEY": "proxy-managed"
}
EOF
;;
*)
rm -f /home/agent/.codex/auth.json
;;
esac
description: Seed Codex config/auth from SBX_CRED_OPENAI_MODE
env:
- SBX_CRED_OPENAI_MODE
- WORKSPACE_DIR
user: agent
startup:
- command:
- sh
- -c
- |
set -e
[ -n "$MCP_GATEWAY_URL" ] || exit 0
cfg="$HOME/.codex/config.toml"
touch "$cfg"
grep -q "^\[mcp_servers.mcp-gateway\]" "$cfg" && exit 0
esc() { printf '%s' "$1" | sed 's/\\/\\\\/g; s/"/\\"/g'; }
url=$(esc "$MCP_GATEWAY_URL")
auth=$(esc "$MCP_SENTINEL_TOKEN_NAME")
# Codex's grammar for a streamable HTTP server: the transport
# is implied by `url` (a `command` would make it stdio; there
# is no `type` key), and static headers go in `http_headers`.
# A `[...headers]` sub-table is not read, so the gateway
# would be reached without its bearer token and codex would
# warn about both keys at startup.
cat >> "$cfg" <<EOF
[mcp_servers.mcp-gateway]
url = "$url"
http_headers = { Authorization = "Bearer $auth" }
EOF
description: Register the sandbox MCP gateway in ~/.codex/config.toml
env:
- MCP_GATEWAY_URL
- MCP_SENTINEL_TOKEN_NAME
user: agent
- type: com.docker.sandbox/agent-context@1
optional: true
config:
contentFile: /usr/share/sandbox/kit/codex-acp-set/context.md
directory: /home/agent/.codex
filename: AGENTS.md
args:
registry:
default: docker.io/docker
description: Registry namespace the listed kits were pushed to
pattern: ^[a-z0-9][a-z0-9._/:-]*$
buildArg: KIT_REGISTRY
kits:
- ref: docker.io/docker/sbx-kit-shell:1.0.0
digest: sha256:b03fad18cf08261cd1eef0b6ac9f3482c47816086263b7f15e734620e1824a21
- ref: docker.io/docker/sbx-kit-codex-mixin:0.164.0
digest: sha256:00805b8332c12b8db034bdc379848ec31b31b74bfca5123a898a38fcd86f463a
- ref: docker.io/docker/sbx-kit-codex-acp:2.2.2
digest: sha256:5896dc2c5d828c58cd22c912cc660df74d55ffc1594bbcbd5a56c9a9f95b1c50