Autosclaw
Autonomous AI Agent Orchestration Platform
Ask AI about Autosclaw
Powered by Claude Β· Grounded in docs
I know everything about Autosclaw. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
Autonomous AI Agent Orchestration Platform
Spawn, schedule, and orchestrate autonomous Claude-powered agents β each in its own Docker container β from a real-time web dashboard.
Table of Contents
- What is autosclaw?
- Core Functionality
- Architecture
- Getting Started (AI-Assisted Setup)
- Configuration
- How It Works
- Security
- API Reference
- Tech Stack
- Project Structure
- Contributing
- License
What is autosclaw?
autosclaw is a self-hosted platform that turns Claude into an army of autonomous agents. Each agent runs in its own isolated Docker container with full tool access β they can write code, browse the web, manage files, interact with GitHub, and even spawn other agents to delegate work.
From the real-time web dashboard, you watch agents think, act, and collaborate. You see every tool invocation, every token spent, every dollar of cost β live. Schedule agents to run on cron expressions for recurring tasks like daily reports, repository maintenance, or automated code reviews. Or spawn them on-demand and let them loose.
What makes autosclaw unique is its multi-agent orchestration: agents aren't isolated workers β they're a network. Any agent can spawn, list, and manage other agents through MCP tools, enabling complex multi-step workflows where agents coordinate, delegate, and build on each other's work. All while you watch from a single pane of glass.
Core Functionality
Autonomous AI Agents
Each agent gets its own Docker container running Claude Opus 4.6 with the full Claude Code toolset:
- Code execution β Bash, file read/write/edit, glob, grep
- Web access β web search, web fetch, browsing
- Development tools β Git, GitHub CLI (
gh), plan mode, worktrees - Agent orchestration β spawn sub-agents, manage schedules, delegate work
- Human-in-the-loop β agents can pause and ask you questions mid-task, then continue with your answer
Multi-Agent Orchestration via MCP
Agents form an interconnected network through 10 MCP (Model Context Protocol) tools:
| Tool | Description |
|---|---|
spawn_agent | Spawn a child agent with inherited permissions |
list_agents | List all running agents (with isSelf flag) |
despawn_agent | Stop an agent (cannot despawn self) |
create_schedule | Create a cron-based recurring or one-time schedule |
list_schedules | List all schedules |
get_schedule | Get details of a specific schedule |
update_schedule | Modify an existing schedule |
pause_schedule | Pause an active schedule |
resume_schedule | Resume a paused schedule |
delete_schedule | Soft-delete a schedule |
Key design decisions:
- Recursive spawning β agents spawn children, which spawn grandchildren, and so on
- Permission inheritance β child agents automatically inherit their parent's permissions
- Safety guardrails β agents cannot despawn themselves or agents already stopping
Real-Time Dashboard
A React 19 progressive web app that streams everything live over WebSocket:
- Live output β watch agent text, collapsible thinking blocks, and system messages as they happen
- Tool cards β structured display of every tool invocation with syntax-highlighted inputs and diffs
- Interactive chat β jump into any running agent's session at any time to provide guidance, course-correct, or give additional instructions mid-task
- Ask-user flow β agents can pause for user input; you get a push notification and see selectable options in the dashboard
- Sortable tables β sort agents and schedules by any column (name, status, tokens, cost)
- Bulk actions β select multiple agents and stop them in one click
- Agent history β browse output and tool logs for stopped or deleted agents
- PWA support β installable on mobile/desktop, push notifications, offline-ready service worker
Cron Scheduling
Automate recurring work with cron-powered scheduling:
- Recurring schedules β standard 5-field cron expressions (UTC timezone)
- One-time schedules β fire once and auto-delete
- Pause / resume β temporarily disable schedules without deleting them
- Custom agent config β each schedule defines the spawned agent's name, purpose, and system prompt
- Permission scoping β schedules inherit the creator's permissions
- 30-second tick β the scheduler checks and fires every 30 seconds
Cost & Token Tracking
Full visibility into what your agents are spending:
- Per-agent breakdown β input tokens, output tokens, cache read, cache creation, and USD cost
- Live updates β token counters update in real-time as agents work
- Usage dashboard β paginated table of all agents sorted by cost, with totals
- Summary cards β at-a-glance totals for running agents, total agents, and schedules
Role-Based Access Control
Three roles with granular permissions:
| Role | Capabilities |
|---|---|
| Admin | Full control: manage all agents, schedules, users, reload service |
| Member | Create and manage your own agents and schedules |
| Viewer | Read-only access to the dashboard |
Agents also receive granular permissions (agent:spawn, agent:schedule) that propagate down the hierarchy to child agents.
Architecture
autosclaw consists of three main components: the Manager (host process), Agent containers (Docker), and the Dashboard (React UI). They communicate over WebSocket for real-time streaming and REST for control operations.
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β Web Dashboard (React 19 + Vite) β
β β
β Live output streaming Sortable agent/schedule tables β
β Tool invocation cards Token & cost tracking β
β Interactive chat Push notifications (PWA) β
β Role-based UI Ask-user question flow β
βββββββββββββββββββββββββββββββ¬βββββββββββββββββββββββββββββββββββββββββ
β WebSocket (/ws) β JWT authenticated
βΌ
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β MANAGER (Host) β
β β
β ββββββββββββββ βββββββββββββββ βββββββββββββββ ββββββββββββββ β
β β Express 5 β β WebSocket β β SQLite DB β β Cron β β
β β REST API β β Servers β β (WAL mode) β β Scheduler β β
β β β β β β β β β β
β β /api/spawn β β /ws (UI) β β β’ agents β β 30s tick β β
β β /api/agents β β /agent β β β’ messages β β recurring β β
β β /api/despawnβ β (agents) β β β’ users β β one-time β β
β β /api/sched. β β β β β’ schedules β β auto-spawn β β
β β /api/push β β Broadcast β β β’ config β β β β
β β /api/health β β to watchers β β β’ push_subs β β β β
β ββββββββββββββ ββββββββ¬βββββββ βββββββββββββββ ββββββββββββββ β
β β β
β SECURITY LAYER β Docker CLI: docker run / stop / rm β
β βββ JWT auth (bcrypt + 24h tokens) β
β βββ Per-agent hex tokens (timing-safe comparison) β
β βββ RBAC (admin / member / viewer) β
β βββ Secrets via stdin (never on disk or in env vars) β
β βββ Post-startup secret scrubbing from process.env β
β β
β RESILIENCE β
β βββ 30s health check reconciliation loop β
β βββ Orphan container detection and cleanup β
β βββ Graceful shutdown (15s timeout β force exit) β
β β
ββββ¬ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β
β WebSocket (/agent) + secrets via stdin
βΌ
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β DOCKER CONTAINERS β
β β
β ββββββββββββββββββββ ββββββββββββββββββββ ββββββββββββββββββββ β
β β Agent #1 β β Agent #2 β β Agent #N β β
β β β β β β β β
β β Claude Agent SDK β β Claude Agent SDK β β Claude Agent β β
β β (Opus 4.6) β β (Opus 4.6) β β SDK (Opus 4.6) β β
β β β β β β β β
β β Built-in tools: β β MCP tools: β β Permissions β β
β β Bash, Read, β β spawn_agent β β inherited from β β
β β Write, Edit, β β list_agents β β parent β β
β β Grep, Glob, β β despawn_agent β β β β
β β WebSearch, β β schedule CRUD β β git, gh CLI β β
β β WebFetch, Agent β β (7 tools) β β β β
β ββββββββββββββββββββ ββββββββββββββββββββ ββββββββββββββββββββ β
β β² β² β² β
β βββββββββββββββββββββββ΄ββββββββββββββββββββββ β
β Agent-to-Agent Orchestration β
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
Component Responsibilities
Manager (manager/src/) β the central orchestrator running on the host:
| Module | Responsibility |
|---|---|
main.ts | Express app init, Docker image build, agent restoration on startup, 30s health check loop, graceful shutdown |
api.ts | REST API routes for spawning/despawning agents and schedule CRUD, dual auth (JWT + agent tokens) |
auth.ts | User registration/login, JWT generation/verification, password hashing (bcryptjs), role management |
communication.ts | Two WebSocket servers β /ws for the dashboard and /agent for agent containers β message routing, permission checks, project management |
containers.ts | Docker container lifecycle: image building, agent spawning (with stdin secret delivery), stopping, orphan cleanup |
db.ts | SQLite schema and CRUD for agents, messages, schedules, users, projects, and config (WAL mode, soft deletes) |
schedules.ts | Cron scheduler: 30-second tick loop, next-run computation, auto-spawn on match, one-time schedule cleanup |
push.ts | Web Push notifications via VAPID keys for agent completion, errors, input requests, and schedule triggers |
logger.ts | Structured JSON logging with file rotation (10 MB max, 5 files) |
Agent (agent/src/) β runs inside each Docker container:
| Module | Responsibility |
|---|---|
main.ts | Entrypoint: reads secrets from stdin, creates MCP server with 10 tools, runs Claude Agent SDK session, scrubs secrets from process.env |
manager-client.ts | WebSocket client to manager: registration, output/token/tool-use streaming, ask-user flow, spawn requests (60s timeout) |
types.ts | SDK message type helpers for display formatting |
Dashboard (manager/ui/src/) β React 19 single-page app:
| Module | Responsibility |
|---|---|
context/AppContext.tsx | Global state (agents, schedules, projects, outputs) via React Context + Reducer, WebSocket connection lifecycle |
hooks/ | useAuth (JWT mgmt), useAutoScroll (smart scrolling), useConfirmDialog, usePushNotifications, useTableSort |
components/dashboard/ | Main view: SummaryCards, AgentTable, ScheduleTable, AgentUsageTable, ProjectsPanel |
components/agent/ | Agent detail: OutputArea (text/thinking), ToolCard (syntax-highlighted), ChatBar, TokenBar, AskUserCard |
components/modals/ | NewAgentModal (spawn form), NewScheduleModal (cron config), ConfirmDialog |
Communication Protocol
Agent β Manager (WebSocket /agent):
| Direction | Message Type | Purpose |
|---|---|---|
| Agent β Manager | register | Authenticate with agent ID and token |
| Agent β Manager | output | Text output (text, thinking, result, system) |
| Agent β Manager | tool_use | Tool invocation details |
| Agent β Manager | tokens | Token usage and cost update |
| Agent β Manager | spawn_agent | Request to spawn a child agent |
| Agent β Manager | ask_user | Pause and request user input |
| Manager β Agent | chat | Message from user via dashboard |
| Manager β Agent | ask_user_response | User's answer to a pending question |
| Manager β Agent | close | Shutdown order |
Dashboard β Manager (WebSocket /ws): The manager broadcasts agent_list and schedule_list on every state change, and streams output, tool_use, tokens, and ask_user events in real-time to watchers.
Data Model
SQLite (WAL mode) with the following tables:
| Table | Key Fields |
|---|---|
agents | id, name, token, purpose, system_prompt, cost_usd, input/output/cache tokens, status, permissions, project_id |
messages | agent_id, role, msg_type (text/tool_use), text, metadata (JSON) |
schedules | id, name, cron_expression, schedule_type (recurring/once), agent config, status, next_run_at |
users | id, username, password_hash, role (admin/member/viewer) |
projects | id, name, purpose, github_token |
config | key/value pairs (VAPID keys, etc.) |
push_subscriptions | endpoint, keys_p256dh, keys_auth |
All deletions are soft deletes (preserving audit history).
Getting Started (AI-Assisted Setup)
autosclaw includes an AI-assisted setup experience powered by a Claude Code custom skill. Instead of manually configuring environment variables and running build steps, Claude walks you through the entire process interactively β checking prerequisites, generating secrets, and configuring everything for you.
Prerequisites
- Node.js 22+
- Docker (running and accessible)
- GitHub CLI (
gh) (install) - Anthropic API Key (get one here)
- Claude Code (install)
Setup
- Clone the repository
gh repo clone BreuerFlorian/autosclaw
cd autosclaw
- Run the AI-assisted setup
Open Claude Code in the project directory and run the setup skill:
/setup
Claude will interactively guide you through:
- Verifying prerequisites (Node.js, npm, Docker)
- Building the agent Docker image
- Configuring your
.envfile (API key, admin credentials, JWT secret, optional settings) - Installing manager dependencies
- Building the React dashboard
- Starting the manager
- Optionally installing a systemd service for auto-start on boot
The setup skill handles secret generation, input validation, and error recovery β you just answer the prompts.
Manual Setup (Alternative)
If you prefer to set up manually without AI assistance:
- Build the agent Docker image:
cd agent && docker build -t autosclaw-agent . && cd ..
- Create a
.envfile in the project root:
ANTHROPIC_API_KEY=sk-ant-...
ADMIN_USERNAME=admin
ADMIN_PASSWORD=your-secure-password
JWT_SECRET=your-jwt-secret
GH_TOKEN=ghp_... # Optional: enables GitHub self-modification
- Install and run:
cd manager && npm install && cd ui && npm install && npm run build && cd .. && npm start
The dashboard is now running at http://localhost:4000.
Systemd Service (Optional)
For production/server deployments, install as a systemd user service:
./install.sh
This creates autosclaw-manager.service that auto-starts on boot, restarts on failure, and runs in the background. Management commands:
systemctl --user status autosclaw-manager
systemctl --user restart autosclaw-manager
journalctl --user -u autosclaw-manager -f
Configuration
Environment Variables
| Variable | Default | Description |
|---|---|---|
ANTHROPIC_API_KEY | required | Your Anthropic API key for Claude |
ADMIN_USERNAME | β | Username for the initial admin account (seeded on first run) |
ADMIN_PASSWORD | β | Password for the initial admin account |
JWT_SECRET | random | Secret for signing JWT tokens. Set this for persistent sessions across restarts |
PORT | 4000 | Port the manager server listens on |
MANAGER_HOST | auto-detected | Docker bridge gateway IP. Auto-detected on Linux via ip route |
ALLOW_REGISTRATION | false | Set to true to enable user self-registration |
LOG_LEVEL | info | Logging verbosity (debug, info, warn, error) |
LOG_DIR | β | Directory for log files (with automatic rotation at 10 MB, keeps 5 files) |
GH_TOKEN | β | GitHub personal access token. Gives agents the ability to interact with GitHub repositories β clone, push, open PRs, and self-modify the autosclaw codebase itself |
Self-Modification with GH_TOKEN
When you provide a GH_TOKEN in your .env, agents gain full GitHub access through the gh CLI. This enables a powerful self-modification capability: agents can clone the autosclaw repository, make changes to its own codebase, commit, push, and open pull requests β effectively allowing the platform to improve itself.
Use cases include:
- Agents that refactor or extend autosclaw's own source code
- Automated code review and PR creation on any repository
- Scheduled agents that maintain repositories (dependency updates, changelog generation)
- Multi-agent workflows where one agent writes code and another reviews it via GitHub
The token is delivered to agent containers securely via stdin (same as all other secrets) and scrubbed from process.env after startup.
How It Works
Agent Lifecycle
-
Spawn β You spawn an agent from the dashboard (or an agent spawns a child via MCP). The Manager generates a UUID and a unique 32-byte hex token, then runs
docker runto create a new container from theautosclaw-agentimage. -
Secret delivery β The API key, manager URL, agent token, and optional GitHub token are piped to the container via stdin. They never touch disk or container environment variables. After the SDK subprocess starts, all secrets are scrubbed from
process.env. -
Registration β The agent connects back to the Manager via WebSocket, authenticates with its token, and begins its autonomous Claude session with the configured system prompt.
-
Execution β The agent runs autonomously, executing tools (Bash, file operations, web search, git) and reporting output, tool invocations, and token usage to the Manager in real-time.
-
Orchestration β Through MCP tools, the agent can spawn child agents, create schedules, list running agents, and despawn agents β enabling recursive multi-agent workflows with inherited permissions.
-
Live guidance β You can jump into any running agent's session at any time via the dashboard chat. Send instructions, course-correct, or provide context β the agent incorporates your message and continues. When the agent itself needs input, it sends an
ask_usermessage with selectable options, and you get a push notification. -
Completion β When the agent finishes (or is stopped), the container exits and is auto-removed (
--rm). The Manager detects the exit, updates the database, and broadcasts the state change to the dashboard.
Scheduling
The Manager's cron scheduler ticks every 30 seconds. For each active schedule whose next_run_at has passed, it spawns an agent with the schedule's configured name, purpose, system prompt, and permissions. One-time schedules are auto-deleted after firing.
State Persistence
All state is stored in SQLite (WAL mode). On startup, the Manager reconciles its database with running Docker containers β restoring active agents and cleaning up orphans (containers without a matching DB entry, or DB entries without a running container).
Security
Secret Management
Secrets are piped to containers via stdin only β never stored in environment variables, CLI arguments, Docker labels, or on disk. After the Claude SDK subprocess starts, the agent scrubs ANTHROPIC_API_KEY, CLAUDE_CODE_OAUTH_TOKEN, GITHUB_TOKEN, AGENT_TOKEN, and others from process.env, preventing leakage through /proc, environment dumps, or child processes.
Authentication
- User auth β username/password login produces a 24-hour JWT. Passwords hashed with bcryptjs (10 rounds).
- Agent auth β each container gets a unique 32-byte hex token verified with
crypto.timingSafeEqual(timing-safe comparison). - Dual auth middleware β every API endpoint accepts either a user JWT or an agent token with appropriate permission checks.
Container Isolation
Every agent runs in a separate Docker container with --rm (auto-cleaned on exit). No host filesystem access, no privileged mode, no shared volumes.
Resilience
- 30-second reconciliation loop β detects and cleans up orphan containers
- Graceful shutdown β stops all agents, closes WebSockets, waits 15 seconds before force-exit
- Structured logging β JSON-formatted logs with request IDs and automatic file rotation
- Soft deletes β agents and schedules are never hard-deleted, preserving audit history
Input Validation
All user inputs are validated at the API boundary: agent names (255 chars), purposes (1,000 chars), system prompts (100,000 chars), chat messages (50,000 chars), and cron expressions (validated with cron-parser).
API Reference
REST API
All /api/* endpoints require Authorization: Bearer <token> (JWT or agent token).
| Method | Endpoint | Description |
|---|---|---|
GET | /api/health | Health check (no auth required) |
POST | /api/spawn | Spawn a new agent container |
POST | /api/despawn | Stop and remove an agent |
GET | /api/agents | List all agents |
GET | /api/schedules | List all schedules |
POST | /api/schedules | Create a new schedule |
GET | /api/schedules/:id | Get schedule details |
PUT | /api/schedules/:id | Update a schedule |
DELETE | /api/schedules/:id | Soft-delete a schedule |
POST | /api/schedules/:id/pause | Pause a schedule |
POST | /api/schedules/:id/resume | Resume a paused schedule |
POST | /api/push/subscribe | Subscribe to push notifications |
POST | /api/push/unsubscribe | Unsubscribe from push notifications |
GET | /api/push/subscriptions | List push subscriptions |
Authentication Endpoints
| Method | Endpoint | Description |
|---|---|---|
POST | /auth/login | Authenticate and receive JWT (24h expiry) |
POST | /auth/register | Register a new user (when ALLOW_REGISTRATION=true) |
GET | /auth/me | Verify the current token |
WebSocket Endpoints
| Endpoint | Purpose |
|---|---|
/ws?token=<jwt> | Dashboard β real-time agent list, output streaming, cost updates |
/agent | Agent-to-Manager β registration, message relay, token usage, spawn requests |
Tech Stack
| Layer | Technology | Purpose |
|---|---|---|
| Runtime | Node.js 22 + TypeScript 5.6 | Server runtime with type safety |
| Server | Express 5 | HTTP server and REST API |
| Real-Time | ws (WebSocket) | Bidirectional communication |
| Database | better-sqlite3 (WAL mode) | Embedded persistent storage |
| Auth | bcryptjs + jsonwebtoken | Password hashing + JWT tokens |
| Scheduling | cron-parser | Cron expression parsing and scheduling |
| Notifications | web-push (VAPID) | Push notifications to browsers and mobile |
| Logging | Custom JSON logger | Structured logs with file rotation |
| AI | @anthropic-ai/claude-agent-sdk | Autonomous Claude agent sessions |
| Tools | @modelcontextprotocol/sdk | MCP server for inter-agent orchestration |
| Validation | Zod 4 | Schema validation for MCP tool inputs |
| Containers | Docker (node:22-slim) | Isolated agent execution |
| Frontend | React 19 + Vite | Real-time dashboard UI |
Project Structure
autosclaw/
β
βββ install.sh # systemd user service installer
βββ .env # Environment variables (created during setup)
β
βββ .claude/
β βββ commands/
β βββ setup.md # AI-assisted setup skill for Claude Code
β
βββ agent/ # Agent β runs inside Docker containers
β βββ Dockerfile # node:22-slim + git + gh CLI
β βββ build.sh # Build helper: docker build -t autosclaw-agent .
β βββ Claude.md # Agent behavior guidelines
β βββ package.json # Dependencies: agent SDK, MCP SDK, ws, zod
β βββ tsconfig.json
β βββ src/
β βββ main.ts # Entrypoint: stdin secrets, MCP server, SDK session
β βββ manager-client.ts # WebSocket client connecting back to Manager
β βββ types.ts # SDK message types and display helpers
β
βββ manager/ # Manager β runs on the host
β βββ start.sh # Full startup script (pull, install, build, run)
β βββ package.json # Dependencies: express, ws, better-sqlite3, etc.
β βββ tsconfig.json
β βββ src/
β β βββ main.ts # Express app, Docker image build, agent restoration
β β βββ api.ts # REST API routes (/api/spawn, /api/agents, etc.)
β β βββ auth.ts # JWT authentication (/auth/login, /auth/register)
β β βββ communication.ts # WebSocket servers (dashboard /ws + agent /agent)
β β βββ containers.ts # Docker container lifecycle (spawn, stop, secrets)
β β βββ db.ts # SQLite schema and CRUD (agents, messages, schedules)
β β βββ env.ts # Environment variable loading and defaults
β β βββ logger.ts # Structured JSON logging with file rotation
β β βββ push.ts # Web Push notification service (VAPID)
β β βββ pushRoutes.ts # Push subscription API endpoints
β β βββ schedules.ts # Cron schedule engine (30s tick loop)
β β
β βββ ui/ # React dashboard (built into src/public/)
β βββ index.html
β βββ package.json # React 19, Vite, TypeScript
β βββ src/
β βββ App.tsx # Root layout: sidebar + main panel
β βββ context/
β β βββ AppContext.tsx # Global state (React Context + Reducer + WebSocket)
β βββ hooks/ # useAuth, useAutoScroll, useConfirmDialog, etc.
β βββ components/
β βββ auth/ # LoginOverlay
β βββ layout/ # Sidebar, MobileHeader
β βββ modals/ # NewAgentModal, NewScheduleModal, ConfirmDialog
β βββ dashboard/ # Dashboard, AgentTable, ScheduleTable, TokenSummary
β βββ agent/ # AgentHeader, OutputArea, ToolCard, ChatBar, TokenBar
β βββ schedule/ # ScheduleDetail
β βββ settings/ # NotificationSettings
β βββ notifications/ # Toast, ToastContainer
β βββ pwa/ # InstallPrompt
Contributing
Contributions are welcome! Here's how to get started:
- Fork the repository (
gh repo fork BreuerFlorian/autosclaw --clone) - Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push and open a Pull Request (
gh pr create --title 'Add amazing feature')
Development Setup
For frontend development with hot reload:
cd manager/ui
npm install
npm run dev
The Vite dev server proxies API requests to http://localhost:4000, so make sure the manager is running.
License
This project is maintained by @BreuerFlorian. Please check the repository for license information.
Built with Claude Agent SDK by Anthropic
autosclaw β let your agents do the work.
