Background reading: Sandboxing and Allocation.
Date: October 27, 2026
Status: Draft for implementation planning
Scope: Sandbox installation, delegated management, observability, orchestrator qualification, and public access dashboards. Implementation proposals and unresolved architecture decisions appear below.
Build workload isolation, observability, and delegated capacity management for independently operated Livepeer machines. An operator should be able to install a sandbox, connect the machine to the observability platform, and check that the machine can run supported applications. The observability platform, acting as the allocator, should be able to deploy, test, operate, and diagnose workloads centrally.
The delivery priorities are:
Orchestrator qualification starts with hardware compatibility checks during sandbox setup, followed by recurring benchmarks and app probes that support comparisons across operators and help distinguish infrastructure problems from application failures. Qualification does not depend on implementing per-job tracking.
| Area | Working direction |
|---|---|
| Machine topology | Plan around one local k3s cluster per machine. Independently owned machines remain separate management and trust domains. |
| Runtime | Install gVisor as the workload sandbox runtime. Test the actual hardware and application combinations. |
| Sandbox implementation | Focus sandbox integration and management work on the Go runner. |
| Gateway integration | Use the Python SDK on the gateway/client side to discover and call applications. |
| Observability backend | Prefer Go for custom backend services and APIs. Reuse standalone infrastructure components such as Alloy and Loki. |
| Observability frontend | Use TypeScript and React, with Vite as the preferred build tool. Avoid Vercel. |
| Allocator authority | Expect substantial operational control. Precisely define its limits, especially access outside Kubernetes. |
| Management transport | Compare direct Kubernetes API access with a local agent that pulls desired state. Neither is selected yet. |
| Orchestrator ownership | The allocator should probably manage the orchestrator, whether it runs in k3s or as a host service. Placement remains open. |
| Telemetry visibility | The allocator should have comprehensive operational visibility. Operator access needs a decision; app owners should eventually see their own logs, at lower initial priority. |
| Orchestrator qualification | Qualify machines with repeatable benchmarks and application probes, and detect operational regressions. |
| Public access dashboards | Publish read-only summaries of network health, capacity, performance, and qualification results, with explicit freshness and coverage. |
| Operator secrets | Some configuration, such as redemption wallet secrets, should remain outside allocator access. Resolve how this can coexist with broad management authority. |
| Connectivity | Evaluate a tunnel installed alongside k3s for management and potentially public job access, with managed DNS, certificates, and ingress. |
| Reference | Relevance and current understanding |
|---|---|
| Livepeer Node | Orchestrator implementation and the main starting point for metrics work. Review and expand its existing metrics, and inventory its endpoints, logs, and access controls. |
| Python SDK | Gateway/client-side integration for discovering and calling Live Runner applications. |
| Go runner | Foundation for sandbox integration. Add runner instrumentation where needed to complement orchestrator telemetry. |
| naap-ops milestone 2 | Rough backlog that needs review and reconciliation with this plan. |
Metrics baseline: the Livepeer Node orchestrator already exposes some metrics that need review and expansion. Start there, then identify any additional host, application, or Go runner instrumentation needed. Inventory existing log formats, collection paths, and job-event coverage during discovery.
Start with a targeted walkthrough of orchestrators, gateways, the Go runner, and the end-to-end request path. Cover the Python SDK's gateway-side role and the payment/redemption boundaries. Use a representative example application to establish shared understanding and identify architectural gaps. Familiarity with every module is not a prerequisite.