vinzenz/hyperhive
vinzenz/hyperhive
Watch
0
0
Fork
You've already forked hyperhive
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

hivectl: add agent <name> watch to follow live events from the CLI

Browse source
This commit is contained in:
damocles 2026-07-27 20:16:26 +02:00 • committed by mara
commit 9d5c7a7f7e
13 changed files with 230 additions and 16 deletions
Download patch file Download diff file Expand all files Collapse all files

10
docs/gateway.md
View file

@ -249,9 +249,13 @@ gateway always terminates TLS, so discovery responses always advertise https.
`hive-c0re.nix` opens the per-agent web-port range
`8100..8999` in the host firewall **only when
`services.hyperhive.gateway.enable = false`**. With the gateway on
(default), it's the sole external entry point and proxies to
`127.0.0.1:<port>` internally — leaving the per-agent ports
firewall-open would defeat the single-front-door story.
(default) it's the sole external entry point and routes to agents over
the UDS upstream described above (see [Per-agent unix-socket
upstream](#per-agent-unix-socket-upstream)) — leaving the per-agent
ports firewall-open would defeat the single-front-door story. The
hashed TCP port (`lifecycle::agent_web_port`) still exists as a direct
host-loopback fallback for the pre-UDS/gateway-disabled case, but isn't
what the gateway itself proxies through.
`services.hyperhive.gateway.openFirewall = true` opens both `port` and
`httpsPort` — the gateway always terminates TLS (self-signed floor), so

12
docs/tools/hivectl-cli.md
View file

@ -32,6 +32,7 @@ This document contains the help content for the `hivectl` command-line program.
* [`hivectl agent set-parent`↴](#hivectl-agent-set-parent)
* [`hivectl agent set-limits`↴](#hivectl-agent-set-limits)
* [`hivectl agent choom`↴](#hivectl-agent-choom)
* [`hivectl agent watch`↴](#hivectl-agent-watch)
* [`hivectl agent quota`↴](#hivectl-agent-quota)
* [`hivectl agent quota show`↴](#hivectl-agent-quota-show)
* [`hivectl agent quota set`↴](#hivectl-agent-quota-set)
@ -348,6 +349,7 @@ Everything here targets a single named agent (`hivectl agent foo restart`, `hive
* `set-parent` — Move this agent in the topology tree — under a new parent, or to root
* `set-limits` — Declare this agent's CPU/memory limits, overriding the hive-wide defaults
* `choom` — Open an interactive Claude session inside this agent's container
* `watch` — Follow this agent's live turn/tool-call event stream from the CLI
* `quota` — This agent's disk accounting + optional quota via btrfs qgroups
* `subvol` — btrfs subvolume management for this agent's state dir
@ -476,6 +478,16 @@ A fresh session by default, or resume a prior one. Requires root and a running c
## `hivectl agent watch`
Follow this agent's live turn/tool-call event stream from the CLI.
Dials the same unix socket the gateway's nginx already proxies through (no gateway hop, no daemon round-trip for the stream itself) and prints one compact line per event. `Ctrl-C` to stop. Requires the agent to be running (its harness must have bound the web UI socket).
**Usage:** `hivectl agent watch`
## `hivectl agent quota`
This agent's disk accounting + optional quota via btrfs qgroups.

26
docs/tools/hivectl.md
View file

@ -266,6 +266,32 @@ lands in a faithful copy of the agent's environment:
instead of the onboarding/trust dialog the headless harness never
completes. It's the single place hyperhive touches that file.
## Watch
Follow an agent's live turn/tool-call event stream from the CLI:
```bash
hivectl agent iris watch # tail iris's live events; Ctrl-C to stop
```
Dials the same unix socket the gateway's nginx `proxy_pass`es through
(`/run/hive-agent/<name>/web.sock` — see [Per-agent unix-socket
upstream](../gateway.md#per-agent-unix-socket-upstream)) directly and
speaks a bare HTTP/1.1 request for the agent's existing `/events/stream`
SSE endpoint over it. No gateway hop, no daemon round-trip for the
stream itself — the daemon socket is only used for the "does this agent
exist" pre-flight, same reasoning as `choom` above. Requires the agent
to be running with its web UI socket bound; a fresh spawn/rebuild that
hasn't come up yet gets a clear connection-refused hint rather than a
raw OS error.
Prints one compact line per event — reuses the `_icon`/`_summary` fields
the harness already stamps onto stream-json events for the web UI
(`stream_enrich.rs`), so tool calls and turn markers read as short
glyph-prefixed lines instead of raw JSON. Not an attempt at the web
UI's full collapsible-details rendering (`docs/terminal-rendering.md`)
— that's presentation for a browser, this is a `tail -f`.
## Open
Print (and best-effort open in a browser) one of the hive's web surfaces.