hiloop run, and hiloop records what crosses the
process and network boundaries, tagging every event with
run identity.
Wrap a command
Everything after-- is the command to run:
hiloop runs list, marked running
while the command executes and succeeded or failed from its exit code when it finishes.
--label names the run in that listing; without it a name is assigned.
Because the run’s lifecycle belongs to the wrapped command, a run whose process vanished without
reporting stays running — the platform never invents an ending it didn’t observe. Instead, run
reads derive a liveness signal: each run carries last_activity_at (its most recent telemetry
event, falling back to its start) and a stale flag once it has been quiet past a 15-minute
window, which runs list renders as running (stale). Staleness is
derived at read time — never stored, and never a terminal state: the run flips back on new
telemetry, and if the liveness source can’t be reached the fields are simply absent (an unknown
run is never rendered stale).
hiloop run is transparent: the child’s stdout, stderr, and exit code pass straight through, so it’s
safe to drop into a script. When the run registers, its run id is announced on stderr
(hiloop: recorded run …, with the hiloop runs show command to view it) so you can query the
capture later — stdout stays clean for pipelines. If the control plane cannot be reached when the run starts, the
command still executes and telemetry still ships, but the run won’t appear in hiloop runs list —
a warning on stderr tells you when that happens.
Use it in CI
Wrap the command you already run and keep the original exit behavior:hiloop run exits with the same code. The stderr announcement
includes the run id for follow-up query steps.
Inside a sandbox
Every sandbox has one ambient run and a platform-managed capture session. Create reports that run id; the workload receives no Hiloop API key and needs no harness-specific configuration:sandbox exec receive process, exit, stdout, and
stderr capture as distinct executions. A non-interactive SSH command gets the same capture; a PTY
session records its start, end, and terminal output, but deliberately not keystrokes/input. The
sandbox also exposes a shared OTLP/HTTP receiver and sets standard OpenTelemetry exporter variables
for software that already emits spans or logs.
HTTP capture uses a sandbox-scoped cooperative proxy. Common clients honor the injected proxy and
CA-bundle variables with no agent configuration, but a client that ignores them or opens raw
sockets can bypass capture. An image’s implicit default entrypoint receives proxy and OTLP capture,
but Kubernetes cannot prepend a supervisor while preserving an unknown image command; pass an
explicit create command when you need entrypoint process and stdio capture.
If the hiloop CLI happens to run inside a sandbox, hiloop run -- <command> joins this same ambient
run. It does not register a child run or start another proxy, and it does not need a Hiloop
credential. Run-selecting flags and per-command egress policy are refused because those belong to
the ambient sandbox boundary.
Model access
Sandbox model traffic must use the proof-bound model gateway. Do not copy a raw provider API key or platform-managed credential into the sandbox through SSH, exec, environment variables, an image, or the workspace. A compatible provider subscription may keep its own login state in the tool, but its traffic is supported only through the proof-bound provider-native gateway route, never by direct provider egress. The hosted service supports proof-bound bearer secrets for exact public HTTPS destinations. That generic delivery path does not replace the provider-native model gateway, so supported model access remains unavailable until the gateway route is active. See managing secrets for the destination-bound contract.What gets captured
Three capture paths run in parallel, all on by default:
Each event is stamped with the run’s
run_id and its lineage_path before it’s
streamed to the telemetry gateway. Large bodies (full prompts, completions, HTTP responses) are
stored by content-addressed reference, not inline — see the event model.
How network capture stays scoped
On supported Linux hosts, the default--net-capture=auto mode places the wrapped process in a
private network namespace after a preflight succeeds. It does not set proxy variables in the child.
On macOS or an incompatible Linux host, an observation-only run warns once and uses a cooperative
proxy instead. Both active modes scope their per-run certificate authority to the wrapped process;
they never modify your machine’s system trust store.
Use --net-capture=proxy to request the cooperative proxy explicitly, or
--net-capture=off when you only want spans and stdio. Restrictive egress policies require
transparent netns capture and fail before the child starts if it is unavailable.
Configuration
hiloop run reads these (flags override environment):
For a local or self-hosted gateway speaking cleartext h2c, add
--insecure. See
Configure CLI contexts and the
CLI reference for every flag.