Skip to content

Commit fddc50b

Browse files
dpsoftdpsoft
authored
Merge pull request #27 from the-void-ia/feat/site-improvements
site improvements
2 parents 43d4409 + 5a07a1e commit fddc50b

File tree

24 files changed

+2451
-571
lines changed

24 files changed

+2451
-571
lines changed

‎README.md‎

Lines changed: 37 additions & 441 deletions
Large diffs are not rendered by default.

‎site/assets/css/site.css‎

Lines changed: 421 additions & 67 deletions
Large diffs are not rendered by default.

‎site/assets/img/void-box-openclaw-demo-2x.mp4‎

1.53 MB
Binary file not shown.

‎site/assets/js/site.js‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -98,4 +98,14 @@
9898
history.replaceState(null, '', id);
9999
});
100100
}
101+
// Scroll fade-in
102+
var faders = document.querySelectorAll('.fade-in');
103+
if (faders.length && 'IntersectionObserver' in window) {
104+
var obs = new IntersectionObserver(function(entries) {
105+
entries.forEach(function(e) {
106+
if (e.isIntersecting) { e.target.classList.add('visible'); obs.unobserve(e.target); }
107+
});
108+
}, { threshold: 0.15 });
109+
for (var i = 0; i < faders.length; i++) obs.observe(faders[i]);
110+
}
101111
})();

‎site/docs/architecture/index.html‎

Lines changed: 186 additions & 11 deletions
Large diffs are not rendered by default.

‎site/docs/cli-tui/index.html‎

Lines changed: 90 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
<!doctype html>
22
<html lang="en"><head>
33
<meta charset="utf-8" /><meta name="viewport" content="width=device-width,initial-scale=1" />
4-
<title>void-box cli and tui</title><link rel="stylesheet" href="../../assets/css/site.css" />
4+
<title>CLI + TUI | Void-Box</title><link rel="stylesheet" href="../../assets/css/site.css" />
55
<!-- Google tag (gtag.js) -->
66
<script async src="https://www.googletagmanager.com/gtag/js?id=G-YRRVNN7VM4"></script>
77
<script>
@@ -12,32 +12,105 @@
1212
gtag('config', 'G-YRRVNN7VM4');
1313
</script>
1414
</head><body>
15-
<header class="site"><div class="wrap inner"><a class="brand" href="../../"><img src="../../assets/img/void-box.png" alt="void-box logo" /><span>Void-Box</span></a><nav class="top"><a href="../">Docs</a><a href="../runtime/">Runtime</a><a href="../events-observability/">Events</a><a class="star-btn" href="https://github.com/the-void-ia/void-box" target="_blank" rel="noreferrer">&#9733; Star</a></nav></div></header>
15+
<header class="site"><div class="wrap inner"><a class="brand" href="../../"><img src="../../assets/img/void-box.png" alt="void-box logo" /><span>Void-Box</span></a>
16+
<nav class="top">
17+
<a href="../">Docs</a>
18+
<a href="../../guides/">Guides</a>
19+
<a href="https://github.com/the-void-ia/void-box" target="_blank" rel="noreferrer">GitHub</a>
20+
<a class="star-btn" href="https://github.com/the-void-ia/void-box" target="_blank" rel="noreferrer">&#9733; Star</a>
21+
</nav>
22+
</div></header>
23+
1624
<main class="doc-main wrap">
25+
<div class="doc-layout">
26+
<aside class="doc-sidebar">
27+
<nav>
28+
<strong>Docs</strong>
29+
<a href="../architecture/">Architecture</a>
30+
<a href="../runtime/">Runtime Model</a>
31+
<a class="active" href="../cli-tui/">CLI + TUI</a>
32+
<a href="../events-observability/">Events + Observability</a>
33+
<a href="../oci-containers/">OCI Containers</a>
34+
<a href="../snapshots/">Snapshots</a>
35+
<a href="../host-mounts/">Host Mounts</a>
36+
<a href="../security/">Security</a>
37+
<a href="../wire-protocol/">Wire Protocol</a>
38+
</nav>
39+
</aside>
40+
<div class="doc-content">
41+
1742
<section>
1843
<div class="kicker">CLI / TUI</div>
1944
<h1>Current Interface Surface</h1>
20-
<p>The CLI provides run/validate/status/log flows and a TUI command mode layered on daemon HTTP endpoints.</p>
21-
<div class="grid-2">
22-
<article class="card"><h3>CLI Commands</h3><p><code>serve</code>, <code>run</code>, <code>validate</code>, <code>status</code>, <code>logs</code>, <code>tui</code></p></article>
23-
<article class="card"><h3>TUI Commands</h3><p><code>/run</code>, <code>/input</code>, <code>/status</code>, <code>/logs</code>, <code>/cancel</code>, <code>/history</code></p></article>
24-
</div>
45+
<p>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.</p>
2546
</section>
47+
2648
<section>
27-
<h2>Daemon APIs used by TUI</h2>
28-
<ul>
29-
<li><code>POST /v1/runs</code></li>
30-
<li><code>GET /v1/runs/:id</code></li>
31-
<li><code>GET /v1/runs/:id/events</code></li>
32-
<li><code>POST /v1/runs/:id/cancel</code></li>
33-
<li><code>POST /v1/sessions/:id/messages</code></li>
34-
<li><code>GET /v1/sessions/:id/messages</code></li>
35-
</ul>
49+
<h2>CLI Commands</h2>
50+
<table>
51+
<thead>
52+
<tr><th>Command</th><th>Description</th></tr>
53+
</thead>
54+
<tbody>
55+
<tr><td><code>voidbox serve</code></td><td>Start the daemon HTTP server. All other commands (except <code>validate</code>) require the daemon to be running.</td></tr>
56+
<tr><td><code>voidbox run --file &lt;spec&gt;</code></td><td>Execute a spec file (agent, pipeline, or workflow). Submits the run to the daemon and streams events to stdout.</td></tr>
57+
<tr><td><code>voidbox validate --file &lt;spec&gt;</code></td><td>Validate a spec file without running it. Checks schema, skill references, and sandbox configuration for errors.</td></tr>
58+
<tr><td><code>voidbox status</code></td><td>Show daemon status and active runs. Displays run IDs, current stage, and elapsed time.</td></tr>
59+
<tr><td><code>voidbox logs &lt;run-id&gt;</code></td><td>Stream logs for a specific run. Follows the event stream until the run completes or is cancelled.</td></tr>
60+
<tr><td><code>voidbox tui</code></td><td>Launch the interactive TUI interface. Connects to the daemon and provides a command prompt for managing runs.</td></tr>
61+
<tr><td><code>voidbox snapshot create --config-hash &lt;hash&gt;</code></td><td>Create a snapshot from a running or stopped VM, keyed by its configuration hash.</td></tr>
62+
<tr><td><code>voidbox snapshot list</code></td><td>List all stored snapshots with their hash prefixes, sizes, and creation timestamps.</td></tr>
63+
<tr><td><code>voidbox snapshot delete &lt;hash-prefix&gt;</code></td><td>Delete a snapshot by its hash prefix. Removes the state file and memory dumps.</td></tr>
64+
</tbody>
65+
</table>
3666
</section>
67+
68+
<section>
69+
<h2>Daemon API Endpoints</h2>
70+
<p>The daemon exposes an HTTP API used by both the CLI and TUI. These endpoints are also available for direct integration:</p>
71+
<table>
72+
<thead>
73+
<tr><th>Method</th><th>Path</th><th>Description</th></tr>
74+
</thead>
75+
<tbody>
76+
<tr><td><code>POST</code></td><td><code>/v1/runs</code></td><td>Create a new run. Accepts a spec payload and returns a run ID.</td></tr>
77+
<tr><td><code>GET</code></td><td><code>/v1/runs/:id</code></td><td>Get run status. Returns current state, stage progress, and timing information.</td></tr>
78+
<tr><td><code>GET</code></td><td><code>/v1/runs/:id/events</code></td><td>Stream run events via Server-Sent Events (SSE). Provides real-time progress updates.</td></tr>
79+
<tr><td><code>POST</code></td><td><code>/v1/runs/:id/cancel</code></td><td>Cancel a running run. Sends SIGKILL to the guest process and tears down the VM.</td></tr>
80+
<tr><td><code>POST</code></td><td><code>/v1/sessions/:id/messages</code></td><td>Send a message to an active session. Used for interactive/conversational workflows.</td></tr>
81+
<tr><td><code>GET</code></td><td><code>/v1/sessions/:id/messages</code></td><td>Get session messages. Returns the full message history for a session.</td></tr>
82+
</tbody>
83+
</table>
84+
</section>
85+
86+
<section>
87+
<h2>TUI Commands</h2>
88+
<p>The TUI provides an interactive command prompt connected to the daemon. Available commands:</p>
89+
<table>
90+
<thead>
91+
<tr><th>Command</th><th>Description</th></tr>
92+
</thead>
93+
<tbody>
94+
<tr><td><code>/run</code></td><td>Start a new run from a spec file or inline definition.</td></tr>
95+
<tr><td><code>/input</code></td><td>Send input to an active interactive session.</td></tr>
96+
<tr><td><code>/status</code></td><td>Display the status of all active and recent runs.</td></tr>
97+
<tr><td><code>/logs</code></td><td>Stream logs for a specific run ID.</td></tr>
98+
<tr><td><code>/cancel</code></td><td>Cancel a running run by its ID.</td></tr>
99+
<tr><td><code>/history</code></td><td>Show the history of completed runs with their results.</td></tr>
100+
</tbody>
101+
</table>
102+
</section>
103+
37104
<section>
38105
<h2>Known UX Gap</h2>
39-
<p>Current TUI is functional but minimal: polling-oriented and plain text. A richer panel-based, live-streaming UX can be layered on top of event streaming APIs.</p>
106+
<article class="card">
107+
<h3>Minimal but Functional</h3>
108+
<p>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.</p>
109+
</article>
40110
</section>
111+
112+
</div>
113+
</div>
41114
</main>
42115
<footer><div class="wrap"><a href="../">← Docs</a></div></footer>
43116
<script src="../../assets/js/site.js"></script>

‎site/docs/events-observability/index.html‎

Lines changed: 138 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
<!doctype html>
22
<html lang="en"><head>
33
<meta charset="utf-8" /><meta name="viewport" content="width=device-width,initial-scale=1" />
4-
<title>void-box events and observability</title><link rel="stylesheet" href="../../assets/css/site.css" />
4+
<title>Events + Observability | Void-Box</title><link rel="stylesheet" href="../../assets/css/site.css" />
55
<!-- Google tag (gtag.js) -->
66
<script async src="https://www.googletagmanager.com/gtag/js?id=G-YRRVNN7VM4"></script>
77
<script>
@@ -12,28 +12,154 @@
1212
gtag('config', 'G-YRRVNN7VM4');
1313
</script>
1414
</head><body>
15-
<header class="site"><div class="wrap inner"><a class="brand" href="../../"><img src="../../assets/img/void-box.png" alt="void-box logo" /><span>Void-Box</span></a><nav class="top"><a href="../">Docs</a><a href="../architecture/">Architecture</a><a href="../cli-tui/">CLI/TUI</a><a class="star-btn" href="https://github.com/the-void-ia/void-box" target="_blank" rel="noreferrer">&#9733; Star</a></nav></div></header>
15+
<header class="site"><div class="wrap inner"><a class="brand" href="../../"><img src="../../assets/img/void-box.png" alt="void-box logo" /><span>Void-Box</span></a>
16+
<nav class="top">
17+
<a href="../">Docs</a>
18+
<a href="../../guides/">Guides</a>
19+
<a href="https://github.com/the-void-ia/void-box" target="_blank" rel="noreferrer">GitHub</a>
20+
<a class="star-btn" href="https://github.com/the-void-ia/void-box" target="_blank" rel="noreferrer">&#9733; Star</a>
21+
</nav>
22+
</div></header>
23+
1624
<main class="doc-main wrap">
25+
<div class="doc-layout">
26+
<aside class="doc-sidebar">
27+
<nav>
28+
<strong>Docs</strong>
29+
<a href="../architecture/">Architecture</a>
30+
<a href="../runtime/">Runtime Model</a>
31+
<a href="../cli-tui/">CLI + TUI</a>
32+
<a class="active" href="../events-observability/">Events + Observability</a>
33+
<a href="../oci-containers/">OCI Containers</a>
34+
<a href="../snapshots/">Snapshots</a>
35+
<a href="../host-mounts/">Host Mounts</a>
36+
<a href="../security/">Security</a>
37+
<a href="../wire-protocol/">Wire Protocol</a>
38+
</nav>
39+
</aside>
40+
<div class="doc-content">
41+
1742
<section>
1843
<div class="kicker">Events + Observability</div>
1944
<h1>Run Event Model</h1>
20-
<p>VoidBox events are designed to keep capability and boundary context explicit for every action.</p>
21-
<div class="card"><h3>Identity fields</h3><p><code>run_id</code>, <code>box_name</code>, <code>skill_id</code>, <code>environment_id</code>, <code>mode</code>, <code>stream</code>, <code>seq</code>.</p></div>
45+
<p>Every pipeline run in VoidBox is fully instrumented. The event system provides structured identity fields on every action, OTLP-compatible traces and metrics, and structured logs -- all designed to keep capability and boundary context explicit.</p>
46+
</section>
47+
48+
<section>
49+
<h2>Identity Fields</h2>
50+
<article class="card">
51+
<h3>Every event carries these fields</h3>
52+
<p><code>run_id</code> -- unique identifier for the pipeline run.<br>
53+
<code>box_name</code> -- the VoidBox that emitted the event.<br>
54+
<code>skill_id</code> -- which skill is active.<br>
55+
<code>environment_id</code> -- the execution environment (VM) identifier.<br>
56+
<code>mode</code> -- execution mode (single, pipeline, workflow).<br>
57+
<code>stream</code> -- output stream (stdout, stderr).<br>
58+
<code>seq</code> -- monotonic sequence number for ordering.</p>
59+
</article>
2260
</section>
61+
2362
<section>
2463
<h2>Core Event Types</h2>
25-
<ul>
26-
<li><code>run.started</code>, <code>run.finished</code>, <code>run.failed</code>, <code>run.cancelled</code></li>
27-
<li><code>env.provisioned</code></li>
28-
<li><code>skill.mounted</code></li>
29-
<li><code>box.started</code>, <code>workflow.planned</code></li>
30-
<li><code>log.chunk</code>, <code>log.closed</code></li>
31-
</ul>
64+
<table>
65+
<thead>
66+
<tr><th>Event</th><th>Description</th></tr>
67+
</thead>
68+
<tbody>
69+
<tr><td><code>run.started</code></td><td>Pipeline run has begun execution.</td></tr>
70+
<tr><td><code>run.finished</code></td><td>Pipeline run completed successfully.</td></tr>
71+
<tr><td><code>run.failed</code></td><td>Pipeline run failed with an error.</td></tr>
72+
<tr><td><code>run.cancelled</code></td><td>Pipeline run was cancelled by the user.</td></tr>
73+
<tr><td><code>env.provisioned</code></td><td>Guest environment has been provisioned (skills, config, mounts).</td></tr>
74+
<tr><td><code>skill.mounted</code></td><td>A skill has been written to the guest filesystem.</td></tr>
75+
<tr><td><code>box.started</code></td><td>A VoidBox has started execution within a stage.</td></tr>
76+
<tr><td><code>workflow.planned</code></td><td>A workflow planner has generated a pipeline plan.</td></tr>
77+
<tr><td><code>log.chunk</code></td><td>A chunk of streaming output from the guest (stdout/stderr).</td></tr>
78+
<tr><td><code>log.closed</code></td><td>The output stream for a box has closed.</td></tr>
79+
</tbody>
80+
</table>
81+
</section>
82+
83+
<section>
84+
<h2>Trace Structure</h2>
85+
<p>VoidBox emits OpenTelemetry-compatible traces that capture the full execution hierarchy:</p>
86+
<pre><code>Pipeline span
87+
└─ Stage 1 span (box_name="data_analyst")
88+
├─ tool_call event: Read("input.json")
89+
├─ tool_call event: Bash("curl ...")
90+
└─ attributes: tokens_in, tokens_out, cost_usd, model
91+
└─ Stage 2 span (box_name="quant_analyst")
92+
└─ ...</code></pre>
93+
<p>Each stage span includes attributes for token counts, cost, model used, and individual tool call events. Fan-out stages create parallel child spans under the same pipeline parent.</p>
94+
<img src="../../assets/img/void-box-tracing-5.png" alt="VoidBox tracing visualization" style="max-width:100%;margin:1.5rem 0;" />
95+
</section>
96+
97+
<section>
98+
<h2>Instrumentation</h2>
99+
<div class="grid-2">
100+
<article class="card">
101+
<h3>OTLP Traces</h3>
102+
<p>Full distributed traces exported via OTLP gRPC. Pipeline, stage, and tool-call spans with rich attributes for token usage, cost, model, and timing.</p>
103+
</article>
104+
<article class="card">
105+
<h3>Metrics</h3>
106+
<p>Token counts (input/output), cost in USD, execution duration, and VM lifecycle timing. Exported as OTLP metrics alongside traces.</p>
107+
</article>
108+
<article class="card">
109+
<h3>Structured Logs</h3>
110+
<p>All log output is prefixed with <code>[vm:NAME]</code> for easy filtering. Stream-json output from claude-code is parsed into structured events.</p>
111+
</article>
112+
<article class="card">
113+
<h3>Guest Telemetry</h3>
114+
<p>The guest-agent reads <code>/proc/stat</code> and <code>/proc/meminfo</code> periodically, sending <code>TelemetryBatch</code> messages over vsock. The host-side <code>TelemetryAggregator</code> ingests these and exports as OTLP metrics.</p>
115+
</article>
116+
</div>
117+
</section>
118+
119+
<section>
120+
<h2>Configuration</h2>
121+
<table>
122+
<thead>
123+
<tr><th>Env var</th><th>Description</th></tr>
124+
</thead>
125+
<tbody>
126+
<tr><td><code>VOIDBOX_OTLP_ENDPOINT</code></td><td>OTLP gRPC endpoint (e.g. <code>http://localhost:4317</code>)</td></tr>
127+
<tr><td><code>OTEL_SERVICE_NAME</code></td><td>Service name for traces (default: <code>void-box</code>)</td></tr>
128+
</tbody>
129+
</table>
130+
<p>OpenTelemetry support is enabled at compile time:</p>
131+
<pre><code>cargo build --features opentelemetry</code></pre>
132+
<p>For a full OTLP setup walkthrough with Jaeger or Grafana, see the <a href="../../guides/observability-setup/">Observability Setup guide</a>.</p>
32133
</section>
134+
135+
<section>
136+
<h2>Guest Telemetry Pipeline</h2>
137+
<p>The guest-side telemetry pipeline works independently from the host tracing system:</p>
138+
<ol>
139+
<li>The guest-agent periodically reads <code>/proc/stat</code> (CPU usage) and <code>/proc/meminfo</code> (memory usage).</li>
140+
<li>Readings are batched into a <code>TelemetryBatch</code> message and sent to the host over the vsock channel.</li>
141+
<li>The host-side <code>TelemetryAggregator</code> receives batches, computes deltas, and exports them as OTLP metrics.</li>
142+
</ol>
143+
<p>This gives visibility into guest resource consumption without any instrumentation inside the workload itself.</p>
144+
</section>
145+
33146
<section>
34147
<h2>Persistence Providers</h2>
35-
<p>Daemon run/session state uses a provider abstraction: <code>disk</code> (default), plus example adapters for <code>sqlite</code> and <code>valkey</code>.</p>
148+
<p>Daemon run and session state uses a provider abstraction, allowing different storage backends:</p>
149+
<div class="grid-2">
150+
<article class="card">
151+
<h3>Disk (default)</h3>
152+
<p>File-based persistence. Run state and events are stored as JSON files on the local filesystem. No external dependencies.</p>
153+
</article>
154+
<article class="card">
155+
<h3>SQLite / Valkey</h3>
156+
<p>Adapter implementations for <code>sqlite</code> and <code>valkey</code> (Redis-compatible) backends. Useful for shared state in multi-node deployments.</p>
157+
</article>
158+
</div>
36159
</section>
160+
161+
</div>
162+
</div>
37163
</main>
38164
<footer><div class="wrap"><a href="../">← Docs</a></div></footer>
39165
<script src="../../assets/js/site.js"></script>

0 commit comments

Comments
 (0)