Getting started

Tandem runs entirely on your machine. The desktop app launches a native window; the server flavor exposes a browser UI on 127.0.0.1:3000. Pick one, install in a single command, then create a project and dispatch your first agent in under ten minutes.

Install

Two distribution formats ship today. Both are self-hosted, both bind 127.0.0.1 only, neither requires Docker.

Linux — desktop app (recommended for 99%+ of users)

The Tauri-packaged tandem-desktop_<version>_amd64.deb is a native window: backend auto-starts on launch and stops on close. Place the .deb next to install.sh and run:

sudo bash install.sh
# or, pointing at a specific file:
sudo bash install.sh /path/to/tandem-desktop_0.4.758_amd64.deb

The installer verifies the signature, pulls system dependencies (libwebkit2gtk-4.1, libayatana-appindicator3, tmux, nodejs), and registers the desktop entry. Pass --skip-verify if you trust the source and want to bypass the sha256 sidecar check.

Linux — server flavor

The server .deb (tandem-server_<version>_amd64.deb or legacy tandem_<version>_all.deb) installs as a user systemd service exposing the browser UI on 127.0.0.1:3000. Same installer:

sudo bash install.sh /path/to/tandem-server_0.4.758_amd64.deb

The installer auto-detects the flavor from the .deb filename, sets up tandem-backend.service for the desktop user (via SUDO_USER), and opens the browser to http://127.0.0.1:3000 when finished.

macOS — tarball (Tier 1)

The Mac path ships as tandem-<version>-macos.tar.gz with a sha256 sidecar. Install is sudo-free; Homebrew is the only step that may prompt for an admin password:

bash install-mac.sh
# or with options:
bash install-mac.sh --skip-brew /path/to/tandem-0.4.758-macos.tar.gz
bash install-mac.sh --browser=safari /path/to/tandem-0.4.758-macos.tar.gz

Installs to $HOME/Applications/Tandem as a launchd LaunchAgent. On any stage [4/7]–[7/7] failure the script writes a diagnostic snapshot to <tarball-dir>/tandem-install-logs/install-diagnostics.log — paste that file when reporting issues.

Platform notes

• Backend: Python 3 stdlib only (no pip install at runtime). Subpackages that pull deps declare them in their own requirements-<pkg>.txt — for example requirements-socials.txt for the Slack/Discord/Telegram engine.
• Frontend: Next.js + Tailwind + shadcn/ui, served by the desktop app or the user systemd unit. Always bound to 127.0.0.1; never 0.0.0.0.
• Terminal: a Node node-pty WebSocket server runs on 127.0.0.1:4201 with tmux session persistence — closing the browser does not kill the job.
• Sandbox (optional): agent-generated code can run inside bwrap (bubblewrap) via systemd-run; admin-gated, off by default. Verify host compatibility with python3 -m sandbox.prereq.

Verify it works

Once the installer finishes, browse to http://127.0.0.1:3000. The Dashboard route shows three green status pills (API · Terminal · Frontend) when all services are live. If any pill is red, run mc.py health and mc.py fix from the install directory.

First project

Projects are the unit Tandem groups work by. Each project pins a directory, a default agent set, and its own task pipeline. Five steps:

1. Open the Projects page. Browse to http://127.0.0.1:3000/projects (or click Projects in the sidebar under the Bench group). The list is empty on a fresh install — that is expected.

2. Click “New project”. Enter the project name (kebab-case is enforced), the absolute path to the working directory, and an optional description. The backend stores the row in tandem.db; nothing else on disk is touched.

3. Confirm the registration. The page now lists your project. The archived flag defaults to 0, meaning the project shows up in default filters everywhere.

4. Pin or scaffold the project. From the CLI: python3 mc.py scaffold <Project> drops a baseline directory layout (tasks folder, daily notes, README) at the registered path; safe to skip if you already have one.

5. Add your first task. Either click “Add task” on the Kanban (/kanban) page, or run python3 mc.py add-task <Project> "<title>" --priority medium. The task lands in tasks/<slug>.md as a markdown file with YAML frontmatter — Obsidian sees it instantly, and the Kanban view picks it up on next refresh.

Why markdown, not a database row?

Tasks live in vault markdown so they are visible from inside Obsidian, grep-able from the shell, and diff-able in git. The single source of truth is tasks/*.md; tandem.db holds projects, sessions, approvals, and audit rows only.

First agent

Tandem ships with a roster of named agents declared in agents.json — COO, Architect, Executor, Verifier, Tracer, Vault, Website, Repo Scout, YouTube Scout, Code Reviewer, Security Reviewer, TDD Guide, Refactor Cleaner, Doc Updater, Build Error Resolver, Browser CDP, Codex CLI, Grok-Swarm, plus the Spark template family. Each agent has its own system_prompt, allowed_tools, allowed_dirs and MCP config.

Pick an agent

Open the Agents page (http://127.0.0.1:3000/agents, sidebar Crew → Agents). The card grid shows every agent registered in agents.json with a live heartbeat dot. For your first run, pick Executor — it has worktree isolation enforced and a wide-enough toolset to ship a small change end to end.

Run a task

1. From the task card on /kanban, click Claim and select Executor — this calls mc.py claim-task <id> executor, which atomically locks the task in SQLite so two agents can never grab the same row.

2. The task status flips to active. A chat pane spawns at /chats and routes through the same tmux substrate as the Terminal page, so the agent’s stdout streams live.

3. When the agent finishes, it moves the task to review with an ## Activity Log section appended and any ## Verification evidence. You either mark it done or kick it back.

Or dispatch from the CLI

# Pick an existing task ID from the Kanban or the CLI:
python3 mc.py tasks

# Claim it for a specific agent:
python3 mc.py claim-task <id> executor

# Open a fresh chat for that agent in a worktree-isolated branch:
python3 mc.py spawn-chat --agent executor --task <id>

Worktree isolation

Writing agents (Executor, Vault, Website, etc.) run in .claude/worktrees/agent-<id> on their own branch; .claude/hooks/enforce-worktree.sh blocks vault-root writes. After the agent returns, post-agent-snapshot.sh auto-commits any dirty worktree as a safety net. Read-only agents (Architect, code-reviewer) are exempt.

Dashboard tour

The frontend exposes 31 pages organized into five sidebar groups: Bench, Crew, Pulse, Reach, Stack. The four pages below get you from zero to fleet visibility.

Page	Route	What it does
Kanban	/kanban	Drag tasks across the seven-stage pipeline (inbox → planning → human_turn → active → review → paused → done). One row per project; each card carries status, priority, retry counter, token budget, and dependency arrows.
Tasks	/tasks	Markdown task list backed by Obsidian Bases. Sort by status, priority, days-open, project. Click a row to open the underlying tasks/<slug>.md file directly.
Agents	/agents	The fleet view. Per-agent card with heartbeat dot, last-active timestamp, current task, live token spend. Click into an agent for its chat history and per-agent ACL.
Approvals	/approvals	Human-in-the-loop inbox. Every agent action that touches money, the network, or disk outside its allowed_dirs blocks here until you approve or reject. Backed by the append-only approvals table.

Beyond those four:

• Costs (/costs, sidebar Pulse → Costs) reads real Anthropic-shape token counts from claude --print JSONL transcripts — every dollar attributed to the agent that spent it.
• Terminal (/terminal, sidebar Bench → Terminal) is a real node-pty shell with tmux persistence, 22 themes, multi-pane grids (2 / 2×2 / 3×4 / 4×4) and drag-drop reorg.
• Wiki (/wiki, sidebar Stack → Wiki) surfaces compiled knowledge pages under wiki/*.md; the ingestion pipeline writes here from raw/.
• Admin (/admin) surfaces mc_settings toggles, including agent_restart_mode (governs whether an agent may restart services without asking). See Configuration.

What next

Open Features for the full capability map across nine domains, or jump to Configuration for the agents.json schema, mc_settings toggles, env vars and service-restart commands.