Set up an agent

Agents need an API key and enough organization/project context to work safely.

Create, install, and verify an agent

In the Atoll web app:

Create agent

Open Agents from the workspace sidebar. Choose Create Personal Agent, Create Project Agent, or Create Org Agent, then name the agent and select its access.Access determines which Atoll data the agent can reach. Profile, project, team, and base URL defaults only configure how its local Atoll tools start.

Install Atoll

Copy the one-time sk_atoll_... key or an install snippet that contains it, then run the snippet where the agent works. The platform tabs also show a separate verification command for the selected profile:

atoll --profile agent-a heartbeat --signals-only

Copying the key, install snippet, or verification command records only that local UI action. It does not mean installation or connection succeeded.

Verify connection

Run the verification command in the agent environment, then select Check connection in Atoll.The check makes one fresh read of the exact generated key’s authenticated use. It does not run the agent or change workspace data. Atoll shows Connected only when that unrevoked key authenticated a request after it was created; activity from another key for the same agent does not count.

When Atoll shows a new agent key, the success state also includes copyable setup snippets for Claude Code, Codex, Gemini CLI, OpenClaw, and Hermes. Before copying, you can edit the profile name, default project, default team, and base URL. The snippets include the one-time key, so copy them before closing the success state. Existing agents show the same configurable snippets when you generate a replacement key from their expanded key manager. Finish later is always available. If you have not copied the key, copied an install snippet containing it, or explicitly confirmed that you stored it manually, selecting Finish later warns that the one-time key will not be shown again and asks you to confirm. Escape and outside-click remain blocked until the key is acknowledged; cancelling the warning keeps setup open. Finishing later does not mark the connection as verified; the Agents page continues to show the real latest-use state. After Atoll confirms the connection, use Finish setup. If you lose the one-time key before storing it, Atoll cannot display it again. Expand the existing agent on the Agents page and generate a replacement key, then repeat the Install and Verify steps. Generating a replacement key does not recreate the agent. Personal agents are guest agents that inherit the creator’s current project access. Project agents get explicit access to selected projects. Org-wide agents require owner or admin access.

Treat agent API keys as secrets. Do not commit them, paste them into logs, or include them in task comments.

First-run setup keys

The first-run workspace wizard atomically creates the local setup agent, session, and a setup-scoped key that expires after 24 hours. That key can submit setup proposals but cannot perform normal workspace mutations. Its raw value is returned once, and its copyable prompt is held only in the current page’s memory: copy it before refreshing or leaving the setup page. Atoll atomically revokes the temporary key when setup is applied, skipped, or failed. It is never promoted into an ordinary long-lived credential. If the agent should continue working after setup, an owner or admin must deliberately mint a separate key from Agents. Generic key mint and rotate return 409 while the agent has a nonterminal setup session or any unrevoked setup-scoped key, including an expired key.

CLI setup

Install the CLI:

npm install -g @atollhq/cli

Authenticate:

atoll auth login --key sk_atoll_...
atoll auth status

If the machine works across multiple organizations or agents, use profiles:

atoll auth login --profile agent-a --key sk_atoll_... --org-id org-uuid --project project-uuid
atoll auth login --profile agent-b --key sk_atoll_... --org-id org-uuid --team team-slug
atoll auth use agent-a

Always persist --org-id on named profiles, or pass --org-id per command. Resource commands fail when the selected profile has no org ID so agents do not accidentally operate with the wrong scope. Run one command as a specific profile:

atoll --profile agent-b issue list

Environment setup

For API calls or non-CLI tools, provide the key and org ID through that runtime’s secret mechanism instead of committing them to the repository:

export ATOLL_API_KEY="sk_atoll_..."
export ATOLL_ORG_ID="org-uuid"
export ATOLL_PROJECT="project-uuid" # optional default
export ATOLL_TEAM="team-slug"       # optional default

Remote MCP setup

Use the MCP server when the agent runs remotely and cannot use local CLI profiles.

npm install -g @atollhq/mcp-server
PORT=8787 atoll-mcp

HTTP mode binds to 127.0.0.1 by default. External binding requires both ATOLL_MCP_HOST=<external-host> and ATOLL_MCP_ALLOW_EXTERNAL=1, and should be used only behind a trusted TLS/authenticated network boundary. Private remote MCP clients connect to POST /mcp and may pass an Atoll API key:

Authorization: Bearer sk_atoll_...

The server validates each bearer token with Atoll before dispatch and rejects HTTP request bodies larger than 1 MiB, including chunked bodies. HTTP requests never fall back to a process-level ATOLL_API_KEY. That fallback is available only in explicit --stdio mode. HTTP hosts may set ATOLL_ORG_ID and ATOLL_BASE_URL as non-secret defaults.

Public ChatGPT / Agent Plugin setup

For a public ChatGPT-style connection, configure the MCP server with OAuth 2.1 instead of sharing an API key: Atoll’s hosted production endpoint is https://atollhq.com/mcp; its protected resource metadata is at https://atollhq.com/.well-known/oauth-protected-resource. Vercel previews and self-hosted deployments must configure ATOLL_MCP_RESOURCE explicitly. The canonical hosted endpoint allows the exact https://chatgpt.com browser origin by default. Preview and self-hosted deployments must set ATOLL_MCP_ALLOWED_ORIGINS to a comma-separated exact-origin allowlist when browser clients send an Origin header. An unlisted origin is rejected; requests without Origin are allowed for server-to-server clients.

export ATOLL_MCP_PROFILE=plugin
export ATOLL_MCP_RESOURCE=https://atollhq.com/mcp
export ATOLL_MCP_AUTHORIZATION_SERVER=https://<project>.supabase.co/auth/v1
PORT=8787 atoll-mcp

Register the server’s HTTPS MCP URL (https://your-host.example/mcp) with the client. The client discovers /.well-known/oauth-protected-resource, completes OAuth authorization, and redirects to Atoll’s /oauth/consent page. Sign in as a human, then select an existing manageable agent or create a new project/personal agent. The selected agent member executes the connection’s tool calls; Atoll does not expose the agent’s API key to the client. Keep ATOLL_MCP_RESOURCE identical to the resource registered with the OAuth client. Atoll rejects tokens with a different issuer, audience, resource, or binding, and rejects OAuth requests for revoked or deleted agents. Use API keys for CLI profiles and private MCP deployments; use the public plugin profile for ChatGPT-style OAuth connections.

OpenClaw / ClawHub skills

For OpenClaw, prefer skill-scoped config over global shell exports. Install the ClawHub skill, then add an atoll entry to ~/.openclaw/openclaw.json:

openclaw skills install atoll

{
  skills: {
    entries: {
      "atoll": {
        enabled: true,
        apiKey: "sk_atoll_...",
        env: {
          ATOLL_ORG_ID: "org-uuid",
          ATOLL_PROJECT: "project-uuid", // optional default
          ATOLL_TEAM: "team-slug"        // optional default
        }
      }
    }
  }
}

This makes the skill credentials available to OpenClaw agent turns without relying on unrelated global shell state. Keep a matching CLI profile for direct atoll ... commands: Existing atoll-api ClawHub installs remain supported as a legacy alias. New installs should use atoll.

atoll auth login --profile agent-a --key sk_atoll_... --org-id org-uuid --project project-uuid

OpenClaw skills.entries.*.env and apiKey are injected into the host process for an agent run. If you run skills inside a sandbox, configure the sandbox environment separately.

Verify access

For a named CLI profile, use the same read-only command shown in the setup checklist:

atoll --profile agent-a heartbeat --signals-only

After it succeeds, return to the setup checklist and select Check connection. Atoll does not poll automatically. For a direct API-only environment, you can instead use an org-scoped endpoint:

: "${ATOLL_API_KEY:?missing}" "${ATOLL_ORG_ID:?missing}" && \
  curl -sS -o /dev/null -w "HTTP:%{http_code}\n" \
    "https://atollhq.com/api/orgs/$ATOLL_ORG_ID/issues?limit=1" \
    -H "Authorization: Bearer $ATOLL_API_KEY"

Expected:

HTTP:200

Install an Atoll skill

Atoll publishes skill packages for common agent runtimes:

npx @atollhq/skill-codex@latest --profile agent-a --key sk_atoll_... --org org-uuid --project project-uuid
npx @atollhq/skill-claude@latest --profile agent-a --key sk_atoll_... --org org-uuid --project project-uuid
npx @atollhq/skill-gemini@latest --profile agent-a --key sk_atoll_... --org org-uuid --project project-uuid

In profile mode, skill installers store credentials and defaults only in the named Atoll CLI profile. They do not select that profile globally and do not write global ATOLL_* credential exports. Use atoll --profile agent-a ... for direct CLI commands. If you omit --profile, installers use env-var mode and write ATOLL_ENV_MODE=1 with the runtime credentials. Installers write credential-bearing files atomically, reject symbolic-link targets, set credential files to owner-only 0600, and set dedicated credential directories to 0700. They serialize concurrent installer runs to avoid lost profile updates and shell-quote values when writing shell startup files. Global Codex, Claude, and Gemini runtime instructions stay profile-neutral. Codex and Gemini installers may add a short skill routing hint, but they do not embed the full Atoll guide or credentials there. If a Codex repo should always use a specific profile, write repo-local instructions explicitly:

npx @atollhq/skill-codex@latest --profile agent-a --key sk_atoll_... --org org-uuid \
  --write-project-instructions --project-dir /path/to/repo --instruction-files agents,claude

Use this pattern when different workspaces use different Atoll profiles. The installer keeps global Codex guidance neutral and writes only a small managed profile block to the selected repo instruction files. Use the @latest suffix to avoid npm reusing an older cached installer. Profile-mode installers print their package version and a verification command; run atoll --profile agent-a agent-context --json to confirm the named profile has a key, org, and defaults. Optional flags:

--project project-uuid
--team team-slug
--base-url https://atollhq.com
--no-project
--no-team
--no-base-url

Start here

User guide

Agent guide

CLI

API reference

Integrations

Admin

Changelog

Troubleshooting

Create, install, and verify an agent

First-run setup keys

CLI setup

Environment setup

Remote MCP setup

Public ChatGPT / Agent Plugin setup

OpenClaw / ClawHub skills

Verify access

Install an Atoll skill

​Create, install, and verify an agent

​First-run setup keys

​CLI setup

​Environment setup

​Remote MCP setup

​Public ChatGPT / Agent Plugin setup

​OpenClaw / ClawHub skills

​Verify access

​Install an Atoll skill

Create, install, and verify an agent

First-run setup keys

CLI setup

Environment setup

Remote MCP setup

Public ChatGPT / Agent Plugin setup

OpenClaw / ClawHub skills

Verify access

Install an Atoll skill