The head for your harnesses.
Truss is a web frontend for AI agent harnesses. It is not a harness itself, it hosts them. Run pi, Claude Code, DeepSeek Harness, and Hermes side by side, pick a harness per chat, and watch all of them through the same interface. You get dockable tab windows, real terminals, a trajectory view that works like the Chrome network tab but for model calls, context tracking, a subagent tree, a task board, todos, and an inbox for things agents hand back to you.
Warning
Truss is very beta. One person builds it and it moves fast. Expect
breaking changes between commits, rough edges, and migrations that might
not be graceful. Do not put it on the public internet (see
Security model). Back up apps/server/data/ if you care
about what's in it. That said, it is a real working app that gets used
every day, and issues and PRs are welcome.
- Every harness in one UI. Chat, streaming, interrupt, permission cards, and dead sessions that resume with their history intact.
- A real workspace. Split panes any direction, each pane has its own tab bar, tabs drag between panes and between workspaces (think virtual desktops), and the layout persists. Tabs shrink to fit like Chrome; the close button shows on hover, or sits inline when there's room.
- Trajectory. Every LLM call with model, latency, tokens, cost (cache reads and writes too). Expand a call to see the tools that ran inside it. Retries and failures stand out.
- Feed. Your inbox. Permission requests you can answer from the card, finished-work notes, crashes, context-window warnings, and reports agents post. Sort, filter, save, dismiss, or share a card into another agent's chat.
- Todos. Agents file tasks for you (the
file_todotool) with priority, deadline, labels, subtasks, and estimates. Four views: grouped list, priority board, table, deadline calendar. A session can only edit its own todos unless you approve an access card. - Tasks board. A kanban of prompts you run as sessions. Agents can file and run cards through the
mcp__truss__*tools too. - Terminals. Real shells (xterm.js + node-pty) in tabs. Free shells, or a shell in a session's working directory.
- Files, Git, Skills. Browse and edit the workspace tree. Branch switcher, changes with diffs, commit graph. A skill explorer with enable/disable, create, and trash.
- Context, Team, Cost, Credentials, Router, Hosts. Occupancy gauges, subagent trees, a cost ledger with a daily heat grid, and management UIs for a local key proxy, a model router, and remote node agents.
- TRUSS.md practices. Like CLAUDE.md but for Truss. A global file plus per-project and per-folder layers, handed to agents so they follow your coding and posting conventions.
- Live sync. The event bus has a heartbeat and reconnects cleanly. Open it on two devices and both stay current.
- Agents can drive Truss itself. Sessions, prompts, terminals, tasks, todos, feed, workspaces, and layout are all MCP tools (
POST /mcp/truss).
You need: Node.js 22 or newer, pnpm (corepack enable && corepack prepare pnpm@latest), and at least one harness CLI on your PATH (pi, claude, dsh, or hermes) with working models.
git clone https://github.com/roowus/truss.git
cd truss
pnpm install
# dev: fastify on :4040 (tsx watch) + vite on :4041 (proxies /api and /events)
pnpm dev
# open http://127.0.0.1:4041No harnesses handy? Add ?demo to the URL. The whole UI runs in the browser against a fake backend that speaks the real event contract.
Running it for real:
pnpm -C apps/web build # builds the single-file web app into apps/web/dist
pnpm -C apps/server start # serves the app + REST + WS on 127.0.0.1:4040Environment variables:
| Var | Default | What it does |
|---|---|---|
TRUSS_PORT |
4040 |
server port |
TRUSS_HOST |
0.0.0.0 |
bind address |
TRUSS_PUBLIC_URL |
unset | the operator-declared front door when a reverse proxy or public DNS name forwards to this server — remote-host installs refuse any return address the bind can't answer, and this is the escape hatch that whitelists yours |
TRUSS_DATA_DIR |
apps/server/data |
where the SQLite store lives (sessions, transcripts, todos, feed, layout) |
TRUSS_AGENT_TOKEN |
truss-dev |
shared secret for remote node agents |
TRUSS_WEB_DIST |
apps/web/dist |
override the served web build |
TRUSS_TRANSCRIBE_URL |
unset | OpenAI-compatible /audio/transcriptions endpoint behind POST /api/transcribe (voice dictation). Unset: dictation uses the browser's own speech recognition where available |
TRUSS_TRANSCRIBE_MODEL |
whisper-1 |
model field sent to the transcription endpoint |
TRUSS_TRANSCRIBE_API_KEY |
unset | bearer token for the transcription endpoint |
TRUSS_TRANSCRIBE_TIMEOUT_MS |
120000 |
deadline for one transcription request |
Multiple devices: serve it over your private network (tailscale serve, your LAN, an SSH tunnel). All devices stay in sync on their own.
Import existing DSH sessions: POST /api/import/dsh (there's a sidebar button) imports saved DeepSeek Harness sessions with transcripts and resume refs.
Truss is a single-user, fully trusted local app. The server has no auth at all, and agents can run shell commands by design. Bind to loopback or your private network only. Do not expose it publicly without putting real auth in front of it.
- Web: React 19, Vite, Tailwind 4, Dockview, xterm.js (single-file build)
- Server: Fastify (Node 22), WebSocket event bus, SQLite (better-sqlite3)
- Protocol: ACP at the harness boundary, plus an internal event schema (
packages/proto) - docs/architecture.md has the system layout and data flow
- docs/adapters.md has the per-harness integration notes
- docs/ui-handoff-v2.md is the UI redesign brief
- PLAN.md is the milestone log
pnpm -r run lint # typecheck everything
pnpm -r run build # build web + server
pnpm test # unit + adapter + store tests (node:test, no network)Every change ships with tests in the same commit. See TRUSS.md for the house rules. CI runs lint, build, and the test suite on every push and PR.
MIT © 2026 roowus