Minimal but Functional
The current TUI is functional but minimal: polling-oriented and plain text. A richer panel-based, live-streaming UX is planned and can be layered on top of the existing SSE event streaming APIs without changes to the daemon.
CLI / TUI
Current Interface Surface
The CLI provides run/validate/status/log flows. The TUI layers an interactive command mode on top of the daemon HTTP endpoints. Both communicate with the same daemon process.
CLI Commands
| Command | Description |
|---|---|
voidbox serve | Start the daemon HTTP server. All other commands (except validate) require the daemon to be running. |
voidbox run --file <spec> | Execute a spec file (agent, pipeline, or workflow). Submits the run to the daemon and streams events to stdout. |
voidbox validate --file <spec> | Validate a spec file without running it. Checks schema, skill references, and sandbox configuration for errors. |
voidbox status | Show daemon status and active runs. Displays run IDs, current stage, and elapsed time. |
voidbox logs <run-id> | Stream logs for a specific run. Follows the event stream until the run completes or is cancelled. |
voidbox tui | Launch the interactive TUI interface. Connects to the daemon and provides a command prompt for managing runs. |
voidbox snapshot create --config-hash <hash> | Create a snapshot from a running or stopped VM, keyed by its configuration hash. |
voidbox snapshot list | List all stored snapshots with their hash prefixes, sizes, and creation timestamps. |
voidbox snapshot delete <hash-prefix> | Delete a snapshot by its hash prefix. Removes the state file and memory dumps. |
Daemon API Endpoints
The daemon exposes an HTTP API used by both the CLI and TUI. These endpoints are also available for direct integration:
| Method | Path | Description |
|---|---|---|
POST | /v1/runs | Create a new run. Accepts a spec payload and returns a run ID. |
GET | /v1/runs/:id | Get run status. Returns current state, stage progress, and timing information. |
GET | /v1/runs/:id/events | Stream run events via Server-Sent Events (SSE). Provides real-time progress updates. |
POST | /v1/runs/:id/cancel | Cancel a running run. Sends SIGKILL to the guest process and tears down the VM. |
POST | /v1/sessions/:id/messages | Send a message to an active session. Used for interactive/conversational workflows. |
GET | /v1/sessions/:id/messages | Get session messages. Returns the full message history for a session. |
TUI Commands
The TUI provides an interactive command prompt connected to the daemon. Available commands:
| Command | Description |
|---|---|
/run | Start a new run from a spec file or inline definition. |
/input | Send input to an active interactive session. |
/status | Display the status of all active and recent runs. |
/logs | Stream logs for a specific run ID. |
/cancel | Cancel a running run by its ID. |
/history | Show the history of completed runs with their results. |