Reference

openovai — the user-level command

One POSIX shell script at ~/.local/share/openovai/openovai, linked as ~/.local/bin/openovai. Read from a pipe — curl -fsSL https://raw.githubusercontent.com/nilcaream/openovai/main/openovai | sh — it installs itself there and says so; if ~/.local/bin is not on PATH it prints the line to add to your shell profile and never edits one. Run from its place it resolves a release, prints it, downloads it once under ~/.local/share/openovai/releases/<version>/ and hands over to that release's installer. It knows one option of its own:

The same installer is also published on npm as @openovai/ovai, for a machine with Node.js 24 or newer: npx @openovai/ovai@latest --root … takes every option above except the version, which is named as @openovai/ovai@<version>. The package is the release, so the installer needs no download and no openovai command is left behind; the Node.js and Claude Code it pins are fetched at the first ovai start, with the tools in the requirements below. @latest is written out because npx reuses a copy it has cached for a name given with no version. npm refuses it on any system but Linux and macOS.

ovai — the instance's command

<instance>/bin/ovai, one per instance. Bare ovai prints the help.

The instance directory

This, and nothing else ever lands in it.

A fresh instance directory is exactly that list without runtime.json, runtime.log, the page's keys, introduced, claude-variables and archive/, which appear at the first start and the first retire. The directory is open to its owner alone, and so are the files that hold its address and keys.

openovai.json

Read when the server starts. The customization page says what each one does; the defaults page has every value that is not a key.

The typing hold

A seat waits for you while you type to it. When something arrives for a seat — a Worker's message, a server event — while you are typing in that seat's box, the seat does not start on it straight away: it waits until you send your line or stop typing, so what you were about to say goes in with it instead of landing behind a turn spent on something else.

What is held, and what is not:

• Only a turn made of Worker messages and server events, and only before it begins. A turn already under way runs on: the server cannot pause a session between its own tool calls.
• Your own line is never held. Pressing Enter takes whatever is waiting in with it, as one turn, in the order it all arrived.
• Only the seat whose box you are typing in. Every other seat carries on as before.
• A keystroke counts, text sitting in the box does not: a box you walked away from with words still in it holds nothing once the quiet has run out.

Two settings, under typing in openovai.json, both in seconds:

"typing": { "quiet": 10, "cap": 30 }

0 in either one turns the hold off. A value that is not a number, or is below 0, is taken as the default. The server reads openovai.json when it starts: a change takes effect at ovai restart.

A timeline with the defaults, on the Leader's panel:

1. Typing, a message arrives, Enter. You start typing at 14:00:00. At 14:00:04 a Worker's message arrives and the Leader, idle, does not start on it. At 14:00:09 you press Enter: your line and the message go in together as one turn, the message first because it arrived first.
2. Typing stops without sending. You type from 14:00:00 to 14:00:03 and stop, the words left in the box. At 14:00:04 a Worker's message arrives and is held. Ten seconds after the last keystroke the server heard, at about 14:00:13, it goes in on its own.
3. Typing past the cap. You type without a pause from 14:00:00. At 14:00:04 a Worker's message arrives and is held. At 14:00:34 the cap is reached and it goes in while you are still typing. When you send your line it reaches that turn the way any line of yours does: at the turn's next tool call, or after the turn if none is left.

What runtime.log shows: one row when a hold starts, and the usual wrote row when it ends, with how long it held and what ended it — user (your line), quiet or cap:

held <seat> - typing, 1 waiting
wrote <seat> - queue x2 (#41..#42: message, user), 0 waiting, after typing held 5.0s (user)

The sixteen tools

Served over POST /mcp/<secret>, one secret per process, and named mcp__openovai__<tool> to the session. Five go to every seat, one is the Workers' and ten are the Leader's; a seat asking for one that is not its own is refused in words.

The roster hire names from is a fixed list of thirty first names — Paul, Jane, Jack, Pete, Anna, Mark, Lucy, Tom, Eva, Sam, Nora, Ben, Mia, Leo, Zoe, Max, Ivy, Finn, Ada, Noah, Ella, Owen, Ruby, Hugo, Iris, Otto, Lena, Axel, Nina, Theo — and the next name is the least recently used free one: never used first, in that order, then the one whose holder left longest ago, read from the desk file under archive/; a name is taken while desks/<Name>/ exists. With nobody in the pool free, Dev and three digits, and the hire's answer says so, with how many of the desks are stopped Workers to retire once nothing open names them.

Server events

A frame the server sets itself, <server-event type="…">, queued like a turn and ahead of the rest when it has to be. Nothing inside a message can pose as one. There are nineteen.

A change to customization/ or to knowledge/common.md reaches the sessions started after it and no others: there is no frame that hands a running session a change to its standing instructions. When something has to reach a session that is running, tell it in words, or restart it: restart_worker for a Worker.

The seeded permission rules

.claude/settings.json, written once at install. Every path rule starts with /, anchored at the instance directory. An update adds no rule; it wires the subagent hook into a file that lacks it, takes out the shell hook versions before 0.26.0 ran, and turns commit attribution off in one that says nothing about it.

Also seeded: attribution with an empty commit and pr and sessionUrl false, so a commit says what its message says; and the hook lib/hooks/subagent.mjs when a subagent starts, which hands it customization/common.md in the frame a seat reads it in, and nothing when there is none. It is named as sh "${CLAUDE_PROJECT_DIR}/lib/hooks/run.sh" subagent, which runs it on the Node.js the instance's version pins. No hook runs before a shell command. The instance's Claude Code home turns the built-in memory off.

runtime.log

Every row has the same four columns, single spaces, then the text. No request is ever logged. Every row is masked as it is written: a key, a token, a password in a URL, an Authorization header, a --token-style flag or a SECRET=-style assignment is written as ***. The rows of every panel are masked the same way, before they are kept.

<moment> <event> <seat> <id> <text…>
2026-09-20T02:15:33.123+02:00 started - - serving /home/ana/workspace at http://127.0.0.1:7357 pid
41200 host box user ana version 0.21.0 2026-09-20T02:15:41.530+02:00 called Max
toolu_01HMVftEemFhWAccN3xSqn7a mcp__openovai__write_desk 2026-09-20T02:15:41.532+02:00 tool Max
toolu_01HMVftEemFhWAccN3xSqn7a mcp__openovai__write_desk in 1 ms 2026-09-20T02:15:44.210+02:00
queued Paul - message #54, 1 waiting 2026-09-20T03:02:10.884+02:00 stopped Paul - idle
2026-09-20T03:40:00.117+02:00 stopped - - SIGTERM

The pid, the host, the user and the version are on the started row and on no other. A session's process gone is one stopped row after the last row of its calls, saying what it ended as — stop, restart, idle, quota, park, idle-forced, stop-deadline, park-deadline, first-turn-failed — or, for one that ended on its own, how: exit 1, SIGKILL. The server's own going out is the last row of its run, stopped - - SIGTERM.

A day can be read back from the file. hired says a Worker was started on a desk, what it runs on, and whether the desk was new or one it had. retired says a desk was filed away, the model that round ran on, and where the desk went. restart says how full the session that restarted was, in tokens, so "it filled up" is a number rather than a story. quota says which usage window crossed a threshold, the percentage it stood at, when it resets, and the model when the window is one model's own. held says a turn waits, for a quota window or while you type on the seat's panel (the typing hold), and released that it was let go. checkpoint says a Worker reached the number of calls the Leader set. died says the service refused a turn, in the service's own words, and closed that a close reached its deadline with no desk written, and when the desk last was. leftovers says what a seat left running was ended with its session.

The plugin contract

plugins/<name>.mjs; the name is the tool's. Read once, when the server starts.

Each is one plugins row in runtime.log naming the file and the reason. The plugins page walks through one.

Requirements

Node.js, npm and Claude Code are not requirements: each release pins the exact versions it was tested with, in lib/RUNTIME, and the installer fetches them under ~/.local/share/openovai/, per user, shared between instances, used by absolute path. This release pins Node.js 24.21.0 and Claude Code 2.1.314. Nothing global, no sudo.