ARCHITECTURE
How it actually works. End to end.
SwarmLab ships as a single Node binary containing the runtime, scheduler, web server, and embedded database. There is no orchestration cloud, no SaaS dependency, and no data leaving your machine. This page walks through every layer.
1
Binary
6
Adapters
3
Sandbox tiers
0
Bytes leave your box
SYSTEM ARCHITECTURE
Four-layer stack
Single-binary by design
The entire stack compiles into one executable. Postgres is embedded, the web server runs inside the process, and the scheduler is a simple setInterval loop. No Docker, no Kubernetes, no microservices. You download one file, run it, and everything is live.
What self-hosted actually means
Your API keys go directly to the provider. Your code stays in your git worktrees. Your database lives on your disk. There is no relay server, no telemetry endpoint, and no analytics pixel. The binary phones home exactly zero times.
ADAPTERS
Six ways to talk to models
Each adapter wraps a provider into a unified interface. Swap models per agent without changing a single line of workflow config.
claude-local
Auth: API key
codex-local
Auth: API key
http/anthropic
Auth: API key
openai
Auth: API key
openrouter
Auth: API key
ollama
Auth: None
RUN LIFECYCLE
From trigger to commit in six steps
Every run follows the same deterministic pipeline, whether kicked off from the UI, CLI, or a bridge message.
Heartbeat scheduler picks up
Every 5 seconds the heartbeat loop queries for pending runs and claims them atomically.
SELECT id, agent_id, workflow_id
FROM runs
WHERE status = 'pending'
ORDER BY priority DESC, created_at
LIMIT 1
FOR UPDATE SKIP LOCKED;Workspace materializes
A fresh git worktree is created so each run gets an isolated working copy.
git worktree add \
.swarmlab/worktrees/run-a3f8 \
--detach HEADAdapter invokes model
The adapter streams the model response through three phases.
thinking → tool_calls → done
├─ stream chunks to UI via WS
└─ accumulate tool invocationsTool calls hit sandbox
Every file path is validated against the agent's glob allowlist before execution.
// sandbox.validate(toolCall)
allow: ["src/**", "tests/**"]
deny: ["*.env", ".git/**"]
path: "src/utils/parse.ts" ✓Approval gate (optional)
If the agent requires approval, the diff is surfaced in the UI and execution pauses.
status: awaiting_approval
diff: +14 -3 src/utils/parse.ts
reviewer: @you
action: [approve] [reject] [edit]Commit, comment, close
Changes are committed, linked to the run, and the task is marked complete.
git add -A
git commit -m "feat: add parser util
swarmlab-run: a3f8
swarmlab-agent: code-writer"SANDBOX MODEL
Three tiers of access control
Every agent runs inside a sandbox tier. The tier decides what the agent can see, touch, and execute.
none
12% capacity
Read-only conversation, no filesystem access.
Best for: Planners & reviewers
- •No file reads
- •No shell access
- •Chat-only mode
read-only
50% capacity
Can read files and execute read-only shell commands.
Best for: Reviewers & auditors
- •File reads within globs
- •Read-only shell
- •No write access
full
100% capacity
Full read/write within configured globs, unrestricted bash.
Best for: Builders
- •Read/write within globs
- •Unrestricted bash
- •Git operations
SECURITY POSTURE
Eight things we guarantee
AES-256-GCM encryption at rest for all secrets and tokens
Encryption-key boot guard — server refuses to start without the key
No outbound telemetry — zero analytics, zero phone-home
Direct provider calls — your API traffic goes straight to the provider
Sender allowlists on bridges — only whitelisted senders can trigger runs
Cross-org mailbox checks — prevents agents from reading other orgs' data
Worktree isolation per run — every run operates in its own git worktree
Auditable codebase — single binary, no hidden services, no black boxes
SYSTEM REQUIREMENTS
What you need to run it
Minimum
- —macOS 13+ or Linux
- —8 GB RAM
- —4 GB free disk
- —Network access to at least one provider
Recommended
- —16 GB RAM (required for Ollama)
- —Apple Silicon or dedicated GPU
- —SSD for worktree throughput
Not sure if your machine qualifies? Run the built-in diagnostic:
npx swarmlab doctorReady to see it running?
Grab a lifetime license or dive into the docs to start building your first agent swarm.