VRSPI RUNTIME / DEVELOPMENT GUIDE

A shared workspace.
A connected workflow.

A practical guide to running and connecting coding agents in Vrspi.

Vrspi is in local development. These examples describe the current implementation, not a publicly released installer. Request early access ↗

Vrspi is a native terminal workspace manager built on Herdr. Its background server owns your terminals and agent processes. You interact through the terminal UI, CLI, or a local JSON socket API.

Getting started

Public downloads and supported release platforms have not been announced. If you already have a Vrspi development build installed, start it from a normal terminal:

vrspi

Launch your chosen coding agents in separate panes. Sign in through each agent’s own setup; Vrspi does not include model access or provider subscriptions.

Coming from Herdr? Compatibility names and session paths still use Herdr internally. An older server may use an incompatible protocol. Use a separate named development session instead of stopping active work.

HERDR_SESSION=vrspi-local vrspi

Run that command outside an existing managed pane. Collaboration commands below must run inside a recognized agent pane; they derive the caller from its managed environment.

Workspaces & sessions

Organize projects into workspaces, tabs, and terminal panes. The TUI is a client of the background runtime. Closing or detaching a client does not stop the server’s terminal processes.

Multiple clients can attach to a session. Agent state is classified as idle, working, blocked, done, or unknown using process and terminal-screen evidence.

Session persistence, live binary handoff, and cold restart are different operations. Collaboration messages and lobbies survive a live handoff, but do not currently recover after a cold server restart.

Connect your agents

Through the terminal UI

Focus a recognized agent pane.
Choose Call another agent from the pane menu, global menu, or the focused pane’s call chip.
Select another recognized agent, write a prompt, and send it.
Read the receipt. The runtime connects a lobby and retains the message.

To connect the workspace as a group, right-click an agent pane and choose Connect workspace agents. Open agent lobbies in the global menu to inspect members.

Through the CLI

From a managed agent pane, use the unique live name of your recipient (here, reviewer), or its pane ID:

vrspi agent self
vrspi agent list
vrspi agent lobby connect reviewer
vrspi agent message send reviewer "Review the parser boundary"

A shared active lobby opts agents into automatic delivery. Sending a message alone retains it for manual consumption; connecting a lobby also makes still-pending messages eligible for automatic delivery.

Follow the message

State	What it means
`pending`	Retained; not yet read or automatically submitted.
`observed`	The recipient read it through the mailbox API.
`injected`	The runtime accepted the terminal submission.
`acknowledged`	The recipient explicitly acknowledged the message.
`revoked`	Recalled by its sender; the retained body is erased.

Automatic delivery requires a recognized, live, idle agent in a shared lobby. Only the oldest eligible pending message is delivered, with at most one automatic message per idle → active → idle cycle.

Reading an inbound message marks it observed and suppresses later automatic delivery. Injected or acknowledged messages cannot be recalled.

vrspi agent message inbox --unacked
vrspi agent message ack msg_1
vrspi agent message send builder "Review complete" --reply-to msg_1

CLI reference

Use vrspi agent self to resolve the calling agent and its immutable instance ID. Message targets must be unique live agent names or current pane IDs, not bare agent-kind labels.

vrspi agent lobby list
vrspi agent message outbox
vrspi agent message get msg_1
vrspi agent message wait --after 0 --timeout 120000
vrspi agent message wait msg_1 --until acknowledged --timeout 120000
vrspi agent message revoke msg_2

Local JSON API

The TUI and CLI use the same server-owned collaboration methods. Here is an example request from a managed caller:

{
  "id": "connect",
  "method": "agent.lobby.connect",
  "params": {
    "caller_pane_id": "w1:p1",
    "target": "reviewer"
  }
}

Discover the schema bundled with your build:

vrspi api schema --json

Under the hood

Vrspi uses Rust, Tokio, Ratatui, and libghostty-vt. A server owns PTYs and shared session state; attached clients handle presentation and input. There is no Electron application and no required external database.

Identity follows the agent

A pane name or position may be reused. Collaboration instead binds messages to an immutable live agent instance. Moving or renaming the same agent preserves its identity; replacing it creates a new instance.

A local trust model

The socket uses same-OS-user trust. Agent attribution is not a security boundary against other processes running as your user. Peer messages are embedded as JSON and labeled as untrusted project context.

Current limitations

Messages and lobbies are not recovered after a cold restart.
Lobby leave, remove, delete, and rename operations are not implemented.
The lobby browser refreshes when opened or after a connection; it does not continuously stream membership changes.
The mailbox has a global limit of 1,024 messages, a 16 KiB body limit, and a maximum of 100 entries per list response.
Per-peer quotas and automatic reply-loop protection are not implemented.
A narrow crash window remains between accepting a terminal submission and recording its delivery. Do not assume exactly-once delivery across a process crash.

These are development constraints to consider when evaluating Vrspi. Contact us to discuss your workflow.

A shared workspace.A connected workflow.