Getting Started

This is the fast path: account → CLI → component → mission. If you get stuck, go to the linked deep-dive page. If not, continue.

1. Sign up and install the CLI

If you have not done this already, follow Install to:

• create a tenant at zeroroot.ai,

• and get the gibson binary from the ADK. The ADK is the one repository that you clone:

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

Point the CLI at the platform once per workspace. gibson init writes .gibson/workspace.yaml. This file pins the platform URL so that you do not repeat the URL on every command:

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

2. Sign in

Authenticate the CLI as yourself with the device flow. gibson login 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

Open https://app.zeroroot.ai/device and enter code: BDRX-WXKQ
Waiting for approval... signed in as you@example.com

The CLI discovers the identity issuer from the platform automatically. To end the session, run gibson logout.

3. Scaffold and enroll an agent

Scaffold a component directory, then enroll a machine identity for it. Enrollment mints a single-use bootstrap token. This token is the one credential that your agent needs to bootstrap itself. There is no client secret to manage anywhere.

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

enroll prints the bootstrap token to stdout. Copy it now. The CLI shows the token once, and the token expires in 24 hours. Exchange the token for a persistent runtime credential:

gibson component register --token <bootstrap-token>

register runs the capability-grant handshake. It writes the host key and the runtime credential under ~/.gibson/agent/ (mode 0600). Then it verifies the credential against Gibson's identity service. If verification fails, see Component bootstrap & auth → Troubleshooting a 401.

4. Verify with inspect

gibson inspect             # auto-detects the local credential

You should see your agent's identity, the tenant that it belongs to, and its current permissions. If inspect works, you are ready to build.

5. Build your agent

In a new Go module:

mkdir my-first-agent && cd my-first-agent
go mod init example.com/my-first-agent
go get github.com/zeroroot-ai/sdk/agent@latest
go get github.com/zeroroot-ai/sdk/llm@latest

Create main.go:

package main

import (
    "context"
    "log"

    "github.com/zeroroot-ai/sdk/agent"
    "github.com/zeroroot-ai/sdk/llm"
)

func main() {
    cfg := agent.NewConfig().
        SetName("my-first-agent").
        SetVersion("0.1.0").
        SetDescription("Says hi via the primary LLM slot.").
        AddCapability("greeting").
        AddTargetType("none").
        AddLLMSlot("primary", llm.SlotRequirements{}).
        SetExecuteFunc(func(ctx context.Context, h agent.Harness, t agent.Task) (agent.Result, error) {
            resp, err := h.Complete(ctx, "primary", []llm.Message{
                {Role: llm.RoleSystem, Content: "Greet warmly in one sentence."},
                {Role: llm.RoleUser, Content: t.Prompt},
            })
            if err != nil {
                return agent.NewErrorResult(err), nil
            }
            return agent.NewSuccessResult(resp.Content), nil
        })

    a, err := agent.New(cfg)
    if err != nil {
        log.Fatal(err)
    }

    if err := agent.Serve(context.Background(), a); err != nil {
        log.Fatal(err)
    }
}

Run it:

go run .

The agent connects to your tenant and waits for work. Do not stop it.

6. Run a mission

Open the dashboard's Missions section (/dashboard/missions/new) and create a one-node mission:

1. Target: pick or create a target. For a hello-world, if your agent does not need a target, the target can be none.
2. Add a node: set the type to Agent, point it at my-first-agent, and set a prompt like "Greet a new Gibson user.".
3. Run.

The mission detail page streams events live. You see mission.started, then node.started. Your agent's output appears as node.finished. The mission ends with mission.completed. See Missions for the full lifecycle.

You can also write a mission as a file and submit it from the CLI:

gibson mission submit missions/recon.yaml --target example.com

The mission loader detects the file format from the extension. It supports .cue, .yaml, .yml, and .json. Use the format that your team prefers.

7. Where to go next

You want to…	Read
Add a tool your agent can call	Tools
Connect a stateful integration	Plugins
Store and rotate credentials	Secrets management
Auto-populate the knowledge graph from tool output	Knowledge graph
Submit and triage findings	Findings
Wire your agent into CI / production	the Makefile produced by gibson component init --kind plugin is the canonical template

If you get stuck, the Component bootstrap & auth page covers the common 401 paths. The CLI reference lists every gibson command.