> ## Documentation Index
> Fetch the complete documentation index at: https://docs.atollhq.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Set up an agent

> Create an agent key, install the CLI or skill package, configure profiles, and verify org-scoped access.

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.

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

## CLI setup

Install the CLI:

```bash theme={null}
npm install -g @atollhq/cli
```

Authenticate:

```bash theme={null}
atoll auth login --key sk_atoll_...
atoll auth status
```

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

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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](/integrations/mcp-server) when the agent runs remotely and cannot use local CLI profiles.

```bash theme={null}
npm install -g @atollhq/mcp-server
PORT=8787 atoll-mcp
```

Remote MCP clients connect to `POST /mcp` and pass:

```http theme={null}
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`:

```bash theme={null}
openclaw skills install atoll
```

```json5 theme={null}
{
  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`.

```bash theme={null}
atoll auth login --profile agent-a --key sk_atoll_... --org-id org-uuid --project project-uuid
```

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

## Verify access

Use an org-scoped endpoint:

```bash theme={null}
: "${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:

```text theme={null}
HTTP:200
```

## Install an Atoll skill

Atoll publishes skill packages for common agent runtimes:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
--project project-uuid
--team team-slug
--base-url https://atollhq.com
--no-project
--no-team
--no-base-url
```