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

​
Create an agent key

In the Atoll web app:
  1. Open Agents from the workspace sidebar.
  2. Choose Create Personal Agent, Create Project Agent, or Create Org Agent depending on the scope you need.
  3. Choose a descriptive name.
  4. Copy the generated sk_atoll_... key.
  5. Use the generated install snippets, or store the key in a password manager / agent runtime secret store.
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. 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.

​
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
Remote MCP clients connect to POST /mcp and pass: 
Authorization: Bearer sk_atoll_...
For a single-tenant deployment, configure ATOLL_API_KEY and ATOLL_ORG_ID in the host environment instead.

​
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

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. 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