Onboarding a company

GitHub App

Create it with Contents: read and write, Metadata: read, and, for agentgate pr and agentgate ci, Pull requests: read and write and Actions: read. Install it on the repositories agents may touch. Record the App ID and installation IDs. See Connect GitHub.

Signing key in a KMS

Put the App private key in AWS KMS (or your HSM) and grant each developer's role kms:Sign on it and nothing else. Developers' brokers sign with AGENTGATE_KMS_KEY_ID (built in) or AGENTGATE_SIGN_COMMAND; the PEM never exists on a laptop. See KMS signing.

Issuer key

Generate the Ed25519 issuer keypair on an issuing host the platform team controls. Only the public key goes into broker configuration; the private key goes to the issuing service.

Policy, entitlements, egress

Write config.json with identity.mode: "assertion", the issuer public key, the repositories, and rules that requires team membership or a ticket. Wire entitlements to your directory export, GitHub teams, Okta, Entra, Jira, or ServiceNow. Choose an egress allowlist (examples/egress.ide.json if developers attach an IDE). See Policy, Entitlements, Egress proxy.

Model gateway

Put the provider API key in the gateway's secret and set the budget. See Model gateway.

Images

Build and sign the broker image and the workspace profile your developers need (examples/workspace-claude-code.Dockerfile for Claude Code). Publish by digest. See Workspace profiles and Verify release images.

Approvals and the issuer

Stand up compose.enterprise.yaml behind your OIDC provider: approval-web so reviewers approve with a verified identity (set reviewerSources: ["oidc"] on rules that matter), and issuer-web so developers mint their own identities at /issuer/.

Audit

Point the audit forwarder at your SIEM and load the detections. See Audit & monitoring.

Bundle it

Give developers a repository containing compose.yaml, the pinned image digests, config.json, the egress allowlist, the gateway config, the CA for the workspace-to-broker hop, and a .env.example with everything but the per-developer values. Developers run the core compose.yaml only; the SIEM forwarder, approval UI, and issuer run wherever reviewers and the audit pipeline live, and their settings never need to be on a developer's machine.

Clone the bundle

Bootstrap your machine's secrets

npm run bootstrap

This generates your workspace client token (it identifies your workspace to your broker and never leaves your machine), the model-gateway token, and a development CA, and writes their paths into .env. It ends by listing what is still missing: fill in the App ID and key (or KMS) settings and the model key file path from your platform team.

Set your commit identity

AGENTGATE_GIT_NAME and AGENTGATE_GIT_EMAIL in .env.

Bring the stack up and get your fingerprint

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

This prints the SHA-256 of your client token. Paste the fingerprint, never the token, into the issuer with the agent you use, your team, the work mode you need, and the ticket you are working.

Install your runtime assertion

Save the assertion the issuer shows you, point .env at it, and renew:

cp ~/Downloads/runtime-assertion ~/.agentgate-runtime-assertion
echo "AGENTGATE_RUNTIME_ASSERTION_PATH=$HOME/.agentgate-runtime-assertion" >> .env
docker compose up -d workspace
docker compose exec workspace agentgate doctor

doctor shows who you are acting as, when the assertion expires, that it is bound to your token, and that the broker, gateway, and proxy are reachable. Every check must be ok.

Open the workspace in your editor

Reopen in Container from VS Code, Cursor, or Windsurf (IDEs & workspace profiles), or use the terminal:

docker compose exec workspace bash
git clone https://github.com/YOUR-ORG/YOUR-REPO

Work normally

Clone, fetch, push, agentgate pr create, agentgate ci list. A push that policy sends to approval fails with a request ID; a reviewer approves in approval-web; push again.