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

​
Create, install, and connect an agent

In the Atoll web app:
1

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

Install Atoll

Copy the one-time sk_atoll_... key or an install snippet that contains it, then run the personalized snippet where the agent works. The snippet configures the selected profile and performs one read-only auth status request with that exact profile.Copying the key or install snippet records only that local UI action. It does not mean installation or connection succeeded.
3

Connect agent

After the personalized setup sequence runs, keep the Connect step open. Atoll observes the exact key automatically and updates the page when it receives the authenticated request.Connected is authentication evidence, not proof that the agent is online or running. Atoll shows it only when that unrevoked key authenticated a request after it was created; activity from another key for the same agent does not count. Use Check again as bounded recovery if a read fails or the automatic watch expires.
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. After Atoll confirms the connection, use Finish setup. The Agents page keeps credential evidence separate. Key used reports only the active API key’s latest authenticated use. Agent active reports the latest authenticated use from an active API key or a non-revoked OAuth agent profile. Atoll updates each usage timestamp at most once every 15 minutes. Existing OAuth activity is not backfilled, so an OAuth-only agent can show Never until its first authenticated request after this tracking is deployed. Atoll stores the authentication timestamp, not MCP tool names, arguments, prompts, or customer content. 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 Connect 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:
Authenticate:
If the machine works across multiple organizations or agents, use profiles:
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:

​
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:

​
Remote MCP setup

Use the MCP server when the agent runs remotely and cannot use local CLI profiles.
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:
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.
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 and continue the one-time request. Atoll returns automatically only when the existing approval has an active connection with at least one usable profile. If Atoll resets an older incomplete grant, return to OpenAI and run Scan Tools again. The new request lets you 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:
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.
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 used by the personalized setup snippet:
The setup page observes the exact generated or replacement key automatically while Connect is open. Connected means the exact unrevoked key authenticated after creation. It does not mean that the agent is online or running. Use the secondary Check again control to recover from a transient read or a completed watch window. For a direct API-only environment, you can instead use an org-scoped endpoint:
Expected:

​
Install an Atoll skill

Atoll publishes skill packages for common agent runtimes: Install or refresh only the local skill assets and routing hints:
Bare invocation does not inspect or change credentials, profiles, shell files, or runtime auth settings. Use --install-only as an explicit alias for this mode. This remains true when ambient ATOLL_* variables exist. To configure a named profile, use explicit flags:
For intentional environment configuration, add --configure:
The same --configure form applies to the Claude and Gemini packages. Configuration mode supports the optional project, team, and base URL defaults. Profile mode stores credentials and defaults only in the named Atoll CLI profile, does not select that profile globally, and does not write global ATOLL_* credential exports. Use atoll --profile agent-a ... for direct CLI commands. 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:
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: