Skip to content
Conduit

mcp server

ummanu

Portable AI agent orchestration appliance with shared memory, task pipelines, skills, and recovery across multiple CLI heads.

vladmesh/ummanucommunitylistedunreviewed
Use tool

Set up

Runs on your computer. Pick your agent and operating system.

Before you start

  • uv (`curl -LsSf https://astral.sh/uv/install.sh | sh`)
~/Library/Application Support/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "ummanu": {
      "command": "uvx",
      "args": [
        "ummanu"
      ]
    }
  }
}

same format Cursor, GitHub Copilot CLI, Junie, JetBrains AI Assistant, Augment (Auggie CLI), Factory Droid, Kiro, Devin CLI +12

Values in angle brackets are placeholders. Restart Claude Desktop after editing its config.Claude Desktop docs

README

synced Oct 17, 2026

ummanu

Portable personal appliance for running multiple AI agent heads across many projects from a remote VPS. The repository contains the CLI, the task and memory protocols, the dispatcher runtime, restore logic, schemas and generic skills.

The product repository holds no installation data. Private installation configuration and portable state live in the installation's live root, a plain directory; the snapshot exporter commits it into a local snapshot repository and pushes that to a private instance remote, the recovery checkpoint. Local mutable and derived runtime state lives in a local data directory. Install and recovery are documented in Recovery.

Documentation

  • Vision — what the appliance is for and who it is for
  • Roadmap — product states, milestones and open questions
  • Architecture — storage boundary, runtime flow, security model
  • Head runtime: runtime defaults, Docker guard, progress journal and prompt handoffs
  • Head scopes: scope ownership, memory exits and host reconciliation
  • Head vitality — observation axes, snapshots and their invariants
  • Outcome lineage — durable round handoffs between worker and reviewer launches
  • Board store — board read/write inventory and the PostgreSQL schema
  • Requests growth — the decision to keep every requests row
  • Owned cleanup — who settles dispatcher-owned Git residue
  • Protocols — command contracts for tasks, sprints, memory and secrets
  • Operations — runbooks for a running installation
  • Recovery — the checkpoint contract, fresh install and restore
  • Testing — CI suite taxonomy and local test boundaries
  • Old-name policy: allowed historical names and permanent guards

Install

The host bootstrap supports Ubuntu 24.04. Prepare its Python prerequisite, then run the checkout setup as the installation user from the product checkout (see Recovery for account, checkout and private-remote setup):

sudo apt-get update
sudo apt-get install --yes python3-venv
python3 -m venv .venv
.venv/bin/python -m pip install -e '.[memory,dev]'
ummanu_product_root=$(pwd -P)

The editable install is required because the runtime also uses deployment assets from the checkout. The shipped systemd units run PRODUCT_ROOT/.venv/bin/…, and upgrade installs dependencies only into that .venv. Install and recovery verify the selected environment before materializing the host.

Bootstrap the host first:

sudo "$ummanu_product_root/.venv/bin/ummanu" bootstrap --instance-remote REMOTE --instance-dir INSTANCE \
  --installation-user INSTALL_USER

For a new installation, continue with:

sudo "$ummanu_product_root/.venv/bin/ummanu" install --instance-remote REMOTE --instance-dir INSTANCE \
  --installation-user INSTALL_USER --product-root "$ummanu_product_root"

To rebuild an existing installation from its private checkpoint, use recover instead of install:

sudo "$ummanu_product_root/.venv/bin/ummanu" recover --instance-remote REMOTE --instance-dir INSTANCE \
  --installation-user INSTALL_USER --product-root "$ummanu_product_root"

Bootstrap installs Docker and Compose from the distribution and provisions the loopback-only postgres:16 board-store container and persistent volume, with its local mode-0600 ignored board-store.env, through the current Alembic head; see Board store.

Status

The project is pre-1.0. It is developed against one opinionated deployment profile: a single trusted owner running one appliance on one host. See SECURITY.md for the boundaries of that model.

Contributing

See CONTRIBUTING.md.

License

Apache License 2.0.

↑↓ navigate openesc close