Console

The console is a web UI for people: tenants reserve GPUs, create instances and open terminals; platform operators watch nodes, rollouts and fleet drift. It comes in two layers you can use separately:

• apps/console, a Next.js 15 app that runs Better IAM and Better Compute in one process, on one origin. It is private to the repository (not published) and serves as the reference deployment.
• @better-compute/console-kit, the framework-free view models the console's pages are built on: resource stores, the live event stream, permission-aware actions, forms, charts and a terminal. Use it to build your own UI in React, Solid, Vue or anything else.

One origin, one sign-in

Better IAM is mounted at /api/iam and Better Compute at /api/compute on the same origin, so the host-only IAM session cookie authenticates both. Compute is built with acceptIamCookie: true: it accepts the cookie only on POSTs that carry X-Better-Compute: 1 and an Origin equal to the console's own. The compute IAM bridge installs compute's action catalog in Better IAM and serves compute's decisions from its projection, as in any embedded deployment.

server.mjs runs Next.js plus the one thing a route handler cannot do: the WebSocket upgrade of /api/compute/tunnels/{ticket} for browser terminals and node consoles, served by handleTunnel and relayed over mTLS to the gateway that holds the node's session. Tunnels open only from the console's own origin, and a signed-in browser can only use its own person's tickets.

Run it

cd apps/console
node server.mjs --dev      # or: pnpm dev

--dev sets CONSOLE_DEV=1, the only mode in which the console generates secrets for itself: the session secret, the exec ticket key, the break-glass and sandbox SSH CA keys (under .console-data/) and, on the first start, the root administrator's password, printed once. It also allows gateways without TLS. Open http://localhost:3100/login and sign in as admin@console.local. Members of an organization sign in at /login?org=<slug>.

For production, build and start without --dev; every secret then comes from the environment:

cd apps/console
pnpm build                   # next build
CONSOLE_ORIGIN=https://console.example.com CONSOLE_SECRET=… CONSOLE_ADMIN_PASSWORD=… \
BETTER_COMPUTE_DATABASE_URL=postgres://… CONSOLE_IAM_DATABASE_URL=postgres://… \
node server.mjs --prod       # or: pnpm start

Run it from apps/console: the stack file and the data directory are resolved against the working directory.

Every replica and gateway must share the exec ticket key, and nodes pin its public key and the SSH CA's, so production supplies the key files rather than generating them. The sandbox SSH CA is a separate key, so a sandbox certificate never opens a node and a break-glass one never opens a sandbox; the console passes its public key to vps({ sandboxExec }) so every sandbox guest trusts it, and certifies each guest's host key with it (certifyHostKey), so sandbox exec against the console pins guests instead of trusting them on first use. Every replica must share it too. The stack is built once per process from console.config.mjs (loaded at run time, never bundled): Better IAM, then compute with the vps, fleet and events (webhooks) modules and retentionModule() (the console builds betterCompute() itself, so the CLI's automatic retention does not apply), audit when an audit key is available, and rollout when release pins are set.

Before the workers start, the stack calls installIamHandlers(compute, { bridge, streams: [watches] }), as serve does for host.iam: a revoked delegation or suspended agent closes its tunnels on every gateway (over the console's gateway mTLS) and its /api/compute/watch streams in this process, and revocations drop the IAM caches. See tunnels.

Screens

Every page needs a session; without one the layout redirects to /login. Pages render in the browser over console-kit, for the tenant the session acts in. Platform pages appear only for the root tenant.

A "live" badge in the navigation shows the event stream's state. While the stream is down, the stores a page has loaded refresh every 20 seconds instead, and only while the tab is visible.

Buttons follow two checks. A button is enabled only when the item's state allows the action (a released reservation offers nothing) and Better IAM would allow it for the signed-in person. The second check is advisory: a server action batches up to 50 checks through Better IAM's can, and the compute API still decides the real call. A delegated call held back for approval shows "awaiting approval" with the confirmation id.

Actions that destroy or release something ask first, naming what happens: draining a node, stopping or deleting an instance, releasing or cancelling a reservation (d40af29, 0919f86), a bare-metal node's undeploy, retire, abort and provide (0cd1d79), and binding a machine's PXE MAC, after which it boots from that MAC (15c11ee).

Sandboxes

The Sandboxes page (createSandboxesView in console-kit) works on sandboxes of the session's tenant. With no template, the create form says an administrator creates them. Create sends sandboxes.create with a fresh console-… idempotency key and waits up to 20 seconds for the sandbox to leave starting. The list shows the person's own sandboxes, or, with Everyone's sandboxes, the tenant's (scope: 'all'), each with its template name, warm and the snapshot it was restored from. A memory restore whose identityRebound is false (console-kit's SandboxRow carries it) shows a warning that it still answers to its source's SSH identity, so exec waits until the source and sibling restores are gone or the host gives it its own (9958865). The countdown ticks every second from expiresAt and reads expired at zero.

Its buttons are not gated by IAM checks in advance: the call is decided and an error is shown in place. +30 min is sandboxes.extend with by of 30 minutes, Snapshot takes a memory snapshot that goes with the sandbox, and Delete asks for confirmation first. A shell is not opened in the browser: the page shows the better-compute sandbox exec sbx_… command, which runs OpenSSH through a tunnel. The console's own stack configures the sandbox SSH CA but no snapshot store, so Snapshot answers INVALID_CONFIG there until you give vps({ snapshots }) a store in console.config.mjs. On that answer the page says snapshots are not configured on this deployment and hides the button for the rest of the session.

A Templates section serves tenant administrators (compute:sandboxes:manage; the calls are decided, not the section hidden). It lists the tenant's templates with pool, flavor, image, lifetime and warm pool, with Warm +1, Warm −1 (sandboxTemplates.update of warm) and delete, and a form that creates one from a name, pool, flavor, image, warm minimum and longest lifetime in hours. console-kit's SandboxesView exposes the same as createTemplate, updateTemplate and deleteTemplate. Templates can also come from better-compute sandbox-template create or a FleetConfig document.

Since dd5555b the templates table also shows each template's volumes (volume name, mount path, (read-only)), each with Detach, and an Attach a volume form picks a template, a ready volume of that template's pool, a mount path (default /data; it must start with /) and Read-only. Every sandbox from the template then mounts the volume and runs on the volume's host. Both send the template's whole volume list through sandboxTemplates.update. Warm +1 is disabled for a template with volumes, since the server keeps no warm pool beside volumes. The volume picker lists everyone's volumes (sandboxVolumes.list with scope: 'all'); without the right to list them it is empty.

Volumes

The Volumes page (50add82) works on the session tenant's sandbox volumes, an agent's persistent memory, through the API directly (sandboxVolumes.*; there is no console-kit view for it). The create form takes a pool from the tenant's pools, a name (lowercase letters, digits, ., _ and -, at most 63, checked before the button enables) and a size from 1 to 16,384 GiB, and sends sandboxVolumes.create with a fresh console-… idempotency key. The list shows the person's own volumes (scope: 'mine'), or, with Everyone's volumes, the tenant's (scope: 'all', e68aba7), each with its id and /dev/disk/by-id/virtio-<serial> path, pool and host ("not placed yet" without one), size and state. For a ready volume, Grow asks for the new size and calls sandboxVolumes.resize only with a larger one, and Delete asks for confirmation, warning that the data is wiped, before sandboxVolumes.delete. As on the Sandboxes page, the buttons are not gated by IAM checks in advance; the call is decided and an error is shown in place. A volume is attached to a template on the Sandboxes page's Templates section (dd5555b, above), or with better-compute sandbox-template update --volumes, the API or FleetConfig.

PXE discovery

The PXE discovery page (/discovery, 15c11ee) is the console's side of discovering new machines: a machine whose BMC cannot name its NICs (IPMI), enrolled with only its product UUID, waits in metal.ensureRamdisk until an operator confirms its PXE MAC. The page is built on console-kit's createPxeDiscoveryView.

A site picker lists the session tenant's sites (sites/list, the first one selected), and the table shows what that site's agents saw PXE-booting from MACs with no boot entry in the last 24 hours (metal.discovered; only the tenant that owns the site sees it). Refresh reloads it. pxeCandidates orders the rows by what needs a decision first: candidates, then unknown machines, then enrolled ones, newest first within each.

Nothing on the page binds a MAC by itself, since discovery data is unauthenticated DHCP. A candidate row (the MAC metal saw under the machine's UUID right after power-cycling it) has a Confirm button. It first asks, in a browser confirmation, "Bind <mac> as the PXE MAC of <node>? The machine will then boot from it.", and only then calls metal.confirmMac and reloads the list. Unknown and enrolled rows have no button: an unknown machine is never answered or enrolled from here.

Bind a MAC by hand serves a machine enrolled without MACs whose PXE MAC you know from its label or its BMC. It takes a node id (it must start with node_) and a MAC; normalizeMac accepts upper or lower case and - or : as the separator, and the button stays disabled until both are well formed. It goes through the same browser confirmation and metal.confirmMac call. As with the CLI's metal confirm-mac, the call is decided as compute:nodes:provision on the node and audited as node.pxe-mac.confirmed; the buttons are not gated by IAM checks in advance, so a refusal (for example CONFLICT for a MAC another machine of the site has, or INVALID_STATE for a node that already has MACs) is shown in place.

Destructive batches

The Batches page (createBatchesView in console-kit, b24d043) shows the tenant's destructive batches: fleet-wide reimages, wipes and power actions held until enough approvers sign their scope. It lists pending batches by default, with a filter for approved, expired, cancelled or all, and counts down each pending batch's window from notAfter. Each row shows its reason and who created it; a batch an agent proposed shows a warning line instead, "Proposed by agent X for Y (delegation D): the reason is the agent's own text" (bd80209, from createdByAgent and delegationId).

Details loads the batch (commandBatches.get) and its whole scope (commandBatches.scope, paged 5,000 at a time and capped at 20,000 entries, with a warning when cut short), grouped by command kind. Subjects read as a person would: a node id, BMC 10.0.0.7 (via node_site) for a BMC reached through a site agent, or HTTP to node_…. The panel also shows the scope root, the approvals so far (key id, approver and time) and the member commands by state. Cancel asks for confirmation and calls commandBatches.cancel, so none of the batch's commands run.

The page cannot approve. A browser never holds an approver key, so for a pending batch it shows the command for the approver's terminal, better-compute batch approve --batch <id> --key <approver key>, where the CLI lists the scope, recomputes the root from it and signs. Reading needs compute:batches:read and cancelling compute:batches:approve, both decided when called.

Break-glass SSH

A node's page carries the Break-glass SSH panel for SSH certificates, for platform administrators. It takes your public key (a pasted private key, several lines or an unsupported key type is refused before anything is sent), the account (default root) and a lifetime of 5, 15, 30 or 60 minutes, and issues a certificate with nodes.issueSshCert; the certificate is shown once, with a copy button and the commands to save it as <key>-cert.pub and connect. A session without MFA is told to sign in again with a second factor.

Below it, Who holds access lists the node's certificates from nodes.listSshCerts: holder, principal, issue and expiry times, and state (active, expired or revoked, with the revocation reason), with Include expired to show those too. Each active certificate has a Revoke button, which asks for confirmation and calls nodes.revokeSshCert with the reason revoked from the console.

console-kit

@better-compute/console-kit depends only on the typed client and core. Every store has subscribe(listener) and get(), the contract of React's useSyncExternalStore, so a framework adapter is a few lines.

import { createComputeClient } from '@better-compute/client';
import { createPermissions, describeAction, startLiveConsole } from '@better-compute/console-kit';

const client = createComputeClient({ baseURL, token: () => session.token });

const live = await startLiveConsole(client, {
  tenantId,
  watchUrl: `${baseURL}/watch`, // wherever your host mounts handleWatch
  headers: () => ({ authorization: `Bearer ${session.token}` }),
  permissions: createPermissions({ authorize: (checks) => iamAuthorizeMany(checks) }),
});

live.reservations.subscribe(() => render(live.reservations.get()));
live.connection.subscribe(() => showBadge(live.connection.get().status));

Live updates

watchEvents({ url, types?, lastEventId?, headers?, onEvent, onStatus? }) reads the stream with fetch rather than EventSource, so it can send an Authorization header (or, in the console, X-Better-Compute: 1). It remembers the id: of the last event and sends it as Last-Event-ID when it reconnects, so it resumes exactly after that event. It reconnects after the server's retry: delay (2 s by default) when the server closes the stream, and with doubling backoff, capped at maxBackoffMs (60 s by default), after a failure. onStatus reports connecting, open, retrying and stopped.

applyEvent routes each event by its subject: reservation/…, node/… and instance/… re-read that one item (and drop it on NOT_FOUND or ACCESS_DENIED), and pool/… refreshes the pools. Reservation, pool and node events (except node.status) also refresh the capacity summary, debounced by 250 ms. startLiveConsole does all of this in one call and clears cached permission answers after events whose type starts with iam., binding., delegation., agent. or project.members. See watch for the server side.

Permission-aware actions

const release = describeAction('reservations', 'release', reservation.id);
// { path: 'reservations/release', action: 'compute:reservations:release',
//   resource: { type: 'compute-reservation', id: 'rsv_…' }, kind: 'mutation' }
const allowed = await permissions.can(release);

describeAction throws for a method outside the API table, and actionsFor(kind, id) lists every mutation on a resource kind, optionally limited to the phases and modules your deployment runs. createPermissions takes your authorize(checks), usually Better IAM's authorizeMany for the caller's tenant behind a server endpoint. A failed batch rejects its checks and leaves them unanswered; it never answers "denied", so a button stays disabled rather than lying. The server still decides every call, so a stale "allowed" only ever ends in a clean ACCESS_DENIED.

React

import type { LiveConsole } from '@better-compute/console-kit';
import { useList } from '@better-compute/console-kit/react';

function Reservations({ live }: { live: LiveConsole }) {
  const { items, status } = useList(live.reservations);
  if (status === 'loading') return <p>Loading</p>;
  return <ul>{items.map((item) => <li key={item.id}>{item.id}: {String(item.state)}</li>)}</ul>;
}

The /react entry binds the hooks to the app's react, an optional peer (React 19). Apps that bring their own React build, or preact/compat, call bindReact(React) from the main entry instead. useList and useDetail load on first use; usePermission returns undefined while IAM answers (render the button disabled), then true or false; useAction(detail, path) returns run, pending, and the outcome or error. The hooks use useSyncExternalStore with the same snapshot on the server, so they render during SSR.

Related: TypeScript client, tunnels, delegated confirmation.