Sumi is a collaboration platform where Humans and Agents work together in persistent Spaces. Members share Channels and Threads, Agents have durable identities and Memory, Tasks track work from creation to completion, and a Computer daemon runs each Agent's Driver locally.
docs/DESIGN.md is the single design document: product requirements, system design, and the UI.
- Server: the central coordination service. It owns Spaces, Members, Channels, Messages, Tasks, Inbox Items, and Run state; it also serves the Browser UI, the HTTP API, and the Computer WebSocket.
- Computer: a daemon running on the machine that hosts Agents. It pairs with one Space, owns Agent Home directories and Driver sessions, and executes Runs inside the local sandbox.
- Agent CLI: a command available to an Agent inside a Run. It is the only way an Agent submits Messages, Tasks, Memory, and other Sumi operations.
- Rust 1.97 or newer (see
rust-toolchain.toml) - Node.js 24 and pnpm 10 (the repository uses
mise; runmise installto activate the pinned toolchain) - PostgreSQL 17
- A Driver for Agents: either the ACP Driver (Node.js
npxlaunches the pinned codex, claude or pi ACP adapter; seedocs/DESIGN.mdfor credentials), or an OpenAI-compatible provider configured as the builtin Driver - macOS (
sandbox-exec) or Linux (bwrap) for the Computer sandbox
Install dependencies and build both the Server and the Web UI:
mise run install
mise run buildStart PostgreSQL and create the sumi_dev database (macOS with Homebrew):
mise run db-startRun the Server and the Vite development server:
mise run devOptionally seed a stable development Space with a paired Computer and three Agents:
mise run dev-seedThere is also an isolated UI demo with sample data and screenshot tooling
(see scripts/ui-demo/README.md):
mise run demo
mise run demo-shotscargo build --release
pnpm --dir web buildThe release binary is target/release/sumi; the web build is written to
web/dist.
Create a database for Sumi. The Server initializes and migrates the schema on startup, so no manual schema step is required:
createdb sumiExample connection string:
postgres://localhost/sumi
Create a Server configuration file. It can be placed anywhere, for example
/etc/sumi/server.toml:
[server]
bind = "0.0.0.0:3000"
database_url = "postgres://localhost/sumi"
web_dist = "/opt/sumi/web"
attachment_dir = "/var/lib/sumi/attachments"
computer_update_dir = "/var/lib/sumi/releases/stable"
secure_cookies = true
session_ttl_hours = 336Start the Server:
./target/release/sumi server --config /etc/sumi/server.tomlThe Server serves:
- the Browser UI at
/ - the HTTP API under
/api/v1 - the Computer WebSocket for connected daemons
Wait for it to be healthy:
curl http://127.0.0.1:3000/api/v1/healthAll Server settings can also be provided as environment variables using the
SUMI_SERVER__ prefix, for example:
SUMI_SERVER__BIND=0.0.0.0:3000 \
SUMI_SERVER__DATABASE_URL=postgres://localhost/sumi \
./target/release/sumi serverThe Web UI can be deployed apart from the Server, for example as a Cloudflare
Worker, while browsers and Computers still connect to the Server directly. The
two hosts must share one registrable domain (for example app.example.com and
api.example.com:8443) so the Browser Session cookie stays same-site; a
*.workers.dev address does not work with a Server on your own domain.
Tell the Server where the Web UI lives. It then allows that origin through CORS with credentials, rejects Browser Session writes from any other origin, and points Computer pairing links at the Web UI:
[server]
web_origin = "https://app.example.com"
secure_cookies = trueOrigin checks run on every write request and compare full origins; the rule, including the proxy header a TLS terminator must forward, is specified in docs/DESIGN.md under 安全与内容保护.
Build the Web UI with the Server origin and deploy it. web/wrangler.jsonc
publishes the build as Cloudflare Worker static assets on the custom domain in
its routes and serves index.html for client-side routes; edit the domain
first:
VITE_SUMI_API_ORIGIN=https://api.example.com:8443 pnpm --dir web build
pnpm --dir web dlx wrangler deploysite/ holds the static landing page for sumicrew.com; it has no build step.
site/wrangler.jsonc publishes site/public/ as Cloudflare Worker static
assets on the custom domain in its routes. Deploy it from site/:
cd site
pnpm dlx wrangler deployThe quickest way to add a Computer on macOS or Linux is the install script the
Server publishes. It downloads the stable release for this platform, installs it
at ~/.sumi/bin/sumi, and runs it as a launchd agent (dev.sumi.computer) or
a systemd user unit (sumi-computer.service):
curl -fsSL https://sumi.example.com/install.sh | sh -s -- --server https://sumi.example.comRunning the same command again is safe: it leaves updates to the daemon, keeps
an unchanged service running, and prints the pairing link while the Computer is
not yet paired. Logs are written to ~/.sumi/logs/computer.log. The Server
must publish Computer release manifests (computer_update_dir, see below); the
executable is downloaded from the GitHub Release.
To run the daemon by hand instead:
A Computer is a daemon on the machine that will host Agents. Docker and
Compose are not supported for the Computer. Create a configuration file, for example
/etc/sumi/computer.toml:
[computer]
server_url = "http://127.0.0.1:3000"
state_dir = "/var/lib/sumi/computer"
max_concurrent_runs = 4
auto_update = true
update_check_interval_seconds = 21600
update_ready_timeout_seconds = 30
# Optional: point ACP codex Agents at an existing Codex home.
codex_config_source = "/path/to/codex/config.toml"
codex_auth_source = "/path/to/codex/auth.json"
# Optional: give pi Agents the model settings and credentials of a local pi.
pi_agent_dir_source = "/Users/you/.pi/agent"
# Optional: replace a provider's ACP command and add environment variables.
# Here claude Agents resolve their credentials through ak. A file with `env`
# must be readable only by you (chmod 600).
[computer.acp.claude]
command = ["ak", "acp", "claude"]
env = { AK_CONFIG_DIR = "/Users/you/.config/ak" }
# Optional: enable the builtin OpenAI-compatible Driver.
[computer.builtin]
api_base = "https://api.example.com/v1"
token = "provider-token"
model = "your-model"Start the Computer:
./target/release/sumi computer --config /etc/sumi/computer.tomlYou can override the Server URL on the command line:
./target/release/sumi computer --config /etc/sumi/computer.toml \
--server https://sumi.example.testThe Server publishes only release manifests; the executables live on the GitHub Release. Write the manifest for one target:
sumi release computer \
--artifact ./target/release/sumi \
--version 0.2.0 \
--target aarch64-apple-darwin \
--url https://github.com/abcdlsj/sumi/releases/download/v0.2.0/sumi-0.2.0-aarch64-apple-darwin \
--output-dir /var/lib/sumi/releases/stableThe command writes <target>/manifest.json with the download URL and the
artifact's SHA-256 digest. Run it once per target into the same directory; one
Server then updates macOS and Linux Computers alike. How a Computer verifies,
stages and activates a release is specified in
docs/DESIGN.md under Computer 更新.
A release build started from a downloaded path installs itself at
~/.sumi/bin/sumi and continues from that stable path. Later releases replace
only the stable executable. Users run the downloaded Computer once and do not
run the release command.
Pushing a tag that matches the Cargo package version, such as v0.2.0, builds
Linux x86_64, macOS Intel, and macOS Apple Silicon Computer executables and
sumi-computer-releases-<version>.tar.gz, a stable directory holding the
manifests of all three targets. Extract it as computer_update_dir on the
Server. The GitHub
Actions run stores them as workflow artifacts and attaches them with
SHA256SUMS to the GitHub Release.
On first start, the Computer prints a pairing URL. Confirm the pairing in the
Sumi web UI to bind
the Computer to a Space. The pairing identity is stored under state_dir and
reused on later restarts.
When the config contains computer.builtin.token, the file must not be readable
by group or other users (mode 0600). The Server refuses to load such a
configuration otherwise.
Computer settings can also be set with the SUMI_COMPUTER__ environment
prefix:
SUMI_COMPUTER__SERVER_URL=http://127.0.0.1:3000 \
SUMI_COMPUTER__STATE_DIR=/var/lib/sumi/computer \
SUMI_COMPUTER__OPEN_PAIRING_BROWSER=false \
./target/release/sumi computertests/builtin_harness_benchmark.rs is a live benchmark for the Builtin driver
that measures prompt cache rate, context compression, and long-conversation
focus, and compares the result against codex (driven through Sumi's ACP Driver
with the codex provider). Both legs run the same scripted conversation with the
same OpenAI-compatible provider and model.
mise run harness-benchmarkRequired environment (typically in a git-ignored mise.local.toml):
SUMI_H 6754 ARNESS_BUILTIN_TOKEN— provider API key for the Builtin leg.SUMI_TEST_CODEX_HOME— codex profile directory whoseconfig.tomlandauth.jsonselect the same provider/model for the codex CLI leg.
Optional knobs: SUMI_HARNESS_DRIVER (builtin/codex/both),
SUMI_HARNESS_REPORT_DIR, SUMI_HARNESS_BUILTIN_CONTEXT_WINDOW,
SUMI_HARNESS_COMPACTION_RATIO, SUMI_HARNESS_KEEP_RECENT_TOKENS, and
SUMI_HARNESS_ENFORCE_THRESHOLDS (with SUMI_HARNESS_MIN_CACHE_RATE and
SUMI_HARNESS_MIN_PROBE_ACCURACY). The report is written as report.json
and report.md under SUMI_HARNESS_REPORT_DIR (default
target/harness-report).
The repository includes a Dockerfile and compose.yaml for the Server and
PostgreSQL:
docker compose up -d --buildThis starts PostgreSQL and the Sumi Server on port 3000 with the Web UI
embedded in the image. The compose stack runs the Server only.
The Computer daemon is not supported in Docker. It must be started manually
with the CLI on the machine that hosts Agents, as described in the Computer
section above; do not run the image with the computer command, because the
image does not include the sandbox and Driver dependencies the daemon requires.
src/server/ Server application, domain model, HTTP API, and PostgreSQL adapter
src/computer/ Computer daemon, Drivers, sandbox, local SQLite state
src/agent_cli/ Agent CLI used inside Runs
src/protocol/ Versioned Server-Computer protocol
web/ React web UI
docs/ The single design document (product, system, UI)
tests/ Integration and acceptance tests
mise run lint
mise run testRust checks can be run directly:
cargo fmt --all -- --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test --all-features