Add a Web UI for the AgentENV control plane

[LSX-s-Software]

Summary

Add a standalone Web UI for the AENV control plane so operators and developers can inspect cluster state and manage sandboxes, snapshots, and templates without calling the HTTP API or CLI directly.

The first version should be a control-plane management console built on top of the existing Gateway and AENV HTTP APIs. Interactive terminals, file management, and other sandbox data-plane features can be considered separately.

Motivation

AENV already exposes most lifecycle and observability capabilities through its E2B-compatible HTTP API and distributed Gateway, but using them currently requires API knowledge or command-line tooling. A Web UI would:

• Make AENV easier to evaluate and operate.
• Provide a single view of nodes, resources, sandboxes, snapshots, and templates.
• Reduce the risk of malformed lifecycle requests and destructive commands.
• Make long-running operations and failures easier to understand.
• Improve the experience of operating multi-node deployments through the Gateway.

Proposed scope

1. Control-plane connection and authentication

• Configure the AENV Gateway endpoint.
• Accept an X-API-Key for sandbox, snapshot, and template APIs.
• Accept an optional X-Admin-Token for node APIs.
• Validate connectivity and display whether the Gateway and credentials are usable.
• Keep credentials only for the current browser session and clear them on logout/session close.
• Never include complete credentials in UI logs or error messages.
• If no admin token is configured, keep the regular resource pages usable and show the node pages as unavailable due to missing permissions.

2. Cluster dashboard

Provide an overview page showing, where permitted:

• Gateway health and connection status.
• Total nodes and counts by ready, draining, connecting, and unhealthy state.
• Running, paused, and starting sandbox counts.
• Aggregate CPU and memory capacity, host usage, and sandbox allocations.
• Sandbox create success/failure counters.
• Template and snapshot counts.
• Recently created and soon-to-expire sandboxes.
• Unhealthy nodes and failed template builds.
• Manual refresh and optional periodic refresh.

When the admin token is absent, node and cluster-resource panels should show a permission notice without breaking the rest of the dashboard.

3. Node views

Node list

• Show node ID, cluster ID, status, version, and commit.
• Show running, paused, and starting sandbox counts.
• Show CPU usage/allocation and memory usage/allocation.
• Filter by cluster, node status, and node ID.
• Visually highlight unhealthy or resource-constrained nodes.

Node detail

• Show service instance ID, architecture, CPU information, version, and commit.
• Show CPU, memory, and per-mount disk metrics.
• Distinguish active sandbox allocations from paused sandbox reservations.
• Show sandbox create successes/failures and cached builds.

The first version should expose the read-only capabilities of the current node API. Node drain, delete, or scheduling configuration is out of scope unless separate control-plane APIs are added.

4. Sandbox management

Sandbox list

• Use the cluster-level v2 sandbox list through the Gateway.
• Include both running and paused sandboxes.
• Show sandbox ID, source template/snapshot, state, CPU, memory, disk, start time, and expiration time.
• Filter by state, sandbox ID, template ID, and metadata.
• Support pagination and refresh.
• Highlight sandboxes that will expire soon.
• Allow copying sandbox IDs and related connection information.
• Provide state-aware quick actions.

Create sandbox

Support both existing creation paths.

From a template or snapshot:

• Select or enter a template/snapshot ID or alias.
• Configure timeout and timeout behavior (pause or kill).
• Configure auto-resume.
• Configure environment variables, metadata, network policy, and custom extension parameters.

Cold start from an OCI image:

• Enter an OCI image reference.
• Configure CPU, memory, and disk size.
• Configure attached drives, including image, read-only mode, mount path, subpath, and disk size.
• Configure environment variables, metadata, network policy, custom extension parameters, and supported advanced boot arguments.
• Clearly indicate that a cache miss can make cold creation take significantly longer.

The form should provide basic and advanced sections, validate required fields and documented ranges, and show a request summary before submission.

Sandbox detail

• Show identity, state, source template/snapshot, resources, lifecycle policy, and expiration time.
• Show envd version, metadata, and network configuration.
• Show proxy domain and connection tokens where returned, with sensitive values hidden by default.
• Show only actions valid for the current state.
• Refresh the detail after an operation so stale state is not presented as authoritative.

Lifecycle operations

• Pause a running sandbox.
• Resume a paused sandbox with a new timeout.
• Connect to a sandbox, resuming it when paused or extending its TTL when already running.
• Set or refresh the timeout.
• Kill/delete a sandbox.
• Fork a running sandbox, supporting the API range of 1–16 children and displaying each resulting sandbox.
• Capture a persistent snapshot from a running sandbox, with an optional name.
• Replace the network egress policy of a running sandbox.
• Read and patch custom extension parameters.

Destructive or high-impact actions such as kill, multi-fork, template deletion, and network-policy replacement should require confirmation. Duplicate submissions should be disabled while an operation is in progress.

5. Snapshot management

Snapshot list

• Show snapshot ID, names/aliases, CPU, memory, disk size, creation time, and update time.
• Filter by source sandbox ID.
• Support pagination, refresh, and copying snapshot IDs.
• Provide an action to create a new sandbox from a snapshot.

Snapshot detail

• Show snapshot identity, aliases, resource specification, and timestamps.
• Show source-sandbox provenance when available from the API.
• Provide a direct entry point into the create-sandbox flow.

Snapshot deletion is not part of the initial UI because the current public control-plane API does not expose a snapshot delete operation.

6. Template and build management

Template list

• Show template ID, names/aliases, resource specification, build status, build count, and spawn count.
• Show creation, update, and last-spawned times.
• Filter by name, alias, template ID, and build status.
• Provide an action to create a sandbox from a template.
• Clearly distinguish building, waiting, ready, and error states.

Create and build templates

Provide a guided flow to:

• Set the template name, tags, CPU, and memory.
• Select a base OCI image or existing template.
• Add and order supported build steps such as RUN, ENV, and WORKDIR.
• Configure start and readiness commands.
• Request a forced build when needed.
• Review the complete build request before submission.

Template detail

• Show template metadata, names/aliases, usage statistics, and build history.
• Show each build's state, resource specification, and timestamps.
• Refresh active build status automatically.
• Show structured log entries, plain logs, failure reasons, and the failed step.
• Support rebuilding and deleting a template.
• Support resolving and navigating to a template by alias.

7. General UX and reliability

• Top-level navigation for Dashboard, Nodes, Sandboxes, Snapshots, Templates, and Connection Settings.
• Preserve list filters and pagination while navigating between list and detail pages.
• Provide loading, success, failure, and retry states for every asynchronous operation.
• Present useful messages for 401, 403, 404, 409, and 5xx responses.
• Do not report a network failure as a successful operation.
• Handle long-running create/build operations without incorrectly treating an ordinary client timeout as definitive failure.
• Display timestamps in local time with access to the original value.
• Use consistent units for CPU, memory, and disk values.
• Support desktop and basic tablet layouts.
• Include basic keyboard navigation, focus indication, accessible labels, and sufficient color contrast.

Deployment expectations

• Package the UI as an independently deployable Web service.
• Add it to the repository's Docker Compose and Kubernetes deployment options.
• Use the Gateway as the single control-plane entry point; the UI should not call Scheduler gRPC APIs directly.
• Keep the baseline UI compatible with the existing public HTTP API rather than introducing UI-only resource semantics.
• Document how to start the UI and access it in local, Compose, and Kubernetes deployments.

Non-goals for the initial version

• Browser terminal or interactive shell.
• Sandbox file browser/editor.
• Direct process execution inside a sandbox.
• Node drain/delete controls.
• Scheduler strategy or resource-limit editing.
• Multi-user login, RBAC, or tenant administration.
• Audit-log storage.

These can be separate follow-up features, especially because terminal and file access belong to the sandbox data plane rather than the control-plane management surface.

Acceptance criteria

• A user can connect the UI to an AENV Gateway and verify authentication state.
• A user with an admin token can inspect cluster and node resource state.
• A user can list, create, inspect, pause, resume, connect, fork, update TTL/network settings, snapshot, and delete sandboxes.
• A user can create a sandbox from a template, snapshot, or external OCI image.
• A user can list and inspect snapshots and start a sandbox from one.
• A user can create templates, start builds, inspect build status/logs, and delete templates.
• Missing admin credentials restrict only admin/node functionality.
• Credentials are cleared when the browser session ends or the user logs out.
• Dangerous actions require confirmation and failed operations are never shown as successful.
• Docker Compose and Kubernetes documentation includes the Web UI service and access path.

Future API opportunities

The UI can initially use the existing API, but the following capabilities may justify separate control-plane issues:

• Snapshot deletion.
• Node drain and maintenance state changes.
• Server-side authenticated sessions and RBAC.
• Audit events and lifecycle history.
• A node-to-sandbox ownership view exposed directly by the admin API.
• Streaming operation/build events instead of polling.

[immanuel-peter]

I can work on this 🙋‍♂️

[immanuel-peter]

Status update (Web UI stack)

Implementation is up as a 4-PR stack against main:

1. [1/4] feat(web): scaffold control-plane console and deploy wiring #76 — scaffold + Compose/K8s deploy + docs
2. [2/4] feat(web): Gateway connection settings and session cookies #77 — Gateway connection / session cookies
3. [3/4] feat(web): sandbox and snapshot management views #78 — sandboxes + snapshots
4. [4/4] feat(web): templates, dashboard, and node views #79 — templates + dashboard + nodes

Done

• Connection: Gateway URL, X-API-Key, optional X-Admin-Token, connectivity probe, httpOnly session cookies, logout clear, masked secrets in UI
• Dashboard: connection/health, node status counts, capacity, create OK/fail, template/snapshot counts, recent/expiring sandboxes, unhealthy nodes / failed builds, manual + periodic refresh; admin-absent panels degrade without breaking the page
• Nodes: list + detail (read-only), filters, pressure highlighting, cached builds when present
• Sandboxes: v2 list, create from template/snapshot/OCI (basic/advanced + request summary), detail, pause/resume, timeout, kill, fork (1–16), snapshot capture, network policy replace, custom-extension params read/patch, confirms on destructive actions
• Snapshots: list/detail, filter by source sandbox, create-sandbox entry points
• Templates: list/detail, guided build (RUN/ENV/WORKDIR + review), logs/status polling, rebuild, delete, create-sandbox from template
• Deploy/docs: standalone web/ service, Compose + Kubernetes, Gateway-only, getting-started + deploy docs

Not done / partial

• Connect for running sandboxes: paused resume uses /connect; running sandboxes have Set timeout but no Connect action to extend TTL via /connect
• Fork results: fork works, but children are mostly toasted as counts — not listed/linked in the UI
• Sandbox list pagination: nextToken is fetched but Next/Prev isn’t wired (snapshots pagination is)
• List ↔ detail filter preservation: back links drop query/filter state
• Long-running timeout UX: create/build use longer client timeouts, but a client timeout is still treated as a hard failure rather than “may still be running”

[immanuel-peter]

As per #76, I will make a separate repo to hold the web UI for AgentENV to be managed independently of the main repo.