Terva: harness the wildcard

Terva: harness the wildcard

An agent harness in a single static Go binary, and a coding agent out of the box that is open to anything you can wire a tool to. One hardened core, one harness, many front ends, guardrails by default, pluggable in any language.

terva a recording, replayed from a session transcript at half speed

A token compare fixed in constant time. The agent asks before each edit and command; one is refused, one is widened to the session, and a question gets a note. Played at half speed.

$ curl -fsSL https://terva.sh/install.sh | bash

Windows: iwr -useb https://terva.sh/install.ps1 | iex · or go install, prebuilt binaries & source

what it is

one core, wide open

One hardened, test-backed agent core holds the loop, the event wire, and one interface to 25+ model providers. One harness around it holds the permission policy, sessions and credentials, and projects it through many front ends. Every piece is extensible in any language.

One static binary

Download one file and run it. No runtime, no package manager, no daemon. Go all the way down.

25+ providers

Anthropic, OpenAI, Gemini, Bedrock, Copilot, Groq, Cerebras, Mistral, DeepSeek, Ollama, and more built in, plus any OpenAI-compatible or Anthropic-compatible endpoint.

Guardrails by default

Approval modes from plan to yolo and typed permission rules. Built-in file tools stay scoped to the working directory and side-effecting foreign tools ask first. These are guardrails that steer the agent, not a kernel sandbox.

Operate any tool

Extensions, MCP servers, and hooks in any language, all speaking JSON-RPC over a subprocess, let terva drive services, hardware, or your own systems, and not only files.

Terminal and browser

Two first-class front ends: the TUI, and terva web, a browser control panel rather than a viewer. Same sessions, same permissions, same event stream; the TUI can even attach to a running terva web as a client, so a terminal outlives its connection. Plus your editor (over ACP), chat, -p print, --json, and a JSON-RPC server to embed it.

Consolidated & tested

One loop, one event wire, one policy, held as typed contracts rather than parallel reimplementations, with golden and end-to-end harnesses backing every change.

take what you need

three layers, any piece

The logo is the architecture. The wildcard at the centre is the agent core, the shell around it is the harness, and the block beneath is the base, where terva meets the world. Each layer stands on its own, so you can take the whole binary or only the piece you need.

The terva logo, pulled apart into the agent core, the harness and the base harness agent core base terva's harness + another agent terva's core + your harness
the whole of terva
  1. One static binary with all three layers in place, wired for software work. Most people start here, and never need to take it apart.

  2. The footer block. The front ends, which are the terminal, the browser, your editor over ACP, and chat, and the capability from outside the binary: tools, extensions, MCP servers, skills and connectors. Add or swap any of them, in any language, without touching the rest.

  3. The shell. terva's composition and its conventions: configuration, approval modes and permission rules, sessions on disk, credentials, and the daemon every front end talks to. Take it whole from Go with the SDK, or from any language over terva rpc.

  4. The wildcard. The loop and the wire: events, tools, the permission gate, compaction and cost, and one interface over every model provider. It reads no file and no environment variable, so your own program can host it with its own conventions. examples/harness is an agent built from the core alone.

  5. Put terva's core under a harness of your own. Or keep terva's harness and conventions and put another agent at the centre: terva can drive Claude Code as a worker, briefed from your project's AGENTS.md, asking terva for any approval it needs, with its progress on terva's task board. That one is off by default, behind external_workers_enabled. terva can also be the worker under someone else's harness, with terva rpc --portable. Embedding terva compares the ways in.

the other front end

drive it from a browser

terva web projects the same core over the wire: same sessions, same permissions, same event stream. It's a control panel, not a viewer: you drive the agent, approve its tool calls, and change its settings from it. The terminal is still home; this is for when the agent isn't running where you're sitting, such as an always-on bot, a long job on a server, or an approval that lands while you're on your phone.

The terva web panel on a desktop. An agent session audits a token check: it greps for verifyToken, reads auth.go, edits the == comparison to hmac.Equal, rendered as a diff, then runs go test and reports it green. A pane docked on the right shows the context breakdown: system prompt, tool defs, transcript, total.
Tool calls carry their diffs and output. The docked pane is the control surface: usage, settings, RAATI, permissions, chat.
The same terva session on a phone: a single column with the diff, the test output, and the message composer.
The same session, on a phone.

Loopback by default; it refuses a public bind without an auth mode. Pick a token, a forward-auth proxy, a scoped tailnet range, or single sign-on through an OpenID Connect provider, which shipped in v0.137.0 and is configured with a web_oidc block. See the web docs.

terva serve puts a supervisor in front of many daemons, so one host can give every person who signs in their own terva: a separate process with its own TERVA_HOME, its own sessions, its own MCP servers, and its own extensions. It refuses to start without single sign-on or a forward-auth proxy, because a shared token would resolve everyone to the same environment. A per-tenant home is a routing decision rather than a security boundary, so letting a second person in wants --containment systemd, which runs each tenant under a transient uid from a unit template. See the serve docs.

A fleet is one browser panel reading the sessions of terva daemons running on other machines. Members dial the hub and the hub never dials a member, so a laptop behind NAT can join without an inbound port, a public address, or a certificate. See the fleet docs.

who is helping

personas

A persona is a named identity with a short behavioral charter that focuses the agent on a specialty. Swap the default Mieli for a specialist, write your own, or get them from extensions, and let a coordinator dispatch a whole crew across a problem.

  • personas, who is helping
  • skills, how to do a task
  • tools & extensions, what can be done
terva persona
$ terva persona list
NAME                    SPECIALTY            SOURCE
Mieli                   coding / coordinator built-in
review-crew:Vartija     security review      built-in
review-crew:Arkkitehti  architecture review  built-in
…

$ terva --persona vartija "audit the auth flow"
$ terva --persona review-crew:luotain "find the hot path"

terva ships seventeen personas out of the box. Mieli takes the day-to-day coding work, and the seven-strong review crew below is built to be dispatched across a problem. RAATI seats three deliberation panelists, YATA-1, KUSANAGI-2 and MAGATAMA-3, who judge a question by truth, by decisiveness and by human impact, and who are convened as a panel rather than one at a time, because a lone panelist is an opinion and not a tally. Five more serve immersive play: Kertoja narrates a scene and voices its cast, Kartoittaja draws a seed several genuinely different ways, Seppä repairs a character card without overwriting its author, Toimittaja folds what a scene established back into a character, and Dramaturgi reads a played session for the lore and threads it has earned. Hautoja recruits for a Talkoot team: it interviews you about one job and proposes a member for you to approve.

open to anything

extend it, in any language

The harness talks to the outside world over small, versioned JSON protocols, so you teach terva new capabilities without touching its core, in whatever language you like.

Extensions

Separate executables speaking JSON-RPC over a subprocess. None installed by default; opt in with terva ext install.

MCP servers

Attach Model Context Protocol servers as tool providers, namespaced and permission-gated like everything else.

Hooks

Veto, rewrite, or observe any tool call with your own pre/post tool-use scripts.

Swarm

Fan work out to parallel background subagents from inside a session, each bootable as its own persona.

RAATI

Don't trust one model's first answer. Convene a panel of several models in distinct seats to argue a decision to a recorded verdict you can go back and read.

Skills

Reusable instructions in SKILL.md files, discovered and surfaced to the agent on demand.

Chat connectors

Built-in Telegram and Discord bridges let you approve tool calls from chat, with buttons on Discord, and external connectors in any language speak the same versioned protocol.

Your language, your words

Translate the UI, or override terva's wording and its model-facing prompts in place, key by key. Works in English too, when you just want it to say something else. See localization.

more than code

beyond the codebase

terva ships as a coding agent, but the harness underneath is general. Compose the layers, a persona or character card (who), an extension (what), a connector (where), and lore that surfaces the right context on cue, and point them away from a repo.

terva beyond code
$ terva --card ./char.png           # chat as a character card
$ terva --play --ext ./world        # act in a simulated world
$ terva --play --cast gm=./gm.png   # a director voices a cast
$ terva bot run --idle-nudge 30m    # a bot that breaks the silence

An extension doesn't have to be a tool. It can be a whole world, or a bridge to a real one. Its tools become the agent's senses and hands, its state the world's memory, a live context card its awareness of its surroundings. The agent perceives, decides, and acts on the same loop that edits code, pointed at a simulation, a service, or a piece of hardware.

The repo ships worked examples. examples/extensions/world is a procedural place an explorer travels through tools (look, travel, gather) with persisted state and a map, and examples/cards holds a SillyTavern character card you can chat as. A --play director can even voice a declared cast of actors, while lore surfaces authored context the moment it's relevant. The persona and extension docs show how to give an agent a world of your own.

Stage is the browser surface for that play: a second web app served by the same daemon, mounted at /stage/ alongside the control panel by --web-stage. It drives a character card or a persona through an immersive conversation or a roleplay rather than a coding session, and it shares the panel's transport, login, and workspace, so immersive sessions sit next to coding ones. It stays off by default while it matures. The web docs describe what it is made of.

drive it

usage

terva
$ terva                              # interactive tui
$ terva "fix the failing test"       # tui, pre-filled prompt
$ terva web                          # browser control panel
$ terva attach                       # reattach to a running daemon
$ terva -p "list all go files"       # print final text, exit
$ terva --json "refactor main.go"    # newline-delimited json events
$ terva --persona vartija            # launch as a specialist
$ terva --continue                   # resume the last session here
$ terva --resume                     # pick a session to resume

get it

install

one-liner for macOS and Linux
$ curl -fsSL https://terva.sh/install.sh | bash

Detects OS and architecture, downloads the latest release, verifies its SHA-256, and drops the binary on your $PATH.

one-liner for Windows, in PowerShell
> iwr -useb https://terva.sh/install.ps1 | iex

Drops terva.exe into $HOME\bin and adds it to your user PATH. Open a fresh terminal afterwards.

go install
$ go install terva.sh/terva/cmd/terva@latest
prebuilt binaries

Every release ships archives for Linux and macOS on amd64 and arm64, and Windows on amd64, plus a checksums.txt. There is no Windows arm64 build. Each platform comes as terva (full, with the desktop window: what the one-liner installs) and terva-min (lean: chat connectors and desktop left out); both unpack the same terva command. On Linux the full build needs glibc, so on musl the one-liner installs terva-min.

from source
$ git clone https://github.com/terva-sh/terva
$ cd terva
$ make build        # produces ./bin/terva

Then run terva and type /login. The TUI opens without credentials and walks you through browser-based auth: an API key or a Claude Pro/Max, ChatGPT Plus/Pro, Kimi, or GitHub Copilot subscription.

read more

documentation