ZeroRoot Docs

Install

Sign up, install the gibson CLI, point it at your Gibson tenant, and verify the connection.

This page connects your workstation to Gibson. Gibson is a hosted service. There is nothing to install on the server side.

The ADK is your entry point. One repository, zeroroot-ai/adk, ships the gibson binary and everything that it scaffolds. You do not need to clone the SDK, install protoc, or set up proto tooling yourself. The SDK is a dependency of your components. gibson component init writes a working buf.yaml and buf.gen.yaml into the directory that it creates.

Prerequisites

ToolWhy
Go 1.26+Builds the CLI and your components. The ADK pins the exact version in gibson/go.mod
DockerOptional, only if you will run plugins as pods

That is the whole list. No protoc, no separate SDK checkout.

1. Sign up for a Gibson tenant

Go to zeroroot.ai and create an account. Gibson provisions your tenant automatically. You are the owner of the tenant. See Signup for each step.

Trial accounts include 14 days of full platform access. See zeroroot.ai/pricing.

2. Get the CLI from the ADK

Clone the ADK and build it. This is the preferred path. You get the CLI, the mission templates, and the scaffolding that the AI-coding workflow uses, all at one commit.

git clone https://github.com/zeroroot-ai/adk.git
cd adk
make build
export PATH="$PWD/gibson/bin:$PATH"

make build compiles gibson/bin/gibson. Run make bootstrap once for the pinned developer tools.

Build from the clone. Installing only the binary leaves behind the mission templates, the toolchain pin and the scaffolder. The scaffolder writes CLAUDE.md, AGENTS.md and a component prompts/ folder. An AI coding workflow depends on those files.

Verify:

gibson --help

You should see the top-level command groups: init, login, logout, component, agent, mission, target, inspect, and docs.

3. Point at your tenant

Run gibson init once per workspace. It writes .gibson/workspace.yaml. This file pins the platform URL so that you do not pass the URL on every command:

gibson init --gibson-url https://api.zeroroot.ai

Use --global to write ~/.gibson/workspace.yaml instead. Then every directory shares one default. The CLI and the SDK also accept GIBSON_URL from the environment. When set, GIBSON_URL overrides the workspace file.

4. Sign in

Authenticate the CLI as yourself with gibson login. It runs the OAuth 2.0 Device Authorization Grant. The CLI prints a URL and a short code. You approve in a browser, and the CLI stores the session at ~/.gibson/auth/credentials (mode 0600). Every later gibson command then acts as you. The session refreshes silently.

gibson login

The CLI discovers the identity issuer from the platform automatically. Run gibson logout to end the session.

5. Enroll a component

Enrollment mints a single-use bootstrap token for a machine identity. Every kind (agent, tool, plugin) enrolls the same way. The token is the only credential that the component needs to bootstrap. There is no client secret anywhere.

Get the token from the deploy wizard in the dashboard. You can also mint one with the CLI:

gibson agent enroll --name my-first-agent --kind agent

The CLI prints the token once. The token expires in 24 hours. Set two environment variables, then start the component:

export GIBSON_URL=https://<your-platform>
export GIBSON_BOOTSTRAP_TOKEN=<bootstrap-token>
make run

GIBSON_URL is the address of your platform. make run starts a component that gibson component init scaffolded. For any other component, start its binary. No register command exists, and the component needs no manifest file.

The first start runs the capability-grant handshake. The component consumes the token and writes an Ed25519 host key and a runtime credential under ~/.gibson/ at mode 0600. Later starts use these files and do not read the token. Treat both files like private keys. They identify your component to Gibson.

If enrollment fails, see Component bootstrap & auth for the layered checks.

6. Verify with inspect

gibson inspect              # auto-detects the local credential
gibson inspect --kind agent --name my-first-agent
gibson inspect --json       # raw output, scriptable

inspect reads your local runtime credential and calls Gibson's identity service. Then it prints who you are and the permissions that you hold. If inspect succeeds, your credential is healthy and you can continue.

What is next

  • Getting Started. The 15-minute walkthrough from zero to a running agent.
  • Your First Agent. Write and ship an agent with the SDK.
  • Plugins. Build a stateful integration with secret bindings.

Storing credentials safely

Credential files live in ~/.gibson/. The component restricts them to mode 0600. Do not commit them. For CI and production deployments:

  • Headless runtimes: do not write files. Pass the runtime credential as GIBSON_AGENT_KEY (the base64-encoded credential) and the daemon endpoint as GIBSON_URL. Source both values from a secret. The SDK reads them automatically. This is the same for every component kind.
  • Fresh runtime instances: put the host key into the deployment artifact, or register again on each instance with a newly issued bootstrap token.
  • Workload identity: if your runtime exposes a workload-identity socket, the SDK detects the socket automatically and uses mTLS with the bearer credential. No extra configuration is needed.

Multi-environment setups

You can operate against more than one Gibson tenant (for example staging and production). If you do, point GIBSON_URL at the correct tenant per shell session or per CI job. Keep the credentials separate. Set GIBSON_HOME to a distinct config directory per tenant. In headless runtimes, you can supply a per-tenant GIBSON_AGENT_KEY instead.

On this page