One static binary
Download one file and run it. No runtime, no package manager, no daemon. Go all the way down.
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.
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 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.
Download one file and run it. No runtime, no package manager, no daemon. Go all the way down.
Anthropic, OpenAI, Gemini, Bedrock, Copilot, Groq, Cerebras, Mistral, DeepSeek, Ollama, and more built in, plus any OpenAI-compatible or Anthropic-compatible endpoint.
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.
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.
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.
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
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.
One static binary with all three layers in place, wired for software work. Most people start here, and never need to take it apart.
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.
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.
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.
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
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.
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
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.
$ 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
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.
Separate executables speaking JSON-RPC over a subprocess. None
installed by default; opt in with terva ext install.
Attach Model Context Protocol servers as tool providers, namespaced and permission-gated like everything else.
Veto, rewrite, or observe any tool call with your own pre/post tool-use scripts.
Fan work out to parallel background subagents from inside a session, each bootable as its own persona.
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.
Reusable instructions in SKILL.md files, discovered and
surfaced to the agent on demand.
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.
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
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 --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
$ 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
$ 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.
> 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 terva.sh/terva/cmd/terva@latest
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.
$ 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
terva web, the browser control panel and Stage