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.
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.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 return409
while the agent has a nonterminal setup session or any unrevoked setup-scoped
key, including an expired key.
CLI setup
Install the CLI:--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.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:
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 ishttps://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.
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 anatoll entry to ~/.openclaw/openclaw.json:
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:
atoll-api ClawHub installs remain supported as a legacy alias. New installs should use atoll.
Verify access
For a named CLI profile, use the same read-only command used by the personalized setup snippet:Install an Atoll skill
Atoll publishes skill packages for common agent runtimes: Install or refresh only the local skill assets and routing hints:--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:
--configure:
--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:
@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:

