Quickstart

Two ways in: the five-minute start brings up the real isolated stack on your machine; the demo needs nothing but Git.

Five-minute start

Requires Docker with Compose. You need a GitHub App from your platform team (App ID and key, or a KMS key) and a model provider key file; everything else is generated for you.

Install

npm install -g @nokeys/agentbox   # any OS with Node 22.14 or newer

Or take a build from the release page, which needs no Node: agentbox_<version>_amd64.deb for Debian and Ubuntu (sudo apt install ./agentbox_<version>_amd64.deb), or the agentbox-linux-x64, agentbox-darwin-arm64, and agentbox-windows-x64.exe executables. Every asset is listed in SHA256SUMS, and the npm package is published with provenance.

Each one puts the agentbox command on your PATH.

Note

Homebrew and winget are not published yet: each release builds the formula and the manifests, but neither has been submitted to its catalogue, so brew install and winget install do not work today.

Create a project

mkdir my-agent && cd my-agent
agentbox init

This generates the per-machine secrets the core stack needs (workspace client token, model-gateway client token, a development CA and broker certificate, all owner-only under ~/.agentgate), writes their paths into .env, creates config.local.json from the example and a .devcontainer for your editor, and prints exactly which settings still need your platform team. Rerunning keeps existing secrets.

Fill in what only your platform team has

Add GITHUB_APP_ID, GITHUB_PRIVATE_KEY_PATH (or AGENTGATE_KMS_KEY_ID), ANTHROPIC_API_KEY_PATH, AGENTGATE_GIT_NAME, and AGENTGATE_GIT_EMAIL to .env. Edit config.local.json: replace YOUR-ORG/YOUR-REPO in every rule with your repository, ID, and installation ID.

Bring the stack up

agentbox up
agentbox doctor        # every check must be ok
agentbox fingerprint   # send this to whoever issues your identity
agentbox assertion ~/Downloads/runtime-assertion   # install what they send back; same command to renew

agentbox check reports everything still missing at once, and agentbox up runs it first. Behind a corporate proxy, or where only verified images may run, see Enterprise networks.

Open it in your editor

Open the project directory in VS Code, Cursor, or Windsurf and choose Reopen in Container; agentbox init wrote the .devcontainer for it. The editor's terminal, Git, and agent commands run inside the isolated workspace. See IDEs & workspace profiles.

For the two-role rollout at a company, read Onboarding a company.

The credential-free demo

Requires Linux or macOS and Git. No GitHub account is needed.

agentbox demo

1. Cloned through AgentBox without a provider credential.
2. Policy allowed a push to agent/demo.
3. Push to main blocked. Approval: 3f0c…
4. Host approval granted; the retried push reached main.
5. Approval consumed. Audit events recorded. Temporary demo data will be removed.

The demo creates a temporary local Git server, clones through the broker, pushes an allowed agent/demo branch, blocks a push to main, simulates approval from the host, and retries. It removes its temporary repositories and audit files on exit.