Docker workspace

An isolated development container where agents work without credentials or a route to the internet.

Core and enterprise stacks

compose.yaml is the core stack one developer runs: the broker, the isolated workspace, the egress proxy, and the model gateway. It needs only its own eight settings (GitHub App, key, client token, TLS files, gateway token, model key).

compose.enterprise.yaml layers on the audit forwarder, the OIDC approval UI, the issuing service, and oauth2-proxy, and is where the SIEM and identity-provider settings are required:

docker compose -f compose.yaml -f compose.enterprise.yaml up -d --build

Without it, approvals come from the host CLI, and rules that require reviewerSources: ["oidc"] cannot be satisfied because agentd holds no approval-web admin secret.

Topology

The workspace joins only an internal network. The broker also has an upstream network and exposes no host port. Only the broker receives the private key, configuration, state volume, and admin socket.

Security

Never mount the Docker socket, host credentials, or broker state into the workspace.

Start it

Bootstrap in one command

npm run bootstrap

Generates the workspace client token, the model-gateway client token, and a development CA and broker certificate (all owner-only under ~/.agentgate), writes their paths into .env without duplicating lines, copies examples/config.json to config.local.json if absent, and prints exactly which settings still need your platform team. Rerunning keeps existing secrets. The manual equivalent for TLS is sh scripts/make-dev-cert.sh ~/.agentgate-tls and the three AGENTGATE_TLS_CERT_PATH, AGENTGATE_TLS_KEY_PATH, AGENTGATE_CA_PATH lines.

Bring up the stack

docker compose up --build -d
docker compose exec workspace agentgate doctor

Work inside

docker compose exec workspace bash
git clone --recurse-submodules https://github.com/OWNER/REPO.git

Approve from the host

docker compose exec agentd node src/cli.js list
docker compose exec agentd node src/cli.js approve <request-id>

The broker runs as UID 1000; its key file must be readable by that UID inside the container. /workspace and /home/node are named volumes that survive docker compose down; docker compose down -v deletes them.

Signing with AWS KMS

The broker has a built-in KMS signer (SigV4 over HTTPS, no AWS CLI or SDK in the image). Import the App's RSA key into KMS, or generate it there and register its public key with GitHub, grant the broker's role kms:Sign on that one key, set AGENTGATE_KMS_KEY_ID (an ARN infers the region; otherwise set AWS_REGION), and layer compose.kms.yaml first:

docker compose -f compose.yaml -f compose.kms.yaml up -d --build agentd
docker compose -f compose.yaml -f compose.kms.yaml -f compose.enterprise.yaml up -d --build

Credentials are resolved in order from EKS Pod Identity or an ECS task role (AWS_CONTAINER_CREDENTIALS_FULL_URI and its token file), IRSA web identity (AWS_ROLE_ARN with AWS_WEB_IDENTITY_TOKEN_FILE), then static keys, and cached until shortly before expiry. Credentials, request bodies, and KMS responses are never logged; a failure is SIGNER_FAILED. agentd refuses to start if GITHUB_PRIVATE_KEY_PATH and AGENTGATE_KMS_KEY_ID both reach it, which is why the override replaces agentd's environment and secrets entirely and must come before compose.enterprise.yaml. GITHUB_PRIVATE_KEY_PATH must still name an existing placeholder such as /dev/null for compose.yaml's own interpolation.

For another HSM or cloud KMS, AGENTGATE_SIGN_COMMAND runs any program that reads the signing input on stdin and writes a raw RSASSA-PKCS1-v1_5 SHA-256 signature; examples/sign-with-aws-kms.sh shows the shape.

Validate the host

Before trusting a host with untrusted workloads:

docker compose run --rm workspace agentgate-egress-check

It verifies the workspace can't reach GitHub, the internet, cloud metadata, or the host gateway; holds no GitHub credentials or private key material; has no Docker socket or effective capabilities; can't resolve external DNS; and can reach the broker and an allowlisted registry through the proxy, while the proxy refuses non-allowlisted hosts, GitHub, and IP literals. Every probe fails closed. Exit 1 should block deployment.

Git routing

Startup manages ~/.config/agentgate/gitconfig, included from ~/.gitconfig. It rewrites GitHub HTTPS, SCP-style SSH, and SSH URLs to the broker, with or without .git. Recursive submodules work when every referenced repository is configured and allowed. No SSH key is needed. Set AGENTGATE_GIT_NAME and AGENTGATE_GIT_EMAIL in .env for commit identity.

What's installed

Git, Git LFS, GitHub CLI, SSH, GnuPG, Node/npm, Python/pip/venv, C/C++ build tools, ripgrep, jq, curl, wget, archive tools, nano, vi, and tmux. The container defaults to 4 GiB memory (WORKSPACE_MEMORY_LIMIT) and 512 processes. AI tools such as Claude Code come from a derived image; see IDEs & workspace profiles.

Verify release images

Tagged releases publish images with an SPDX SBOM, SLSA provenance, and a keyless cosign signature. Each digest is Trivy-scanned before it's tagged.

cosign verify ghcr.io/nokeys-dev/agentgate:vX.Y.Z \
  --certificate-identity-regexp '^https://github.com/nokeys-dev/agentbox/.github/workflows/release.yml@refs/tags/v' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com

Deploy by digest (image: ghcr.io/nokeys-dev/agentgate@sha256:…) so what runs is exactly what was scanned and signed.