Most agent tools hand you a blank slate and expect you to figure out the rest. For a freelancer or non-tech owner, that's a dead end. Most just don't have the time or the context to build from zero.
Atoll ships helpers that already know their job. Pick a role (accountant, support agent, social media manager, or define your own) and the helper comes pre-loaded with the right identity, goals, and behavior.
The underlying runtime is unchanged. We just give it a purpose before you ever open it.
Atoll focuses on the operating layer around the agent.
- 🤖 Create helpers with reusable identities, role definitions, and skill/tool context
- 📁 Share files directly with helpers
- 🐳 Provision containered runtimes without hand-wiring every instance
- 🔗 Place helpers in shared or dedicated workspaces
- 💬 Configure Telegram and Discord channels from the same UI
- 🛠 Operate helpers from the browser: chat, logs, health, repair, reconcile, event history
- 🛡 Helpers runs in their own isolated Docker containers with dedicated volumes and networks
| Capability | Description |
|---|---|
| Quick helper setup | Spin up a helper, assign a workspace, and provision a runtime in minutes |
| Identity catalog | Manage reusable business identities and helper presets from the UI |
| Runtime operations | Inspect health, logs, events, repair actions, and reconcile flows |
| Channel wiring | Expose shared messaging settings in the UI and runtime-native advanced settings where semantics differ |
| Single-host | Run locally during development or in Docker Compose for a self-hosted deployment |
 |
 |
 |
- Node.js
20+andnpm - Docker Desktop or another reachable Docker engine
1. Copy the example environment file
cp .env.example .env2. Set required variables in .env
ATOLL_SECRETS_KEY=<long-random-string> # required
ATOLL_LLM_PROVIDER_API_KEY=<your-api-key> # optional to set default3. Install dependencies
npm install4. Start the API and app together
npm run dev5. Open in your browser
For a containerized single-host deployment:
cp .env.example .env # set ATOLL_SECRETS_KEY inside
docker compose up --buildAtoll uses tenants as workspaces.
| Type | Description |
|---|---|
default |
Individual helper workspace for quick setup |
dedicated |
Shared workspace with reusable network and storage context |
A helper is the user-facing agent record: name, avatar, role title, preset, skills, and channel settings.
A runtime is the managed execution environment attached to a helper. Atoll provisions it through Docker, tracks its status, and exposes lifecycle actions through the API and UI.
Reusable identity presets live under src/business-identities and are editable in the /identities screen. These presets seed helper identity, soul, and tools documents.
All important configuration lives in the repo-root .env.
| Variable | Required | Purpose |
|---|---|---|
ATOLL_SECRETS_KEY |
✅ | Encryption key for stored secrets and sensitive runtime config |
ATOLL_LLM_PROVIDER_API_KEY |
Default provider API key when a helper has none | |
PORT |
API port (default 8450) |
|
HOST |
API bind host | |
RUNTIME_PROVIDER |
Default LLM provider for new helpers | |
RUNTIME_MODEL |
Default LLM model for new helpers | |
RUNTIME_HTTP_TIMEOUT_MS |
Runtime HTTP timeout in ms (default 3600000) |
|
RUNTIME_OPENCLAW_IMAGE |
✅ | OpenClaw runtime image |
RUNTIME_ZEROCLAW_IMAGE |
✅ | ZeroClaw runtime image |
RUNTIME_HERMES_IMAGE |
✅ | Hermes runtime image |
RUNTIME_GUI_SIDECAR_IMAGE |
✅ | GUI sidecar runtime image (required when gui.enabled is used) |
RUNTIME_STARTUP_VALIDATION |
Prerequisite validation: strict, warn, or off |
|
RUNTIME_ALLOW_PUBLIC_BIND |
Whether helper gateways bind to host loopback by default | |
RUNTIME_REQUIRE_PAIRING |
Whether pairing is required for supported runtimes | |
ATOLL_CORS_ALLOWED_ORIGINS |
Needed when the web app is on a different origin than the API |
The Settings screen writes managed runtime defaults back to
.env. Changes require an API restart to fully apply.
Runtime image sources:
RUNTIME_OPENCLAW_IMAGE: published image (default in.env.example:zivhm/openclaw).RUNTIME_ZEROCLAW_IMAGE: published image (default in.env.example:zivhm/zeroclaw-runtime).RUNTIME_HERMES_IMAGE: published image (default in.env.example:nousresearch/hermes-agent).RUNTIME_GUI_SIDECAR_IMAGE: local image built fromdocker/runtime-gui-sidecar/Dockerfile(default tag in.env.example:atoll-gui-sidecar).
GUI sidecar runtime options (available on all runtime types):
gui.enabled: create and reconcile a GUI sidecar for the runtime container.
| Route group | Purpose |
|---|---|
/api/healthz |
Health check |
/api/auth/me |
Auth context |
/api/settings/config |
Runtime defaults |
/api/tenants |
Workspace management |
/api/agents |
Helper CRUD |
/api/agent-presets |
Preset catalog |
/api/runtime/catalog |
Available runtime types |
/api/runtime/provision-jobs |
Provision job tracking |
/api/runtime/instances/* |
Lifecycle, chat, diagnostics |
/api/runtime/events |
Event history |
/api/runtime/model-catalog |
LLM model listing |
src/ Fastify API, runtime orchestration, storage, identity presets
src/http/routes/ API route modules
src/business-identities/ Reusable helper identity presets
web/ React/Vite control-plane frontend
landing/ GitHub Pages landing site
scripts/ Development helpers
tests/ API/runtime-focused tests
Dockerfile Production image build
docker-compose.yml Single-host deployment
atoll-state.json Local persisted state file
| Setting | Value |
|---|---|
| Supported runtimes | OpenClaw, ZeroClaw, Hermes |
| Default runtime type | openclaw |
| Default hosted provider | openrouter |
| Default hosted model | anthropic/claude-sonnet-4.6 |
| Long-term direction | Harness/Provider-agnostic runtime support |
The public site is hosted on GitHub Pages, separate from the self-hosted control-plane app.
- Site: https://zivhm.github.io/Atoll-OS/
- Source:
landing/
See LICENSE.