Docker workspace

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

Where to run this

Every command on this page runs from a clone of the AgentBox repository on the trusted host — never inside the agent workspace. If you haven't cloned it yet, start with the quickstart.

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

Generate TLS for the broker hop

sh scripts/make-dev-cert.sh ~/.agentgate-tls
echo "AGENTGATE_TLS_CERT_PATH=$HOME/.agentgate-tls/broker.crt" >> .env
echo "AGENTGATE_TLS_KEY_PATH=$HOME/.agentgate-tls/broker.key" >> .env
echo "AGENTGATE_CA_PATH=$HOME/.agentgate-tls/ca.crt" >> .env

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>

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. 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.

/workspace and /home/node are named volumes that survive docker compose down. The container defaults to 4 GiB memory (WORKSPACE_MEMORY_LIMIT) and 512 processes.

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/rvasqz86/agentgate:vX.Y.Z \
  --certificate-identity-regexp '^https://github.com/rvasqz86/agentbox/.github/workflows/release.yml@refs/tags/v' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com

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