The project's README from github.com/AFK-surf/Comma. As one markdown file: README.md.
Comma is an open-source personal agent built to be sessionless. Your work, memory, and context stay continuous across your computer, phone, cloud environment, applications, and connected devices.
It breaks down your goals into Tasks and keeps working through agentic loops until the job is done.
Built by AFK Inc., Comma is our attempt to create an open agentic system that keeps you away from software — and away from the keyboard.
You can use the hosted service at comma.surf, or run your own instance from this repository.
Hand over your work and life. Comma gets it done.
https://github.com/user-attachments/assets/cefa2954-f29c-4434-9246-a82cb19a51fe
Save money. Shop smarter based on your preferences. Check out on your trusted device.
https://github.com/user-attachments/assets/486cde78-d927-4ff0-85de-00c46edc498e
Sessionless
Relentless
Swarm Intelligence
Works with your existing agents
Cloud for work. Your device for identity.
Comma is built for long-running, fault-tolerant agent workloads. Its runtime is primarily built with Elixir/OTP, with Lean used for critical systems components. Important runtime properties are specified and machine-checked in Lean, and we use TLA+ to model-check core distributed protocols.
Each agent runs as its own process on the Erlang VM. When one part fails, it restarts, and the other agents keep running. Messages that Salix has accepted survive the restart. An interrupted action that changes something does not run again on its own.
The formal models check properties such as:
Formal verification does not prove model judgment or task success. It verifies something more fundamental: the runtime behaves according to the rules we designed, even when things fail.
For a sessionless agent, reliability is not an infrastructure detail. It is part of the product.
See Verification and the TLA+ models.
The root compose.yaml starts a complete single-node instance. It builds the
Web client, the Admin client, and the server from source. It also starts
PostgreSQL, Redis, MinIO, ClickHouse, and Mailpit, a local email inbox. You do
not need a Comma account or a private repository token.
Copy the example configuration:
cp .env.example .env
Set COMMA_OWNER_EMAIL to your email address. This account gets Admin
access.
Set your model provider in .env, or skip this step and configure a
private model in Settings after login.
Build and start the stack:
docker compose up -d --build
Open http://localhost:8080 and request a login code with your email address.
Read the code in the local inbox at http://localhost:8025.
The first start generates persistent secrets and initializes empty stores. By default, all public ports bind to loopback only.
| Variable | Purpose |
|---|---|
COMMA_OWNER_EMAIL |
First owner account and Admin access |
COMMA_ALLOW_SIGNUP |
Public registration, off by default |
COMMA_LLM_BASE_URL |
Model provider endpoint |
COMMA_LLM_PROTOCOL |
Provider protocol, such as chat_completions |
COMMA_LLM_MODEL |
Provider model ID |
COMMA_LLM_API_KEY |
Provider credential |
COMMA_LLM_CONTEXT_TOKENS |
Model context budget |
COMMA_LLM_MAX_TOKENS |
Output token limit |
COMMA_EXA_API_KEY |
Optional Exa key for web search and page reading |
COMMA_SMTP_* |
Mail server for login codes |
COMMA_PUBLIC_URL, COMMA_API_URL, COMMA_ADMIN_URL, COMMA_SALIX_URL |
Browser origins |
Model calls use your provider account and can cause provider charges. A self-hosted instance does not need Stripe or Comma credits.
| Interface | Default address |
|---|---|
| Comma Web | http://localhost:8080 |
| Comma Admin | http://localhost:8082 |
| Comma Product API | http://localhost:8081 |
| Salix dashboard | http://localhost:4000/dash |
| Local inbox | http://localhost:8025 |
For a public instance, put Comma behind your HTTPS reverse proxy. Web, Admin,
and the Product API must use different origins on one registrable domain, for
example app.example.com, admin.example.com, and api.example.com. Set a
real SMTP server. The local inbox is for loopback use only, because anyone who
can read it can use its login codes.
Agents, Tasks, object storage, search, and subscription-account storage run inside the stack. To let Comma run commands on your own computer, connect the computer from the device settings. Group cloud computers need a Cloudflare configuration. Meetings and Agent VMM hosts need runtimes that this repository does not include.
Stop the stack before an upgrade. Back up all five named volumes together:
config, postgres, objects, clickhouse, and redis. The config volume
holds the encryption key and authentication secrets. Do not delete it or
regenerate its secrets. docker compose down keeps your data. Do not add -v
unless you want to delete the instance.
Read the self-hosting guide before public deployment, upgrades, or restores.
clients/ # Web and Electron clients and shared React packages
systems/ # Elixir umbrella for Salix, the Comma product, and Bridge For Teams
selfhost/ # Self-hosting configuration and storage images
docs/ # Engineering contracts
tla/ # TLA+ models of core distributed protocols
Install the client dependencies once, then start the local backend and the Web client:
pnpm install
make dev
make dev uses a deterministic mock model, so you do not need a model key. Sign
in as [email protected] and read the code in Mailpit at
http://127.0.0.1:8025. Use make dev-electron for the Mac app. Run the tests
from the repository root:
make test-clients
make test-systems
make test-policy
Start with these documents:
Report a vulnerability to [email protected]. See the security page for details.
Comma's original code is licensed under AGPL-3.0-only. Third-party
components keep their own licenses. If you serve a modified version, keep the
/source.tar.gz download available.
Contributions require the AFK AI, Inc. CLA. See CONTRIBUTING.md.