Comma README

The project's README from github.com/AFK-surf/Comma. As one markdown file: README.md.

Comma

The sessionless, relentless personal agent.

Comma: the open-source, sessionless, relentless personal agent for macOS and Web

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.

See Comma in action

No more applications.

Hand over your work and life. Comma gets it done.

https://github.com/user-attachments/assets/cefa2954-f29c-4434-9246-a82cb19a51fe

Personal context, aligned.

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

Philosophy

What Comma does

Built with Elixir and Lean. Verified with Lean and TLA+.

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.

Self-host with Docker Compose

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.

Requirements

First start

  1. Copy the example configuration:

    cp .env.example .env
    
  2. Set COMMA_OWNER_EMAIL to your email address. This account gets Admin access.

  3. Set your model provider in .env, or skip this step and configure a private model in Settings after login.

  4. Build and start the stack:

    docker compose up -d --build
    
  5. Open http://localhost:8080 and request a login code with your email address.

  6. 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.

Configuration

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.

Interfaces

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

Public access

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.

Features that need external accounts

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.

Upgrades and backups

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.

Repository layout

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

Development

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:

Security

Report a vulnerability to [email protected]. See the security page for details.

License and contributions

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.

Comma (AFK-surf/Comma)

Searching Database…

266 ·GitHub
What is this?Comma is an open-source, sessionless personal AI agent that turns your requests into persistent Tasks and keeps working on them through autonomous agent loops until they're done, across your computer, phone, and cloud.
Is this an app I install, or a service I self-host?It's a self-hosted service (a Docker Compose stack with Web and Admin clients plus a server) that you can also use as a hosted product at comma.surf; a companion Mac app called Salix lets it read and control files on your own computer.
How do I get my own instance running?Copy the example .env config, set COMMA_OWNER_EMAIL for admin access, point it at a model provider, then run 'docker compose up' to build and start the Web client, Admin client, server, PostgreSQL, Redis, MinIO, ClickHouse, and Mailpit.
What do I need installed before I start it up?You need Docker Engine with Compose v2.24 or later, plenty of disk space for the first build (it pulls the Lean, Elixir, Go, and Node toolchains), and a model provider account since the default stack ships with no mock model.
Does the formal verification mean tasks always succeed?No — the Lean and TLA+ proofs only guarantee the runtime behaves correctly under failures, like not losing accepted work or double-executing a mutating action. They don't prove the agent's judgment or task outcomes are actually correct.
Where does my sensitive data actually live?Long-running work happens in Comma's own environment, but identity, sessions, payments, and private data are designed to stay on your own devices, with Comma handing a Task back to your computer or phone when that's needed.
What happens if I modify and redistribute it?Comma's original code is AGPL-3.0-only, and if you run a modified version as a public service you're required to keep a /source.tar.gz download of your changes available to users.
Can I still use Claude Code or Codex alongside Comma?Yes — Codex, Claude Code, Pi, and Kimi can be invoked as applications or registered as Workers and Sub-agents, so Comma orchestrates your existing agent tools instead of replacing them.
What is Salix?Salix is the Mac companion app that connects your computer to Comma; it lets Comma read your files, and once you enable 'Allow operations', also change files, run commands, and record calls.
What are Loops?A Loop is a small program your agent writes to watch an inbox, repository, or feed, waking the agent only when something actually needs attention, so quiet monitoring burns no model tokens.
Why build the runtime in Elixir with Lean verification instead of a typical agent stack?Elixir/OTP runs each agent as its own isolated, restartable process on the Erlang VM, while Lean and TLA+ formally check that core distributed protocols never silently lose work or double-run side effects — reliability is treated as a core product property, not an afterthought.
Creator
AFK-surf
Size
41.1 MB
Stars
266
Updated
CommitOct 02
Age
17d
Commits · 90 Days