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…

267 ·GitHub
Что это?Comma — open-source персональный AI-агент без привязки к сессиям, который превращает ваши запросы в постоянные Tasks и продолжает работать над ними через автономные циклы агента, пока они не будут выполнены, — на вашем компьютере, телефоне и в облаке.
Это приложение для установки или сервис для самостоятельного хостинга?Это самохостинговый сервис (стек Docker Compose с клиентами Web и Admin плюс сервер), который можно использовать и как хостинговый продукт на comma.surf; сопутствующее приложение для Mac под названием Salix позволяет ему читать и управлять файлами на вашем компьютере.
Как поднять свой экземпляр?Скопируйте пример конфигурации .env, задайте COMMA_OWNER_EMAIL для админ-доступа, укажите провайдера моделей, затем выполните «docker compose up», чтобы собрать и запустить Web-клиент, Admin-клиент, сервер, PostgreSQL, Redis, MinIO, ClickHouse и Mailpit.
Что нужно установить перед запуском?Нужны Docker Engine с Compose v2.24 или новее, много дискового пространства для первой сборки (она тянет тулчейны Lean, Elixir, Go и Node) и аккаунт провайдера моделей, поскольку в стандартном стеке нет мок-модели.
Означает ли формальная верификация, что задачи всегда выполняются успешно?Нет — доказательства на Lean и TLA+ гарантируют лишь, что рантайм корректно ведёт себя при сбоях: не теряет принятую работу и не выполняет изменяющее действие дважды. Они не доказывают, что суждения агента или исходы задач действительно верны.
Где на самом деле хранятся мои чувствительные данные?Длительная работа происходит в собственном окружении Comma, но личность, сессии, платежи и приватные данные по замыслу остаются на ваших устройствах: когда это нужно, Comma возвращает Task на ваш компьютер или телефон.
Что будет, если я изменю и распространю его?Исходный код Comma — AGPL-3.0-only, и если вы запускаете изменённую версию как публичный сервис, вы обязаны держать доступной для пользователей загрузку /source.tar.gz с вашими изменениями.
Можно ли по-прежнему использовать Claude Code или Codex вместе с Comma?Да — Codex, Claude Code, Pi и Kimi можно вызывать как приложения или регистрировать как Workers и Sub-agents, так что Comma оркестрирует ваши существующие агентские инструменты, а не заменяет их.
Что такое Salix?Salix — сопутствующее приложение для Mac, соединяющее ваш компьютер с Comma; оно позволяет Comma читать ваши файлы, а после включения «Allow operations» — ещё и изменять файлы, выполнять команды и записывать вызовы.
Что такое Loops?Loop — небольшая программа, которую пишет ваш агент, чтобы следить за почтой, репозиторием или лентой и будить агента, только когда что-то действительно требует внимания, поэтому тихое наблюдение не тратит токены модели.
Зачем строить рантайм на Elixir с верификацией Lean вместо типичного агентского стека?Elixir/OTP запускает каждого агента как отдельный изолированный перезапускаемый процесс на виртуальной машине Erlang, а Lean и TLA+ формально проверяют, что ключевые распределённые протоколы никогда не теряют работу молча и не выполняют побочные эффекты дважды — надёжность считается ключевым свойством продукта, а не запоздалой мыслью.
Creator
AFK-surf
Size
41.1 MB
Stars
267
Updated
CommitOct 02
Age
18d
Commits · 90 Days