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 New agent, name the agent, and select its project, Product KPI and automation permissions. Select Change beside the avatar to search built-in icons or upload a JPEG, PNG, WebP, or GIF image up to 2 MB.Search projects by project or product name. Projects are grouped by product; a product group does not grant access. Selected projects stay visible above the results when you search. Use each remove control to remove optional project access, and choose View, Edit or Admin for each project. The current project, when provided by the setup entry point, is required. Project automation permissions are separate from project access.Use Add description for an optional description, or expand Advanced defaults to set local tool defaults. Select Generate API Key to continue.Access determines which Atoll data the agent can reach. Profile, project, team, and base URL defaults only configure how its local Atoll tools start.Use Workforce context to choose the organization inventory (owners/admins), your own agents, or one project that you administer. A project context shows only that project’s agent facts and carries through Detail and Back to Agents. It does not show organization capacity or integrations.The Agents page has one workforce list. Search visible agent or project names, filter by project, and sort by name, latest authenticated use or creation date. Deleted agents are hidden by default. The Lifecycle filter can show deleted history; these controls do not report execution or health state.Select Detail to inspect an authorized agent’s safe identity and access facts, context-visible projects, latest authenticated use, open assigned work, and recent issue-linked Activity. Assignments and authentication evidence do not indicate a running execution. Use the existing links for heartbeat configuration and access/key changes.Expand Manage on an existing agent to replace its icon with another preset or custom image. Custom JPEG, PNG, WebP, and GIF images can be up to 2 MB.
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. The Claude Code, Codex, and Gemini CLI snippets verify the saved profile without a global CLI installation. They run the following command in an isolated child process that clears ambient Atoll credentials and repository context:
The package provides both atoll and atoll-runner, so select atoll explicitly. If an older snippet reports could not determine executable to run, copy a new snippet or use the command above with your profile name. This npm error does not indicate invalid credentials. Command errors retain npm’s diagnostic output; rejected credentials report API key is invalid or expired. 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 shows Authenticated use from an active API key or a non-revoked OAuth profile. This aggregate timestamp does not identify which credential was used. Key prefixes and key controls appear only when your management capability permits them. Authentication timestamps update at most once every 15 minutes and do not show execution or health. Existing OAuth activity is not backfilled. 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. An existing agent can follow its human owner’s current project access when that setting is enabled. This does not inherit organization strategy or administration rights. Explicit project and KPI grants are separate. Read current grants through atoll agent-context --live-permissions or MCP atoll_get_auth_context.

Reconcile agent capacity

Owners and admins can reconcile the shared agent allowance at the top of Agents. The total shows used slots and the finite limit, or Unlimited. The breakdown counts all normal agents and API-key integrations, regardless of search filters. If the counts differ from the billing total, Inventory changed; refresh to reconcile requires a fresh read. Refresh inventory reloads the inventory and capacity together. Agents share one list. Owner-following project access appears as a permission source. A human can change access in place; a preset is not a permanent agent type. The API-key integrations section lists names only. Manage integrations opens the existing Settings > Integrations controls. Use Delete agent for permanent workspace removal; it reloads capacity and retains history. The normal own-agent context has no capacity or integration inventory. Explicit project contexts also omit these organization totals.

Change an agent’s lifecycle

Enabled, Disabled, and Deleted are administration states. They do not report whether a process is running. Each list and detail action appears only when the server grants that specific capability. Project-admin visibility alone grants no lifecycle, key, profile, access, or heartbeat mutation right. Disable invalidates current credentials and preserves history and assignments. Disabled agents still use a slot. Enable requires a fresh key or new OAuth authorization; it restores no old credential and starts no work. Delete agent requires confirmation and is permanent. It keeps identity and history, cancels active execution/attention under the existing rules, and releases the slot. After each request, the page reloads authoritative state. A conflict or uncertain result requires that read before retry. Deleted identities remain available through authorized Detail history with no management actions. In a project context, Manage full project access opens the complete inventory so an access change cannot remove another project by accident. Store or dismiss a one-time replacement key before changing context, filters, detail navigation, or lifecycle.
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:
The atoll skill (1.0.8 and later) declares ATOLL_API_KEY as its OpenClaw primary env, so apiKey is injected as ATOLL_API_KEY and the env values are injected for host agent turns without relying on unrelated global shell state. Earlier versions (atoll 1.0.6 or legacy atoll-api 1.0.22 and earlier) declare no primary env: OpenClaw ignores apiKey and blocks ATOLL_API_KEY under env. Run openclaw skills update atoll to upgrade, then check openclaw skills info atoll lists Primary env: ATOLL_API_KEY. The skill does not require these variables, so it stays available to agents that use an Atoll CLI profile or MCP connection instead. 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: