Documentation

Getting started

soloagent is one Node.js program. Run it on your laptop to try it, then put the same thing on a server when your team should reach it from Slack, Discord, or Telegram. Pick whichever install fits:

Install on your machine

With Node 22.19 or newer, the installer puts the soloagent command on your path:

curl -fsSL https://soloagent.dev/install.sh | sh

It downloads the latest release and installs it with npm, so you can also do that yourself, on any OS including Windows, or try it once without installing. --allow-remote=root lets npm 12 install from a release URL; older npm versions ignore it:

# install
npm install -g --allow-remote=root https://github.com/nearbycoder/soloagent.dev/releases/latest/download/soloagent.tgz

# or run once, nothing installed
npx -y --allow-remote=root https://github.com/nearbycoder/soloagent.dev/releases/latest/download/soloagent.tgz

On macOS or Linux with Homebrew, which brings its own Node:

brew install nearbycoder/soloagent/soloagent

No Node? Use Docker, one command, any OS:

docker run -d --name soloagent -p 7420:7420 -v soloagent:/data ghcr.io/nearbycoder/soloagent.dev

Then open http://localhost:7420 and paste the token from docker logs soloagent.

First run

# the terminal UI, with a private server and data in ~/.soloagent
soloagent

# or the web dashboard on http://localhost:7420
soloagent serve
soloagent token   # paste this into the dashboard

A fresh install has one agent and the built-in demo model, so everything works before you connect an account. Then sign in to a real model, for example your Claude Pro or Max subscription, with /login anthropic in the TUI, soloagent login anthropic in your shell, or the Providers page of the dashboard.

# one-shot answers for scripts; piped input is added after the message
git diff --staged | soloagent ask "Write a commit message for this diff"

# point the TUI at a server you deployed
soloagent connect https://solo.example.com --token $SOLOAGENT_TOKEN

Deploy

soloagent needs three things from a host: a long-running process (chat connectors hold open connections and durable timers need a clock), a persistent directory for its two SQLite databases, and, for the dashboard and webhooks, an HTTP port. It runs as a single instance; don't scale it horizontally.

curl -fsSLO https://raw.githubusercontent.com/nearbycoder/soloagent.dev/main/docker-compose.yml
docker compose up -d
docker compose logs soloagent | grep token

git clone https://github.com/nearbycoder/soloagent.dev && cd soloagent.dev
fly launch --copy-config --no-deploy
fly volumes create soloagent_data --size 1
fly secrets set SOLOAGENT_TOKEN=$(openssl rand -base64 32) SOLOAGENT_SECRET=$(openssl rand -base64 32)
fly deploy

sudo useradd --system --create-home --home-dir /var/lib/soloagent soloagent
sudo npm install -g --allow-remote=root https://github.com/nearbycoder/soloagent.dev/releases/latest/download/soloagent.tgz
sudo curl -fsSLo /etc/systemd/system/soloagent.service https://raw.githubusercontent.com/nearbycoder/soloagent.dev/main/deploy/soloagent.service
sudo systemctl enable --now soloagent
sudo journalctl -u soloagent | grep token

Configuration

The server prints its URL and token when it starts:

  soloagent is up — https://solo.example.com
    data      /data
    token     solo_••••••••••••••••••••••••
    terminal  soloagent connect https://solo.example.com --token <token>

Where it doesn't fit

Serverless and edge platforms (Vercel functions, Netlify, Cloudflare Workers, AWS Lambda) and hosts without persistent disks (Heroku's dynos, DigitalOcean App Platform) can't run soloagent: they stop the process between requests and discard its files. Use one of the options above, or any VM.

Providers & subscriptions

soloagent reaches models through @earendil-works/pi-ai. You can sign in with a consumer subscription (or an OpenRouter account) over OAuth, or paste an API key. Each agent picks its own provider and model.

Sign in with your account

Open Providers in the dashboard and choose Sign in next to one of:

The provider's sign-in page opens in a new tab. When the server runs on your own machine, the login completes on its own.

From the terminal, /login <provider> in the TUI and soloagent login <provider> in your shell run the same flow.

API keys

Paste a key under Providers for any of 40+ providers, including Anthropic, OpenAI, Google Gemini, Mistral, Groq, DeepSeek, xAI, OpenRouter, Vercel AI Gateway, Amazon Bedrock, Azure, Together, Fireworks, Cerebras, and Hugging Face. Over the API, send { "key": "…" } to PUT /api/providers/:id/key, or run soloagent login <provider> --key.

Keys and OAuth tokens are sealed with AES-256-GCM before they're written to disk. See Security.

Subscription sign-in is subject to each provider's terms. Product names are trademarks of their respective owners.

Agents & skills

An agent is a named assistant with its own personality, model, and abilities. Create and edit them under Agents in the dashboard, or with POST /api/agents.

Skills

Agents can also get tools from MCP servers you connect. See Tools (MCP).

Memory

With the Memory skill, an agent saves durable notes with remember, searches them with recall, and deletes them with forget. The newest 40 are part of its prompt in every conversation. To see and correct what an agent remembers, open the agent and choose the Memory tab: search, add, edit, or delete notes, or clear them all. Agent cards show how many memories each agent has.

The same is available over the API at /api/agents/:id/memories (see Routes). Clearing every memory needs ?confirm=all, so a stray request can't wipe them.

Tools (MCP)

Connect Model Context Protocol servers (GitHub, Linear, Postgres, Sentry, a filesystem, anything that speaks MCP) and give their tools to the agents you choose. Add servers under Tools in the dashboard, then turn them on per agent under Tools from MCP servers in the agent editor.

Examples

GitHub's official server over stdio. It ships as a Docker image, so Docker must be available where soloagent runs. It reads a personal access token from its environment:

curl -X POST https://solo.example.com/api/mcp-servers \
  -H "authorization: Bearer $SOLOAGENT_TOKEN" -H "content-type: application/json" \
  -d '{
    "id": "github",
    "name": "GitHub",
    "command": "docker",
    "args": ["run", "-i", "--rm", "-e", "GITHUB_PERSONAL_ACCESS_TOKEN",
             "ghcr.io/github/github-mcp-server"],
    "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "github_pat_…" }
  }'

Servers published to npm run with npx, which is also available in the soloagent Docker image. The reference filesystem server, limited to one folder:

{
  "id": "files",
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-filesystem", "/data/shared"]
}

A remote server over HTTP, here GitHub's hosted one:

{
  "id": "github",
  "transport": "http",
  "url": "https://api.githubcopilot.com/mcp/",
  "headers": { "Authorization": "Bearer github_pat_…" }
}

Then give the tools to an agent in its editor, or with PATCH /api/agents/:id and { "mcpServers": ["github"] }.

How it works

• Connections. soloagent connects to every enabled server at startup and whenever you change one. If a server fails or drops, it shows Error with the reason and reconnects with backoff, from 2 seconds up to 5 minutes. A broken server never affects the rest of soloagent.
• Test. The Test button, or POST /api/mcp-servers/:id/test, connects if needed and lists the server's tools live.
• Tool changes. Tools appear for agents as soon as the server connects, and follow the server when its tool list changes. No restart or agent edit needed.
• Large servers. When a server has more than 15 tools, they aren't offered to the model up front. The agent gets a tool_search tool instead, searches for what it needs, and the matches are loaded for the rest of the conversation.
• Results. Text and images from tool results go to the model. A result the server marks as an error is reported to the agent as one.
• Not replayed. MCP calls can change things, so a call cut off by a crash or restart doesn't run again. The agent is told it was interrupted and can decide what to do.

Approvals

An agent can pause before a tool call until a person approves it. You can approve or deny in the dashboard, in the TUI, or with buttons in the Slack, Discord, or Telegram thread where the agent works. The wait is durable: it survives restarts and deploys, and an approved call runs exactly once.

Policies

Set the policy per agent under Agents → Approvals, or with the agent's approvals field.

Two settings apply to every agent. Change them under Approvals → Settings or with PUT /api/approval-settings:

• Timeout, 24 hours by default. A request nobody answers in time is denied.
• More risky tools: extra tool names the risky policy asks about, such as forget or schedule_reminder. End a name with * to match a prefix: mcp__github__* covers every tool of that MCP server. The all policy already asks before MCP tools.

When a call is denied, the agent gets an error result such as Denied by ann: not on prod and carries on, usually by explaining or trying another way. Stopping the run cancels the request.

Where to approve

• Dashboard. The tool card in the thread shows Waiting for approval with the arguments and Approve / Deny buttons. Deny takes an optional reason, which the agent sees. Deciding is for admins; members see the request and who it waits on. The Approvals page lists every waiting request across threads, with a count in the sidebar, and the recent decisions.
• Chat apps. In Slack, Discord, and Telegram threads, the agent posts a message with Approve and Deny buttons. Once someone decides, the message changes to show the outcome and who decided.
• TUI. The tool line shows waiting for approval. /approve approves the current thread's waiting call; /deny [reason] denies it.
• API. GET /api/approvals?status=pending, then POST /api/approvals/:id/approve or POST /api/approvals/:id/deny with { "reason": "…" }. Both take an optional by, the name recorded as the decider (default dashboard).

Chat setup

Only the people you list may press the buttons. In Connections, open the connector and fill in Approvers with platform user ids or display names, comma-separated. With an empty list, approvals happen only in the dashboard; anyone who presses a button is told so privately.

• Slack delivers button presses over Socket Mode, but only when the app has Interactivity on. The manifest below enables it (interactivity.is_enabled: true). For an app made from an older manifest, turn it on under Interactivity & Shortcuts; no request URL is needed. User ids look like U012ABCDEF (profile → Copy member ID).
• Discord needs no setup. Copy a user id with Developer Mode on (right-click → Copy User ID).
• Telegram needs no setup. Display names are first and last name as Telegram shows them; numeric user ids work too.
• Webhook connectors have no buttons. Approve their requests in the dashboard or through the API.

Connectors

Connectors put your agents into chat apps. Add them under Connections in the dashboard, which includes these setup guides. Each connector can be bound to an agent; otherwise the default agent answers. In chat apps, replies stream live by editing a placeholder message as the answer arrives.

display_information:
  name: Solo
  description: Your agents, on soloagent.dev
  background_color: "#15140f"
features:
  app_home:
    messages_tab_enabled: true
    messages_tab_read_only_enabled: false
  bot_user:
    display_name: Solo
    always_online: true
oauth_config:
  scopes:
    bot:
      - app_mentions:read
      - chat:write
      - channels:read
      - files:read
      - groups:read
      - im:history
      - im:read
      - im:write
      - users:read
settings:
  event_subscriptions:
    bot_events:
      - app_mention
      - message.im
  interactivity:
    is_enabled: true
  org_deploy_enabled: false
  socket_mode_enabled: true
  token_rotation_enabled: false

curl -X POST https://solo.example.com/api/hooks/<connector-id> \
  -H 'x-solo-secret: YOUR_SECRET' \
  -H 'content-type: application/json' \
  -d '{"text": "@coder what changed in the last deploy?", "thread": "deploys", "user": "ci"}'

Chat routing & commands

Every inbound message, from any connector, is routed to one agent:

1. If it starts with @handle or handle:, that agent answers. @coder fix the build and coder: fix the build are the same.
2. Otherwise, the agent bound to the connector answers.
3. Otherwise, the default agent answers.

Addressing applies to that one message, and each agent keeps its own conversation in a chat thread.

Steering

If you send another message while an agent is still working, it steers the run in progress: the agent sees your new message after its current step (a model reply or a round of tool calls) and adjusts, rather than finishing the whole task first and answering later.

Chat commands

Teams & access

By default anyone in a connected Slack, Discord, or Telegram can talk to any agent, and the dashboard has one admin token. For a team, limit who can reach which agents, cap what they cost, and give people their own sign-in.

Files & images

People can share files and images with agents from Slack, Discord, Telegram, webhooks, the dashboard (paste, drag and drop, or the paperclip), and the CLI (soloagent ask "describe this" --file ./screenshot.png). Each file becomes part of the message the agent sees:

Agents with the Workspace skill also get every file in attachments/ in their workspace, and notes point there, so they can work on PDFs, archives, and long files with their tools.

Limits

Files can be up to 20 MB, with up to 10 per message. Downloads from chat platforms and URLs time out after 30 seconds. Telegram bots can only download files up to 20 MB. Attachment URLs must be http or https and may not point at loopback or private network addresses unless SOLOAGENT_ALLOW_PRIVATE_FILE_URLS=1 is set.

Sending files over the API

POST /api/threads/:id/messages, /ask, and webhooks take an attachments array of { name, mimeType, data_base64 } or { name, mimeType, url }. mimeType is optional; it's guessed from the file name. The SDK passes them through: solo.send(threadId, "what's wrong here?", { attachments }).

Slack

Slack needs the files:read scope, which is in the manifest above. Apps created before it was added must add the scope and be reinstalled.

Where files are stored

Original files are kept on your server's disk under <data dir>/files/, named by their SHA-256 hash, so a file shared twice is stored once. Messages keep only each file's name, type, size, and hash. Images go to the model at request time and aren't copied into the conversation database. Files are never deleted automatically; deleting a thread leaves its files in place. They're readable only with the admin token, through GET /api/files/:sha256, and they're sent to your model provider along with the message, like any other message content.

Automations

An automation is a prompt that runs on a schedule: “every weekday at 9:00, post a standup summary in #eng”, “every Monday, summarize last week's deploys”, “every hour, check the status page and alert if anything is down”. Reminders fire once; automations repeat.

Create them under Automations in the dashboard, with POST /api/automations, or by asking an agent that has the Schedule skill. In Slack:

@solo every weekday at 9 post the open incidents here

The agent calls schedule_recurring. It can also list_automations and cancel_automation.

Schedules

A schedule is a 5-field cron expression read in an IANA time zone (the server's by default). The dashboard also offers simple presets, which are stored as cron:

The fields are minute, hour, day of month, month, and day of week. Each takes *, numbers, lists (1,15), ranges (1-5), and steps (*/10); months and days also take names (jan, mon-fri). As in classic cron, when both day fields are set, a day matching either one fires. @hourly, @daily, @weekly, and @monthly work too.

Daylight saving time. A time skipped by a spring-forward jump (02:30 on that night in most of the US) fires once, at the moment of the jump. A time repeated by a fall-back fires once, on its first occurrence.

Where runs land

• A thread. Pick any existing thread, web or chat. Each run is a message from Automation: <name> in that thread, answered by the thread's agent. In a chat thread the answer is posted to Slack, Discord, or Telegram like any other reply.
• A chat channel. Pick a connection and a channel id (Slack channel id, Discord channel id, Telegram chat id, or a webhook callback URL). Each run posts a new top-level message in the channel; on Slack, replies to it start a normal thread with the agent. The automation keeps one conversation of its own, so the agent remembers earlier runs (“since yesterday…”).

Catch up once

Each enabled automation is a durable task that sleeps until its next run. If the server is down when a run is due, that run fires once when the server starts again, and the schedule continues from then. Missed runs are not replayed one by one: an hourly automation that was down for a day runs once on startup, not 24 times.

Disabling, editing, or deleting an automation cancels or reschedules its task immediately. Run now runs it once outside its schedule, even when it is disabled. Runs use the same path as a chat message, so the agent's model, skills, and limits apply.

API

curl https://solo.example.com/api/automations \
  -H "authorization: Bearer $SOLOAGENT_TOKEN" -H "content-type: application/json" \
  -d '{
    "name": "Standup summary",
    "prompt": "Summarize the PRs merged since the last run and the open incidents.",
    "preset": { "kind": "weekdays", "time": "09:00" },
    "timezone": "America/Chicago",
    "target": { "kind": "channel", "connectorId": "sla_…", "channel": "C0123456789", "location": "#eng" }
  }'

Give cron (an expression or a phrase like "weekdays at 9:00") or preset. A thread target is { "kind": "thread", "threadId": "thr_…" }. List them from the terminal with soloagent automations.

Terminal UI

soloagent opens a full-screen terminal UI built on pi-tui. With no arguments it uses a local server, starting one in-process if soloagent serve isn't already running; after soloagent connect <url> --token … it talks to that remote server instead. It streams answers live and shows tool calls as they run.

Keybindings

Slash commands

Type / in the input to search the commands. Start a message with // to send text that begins with a slash.

CLI commands

HTTP API & SDK

The dashboard and TUI use the same public API, so anything they do, your scripts can do. All routes live under /api and require the admin token in an authorization: Bearer … header (or a signed-in user's session cookie), except inbound webhooks, which carry their own secret, invite links, and /api/version. Only the WebSocket accepts the token as ?token=; REST routes reject it. Requests without a valid token get 401.

curl https://solo.example.com/api/agents \
  -H "authorization: Bearer $SOLOAGENT_TOKEN"

Routes

WebSocket events

Connect to /api/ws and send { "type": "subscribe", "threadId": "…" } to receive a thread's thread.snapshot, thread.messages, and thread.live events (streaming text, thinking, and tool calls). Send { "type": "tasks.subscribe" } for the live durable task graph. Server-wide events such as thread.updated, agent.updated, connector.updated, approval.updated, automation.updated, and mcp.updated arrive without subscribing. A thread's live.approvals lists the tool calls it waits on.

TypeScript SDK

@soloagent/client, in packages/client, is a typed client for the REST API and WebSocket with no dependencies. It runs in Node 22.19+ and in browsers. It isn't on npm yet, so use it from a clone of the repository.

import { SoloClient } from "@soloagent/client";

const solo = new SoloClient({
  baseUrl: "https://solo.example.com",
  token: process.env.SOLOAGENT_TOKEN,
});

const thread = await solo.createThread({ agentId: "coder" });

// Wait for the full answer
const result = await solo.ask(thread.id, "What changed in the last deploy?");
console.log(result.answer);

// Or fire and forget, and follow along live
await solo.send(thread.id, "Now draft release notes");

const stream = solo.connect(); // reconnects automatically
stream.subscribe(thread.id);

stream.on((event) => {
  if (event.type === "thread.live") render(event.live);         // streaming text, thinking, tools
  if (event.type === "thread.messages") append(event.messages); // committed messages
});

// later
stream.close();

Embed the core

The runtime, @soloagent/core in packages/core, is a library too. Open it against a data directory and use it in-process, without the HTTP server.

import { SoloAgent } from "@soloagent/core";

const solo = await SoloAgent.open({ dataDir: "./data" });
// … create agents and threads, send messages …
await solo.close();

Durability

Agent runs execute on @earendil-works/pi-durable, Pi's durable execution harness, backed by SQLite in your data directory.

• Commit before show. Each model turn and each tool call is recorded as a durable step and committed before it's shown in any UI or chat app. Streaming text is saved as it arrives, so a crash loses at most about a second of a half-written answer.
• Resume after a crash. If the process exits mid-run (a crash, a restart, a deploy), the run resumes from its last committed step when the server starts again. Completed steps aren't repeated. An interrupted model request is retried; a tool call cut off midway runs again only if it's safe to repeat, and otherwise the agent is told it was interrupted.
• Durable sleep. Scheduled reminders and automations are durable timers. They wait in storage, not in memory, so they still fire after restarts. An automation that came due while the server was down runs once on startup.
• Durable approvals. A tool call waiting for approval has not started, so a restart simply asks again for the same request. Once approved, it runs once. The restart limit of Pi Durable still applies: after five restarts in a row while one request waits, that call ends with an error.
• Durable delegation. ask_agent starts a child conversation that is itself durable. The parent waits for it, across restarts if needed.
• Visible. The dashboard shows the live durable task graph and upcoming schedules.

Backups & upgrades

A backup is one .tar.gz of the data directory: consistent snapshots of both SQLite databases, agent workspaces, uploaded files, and a manifest.json. It's safe to take while agents are running.

soloagent backup                          # ./soloagent-backup-<time>.tar.gz
soloagent backup --out solo.tar.gz --url https://solo.example.com --token "$SOLOAGENT_TOKEN"
soloagent restore solo.tar.gz             # into ~/.soloagent/data, or --data <dir>

soloagent backup talks to your remote server or local server if one is configured or running. Otherwise it reads ~/.soloagent/data directly, or the directory you pass with --data. You can also download a backup from Settings in the dashboard, or GET /api/backup.

soloagent restore checks the archive before it touches anything: the manifest, every file's checksum, and each database's integrity. It refuses to run while a server is using that data directory, and it won't replace existing data without --force. With --force, the backups/ folder is kept.

With Docker Compose, the image has the CLI and uses /data:

docker compose exec -T soloagent soloagent backup --out - > solo.tar.gz
docker compose stop soloagent
docker compose run --rm -v "$PWD:/backup" soloagent soloagent restore /backup/solo.tar.gz --force
docker compose start soloagent

Secrets and restores

Provider logins and bot tokens are sealed with SOLOAGENT_SECRET, or with the .secret file generated in the data directory. Backups leave the secret out by default, so a restored server needs the same secret to open them:

• If you set SOLOAGENT_SECRET, set the same value on the restored server.
• If you didn't, either keep a copy of <data>/.secret somewhere safe, or back up with --include-secret. Anyone with that archive can then read every credential, so store it like a password.

The restore warns you when the secret is missing or doesn't match the one the backup was made with. Agents, threads, and memory don't depend on the secret; only credentials do.

Scheduled backups

Set SOLOAGENT_BACKUP_INTERVAL (24h, 6h, 30m…) and the server writes a backup to <data>/backups/ on that interval, keeping the newest SOLOAGENT_BACKUP_KEEP (default 7). Scheduled backups never include the secret. They sit on the same disk as your data, so copy them somewhere else too.

To send backups to S3 or any other object store, write to stdout with --out -:

soloagent backup --out - | aws s3 cp - s3://my-bucket/soloagent/$(date +%F).tar.gz
aws s3 cp s3://my-bucket/soloagent/2026-11-03.tar.gz - | soloagent restore - --data /var/lib/soloagent

Run the first line from cron on any machine that can reach the server, with SOLOAGENT_URL and SOLOAGENT_TOKEN set.

Moving agents between servers

Export writes every agent's settings (instructions, model, skills, and anything else stored on the agent) to JSON. Import matches agents by handle: new handles are created, and existing ones are updated (merge, the default) or left alone (skip-existing). Import never changes which agent is the default. The dashboard's Agents page has the same Export and Import buttons, with a preview before anything changes.

soloagent agents export > agents.json
soloagent agents import agents.json --dry-run
soloagent agents import agents.json --mode skip-existing

Upgrading

The server checks GitHub for a new release when it starts and every 12 hours. When there is one, the dashboard shows a note in the sidebar, Settings shows how to upgrade, and the terminal UI mentions it on its welcome screen. soloagent --version also says when an update is available; it checks at most once a day. Set SOLOAGENT_UPDATE_CHECK=0 to turn checks off.

Your data and unfinished durable work carry over. Database migrations run when the new version starts. Take a backup first.

Security

• The admin token and users. The API, TUI, and WebSocket take the admin token: SOLOAGENT_TOKEN, or the one generated on first boot. Treat it like a password and rotate it if it leaks. People sign in to the dashboard with their own name and password and an admin or member role. Sessions live in an HTTP-only cookie.
• Sealed credentials. Provider keys, OAuth tokens, connector tokens, webhook secrets, and MCP server env values and headers are encrypted at rest with AES-256-GCM, using a key derived from SOLOAGENT_SECRET or the secret generated in the data directory.
• Webhook secrets. Each webhook connector has its own shared secret, sent in x-solo-secret. It grants only that connector's access.
• Workspace is powerful. The Workspace skill can run shell commands on your server with the server's permissions; its folder is a starting point, not a sandbox. Chat apps can't reach such an agent unless you turn on its chat access; if you do, limit who can reach it with the connector's access lists.
• MCP servers run with your server's access. A stdio MCP server is a program running as the soloagent user, and an agent with its tools can do whatever those tools allow. See Tools (MCP).
• Your data stays with you. Threads, memory, schedules, and credentials live in your data directory. Model calls go directly from your server to the providers you connect.

Found a vulnerability? Please report it privately through GitHub security advisories.