os-hub

Lifecycle

Lifecycle changes run as jobs, with progress and a final state.

The API answers at once and hands the work to a job: provision, start, stop, pause, restart, deploy or deprovision. The job calls the provider and writes its progress and the result to SQLite, where the console reads them; a job that brings the instance up also waits up to three minutes for it to report healthy. An instance is running, idle after a pause, off after a stop, or failed. On Modal and Vercel, a start brings the sandbox up at a new endpoint; the address under os.zionru.dev stays the same.

Job records are persisted, but lifecycle execution runs inside the hub process. A durable queue and restart recovery remain production work. Deprovision removes the local record even if remote destruction fails, so that result alone does not confirm provider cleanup.

Providers

One interface for every sandbox, with the extras made explicit.

Every provider can provision, start, stop, pause, restart, destroy and tail logs. Files, metrics, deploys and a shell are optional: a provider opts in by implementing them, and the hub offers the matching console tabs only where it has. A pause keeps something different on each: the container on Docker, the volume on Modal, a snapshot on Vercel, memory on E2B. Platform, the default, hands off to a driver, Docker unless configured; a hosted installation can choose a cloud driver instead.

Integrations connects each user’s cloud provider account. Credentials are encrypted in the hub and resolved server-side when acting on that user’s instances. Platform continues to use its configured driver; the sandbox and its durable data follow that driver’s lifecycle semantics.

Console

Inspect the environment and operate the instance from one console.

Logs is always available. Monitor, Files, Config, Deploys and Shell follow the provider’s declared capabilities, with command execution also controlled by a hub setting. The same capability checks govern the API, so the console reflects the operations the backend can actually perform.

For providers with metrics, a background sampler records CPU, memory, disk, data size and file count, then folds headline values into the fleet view. The monitor adds history and provider telemetry such as session expiry. Bastion derives sandbox posture from the hub’s observed facts and marks unobserved layers as unassessed.

Config & deploy

Track what is saved, what is deployed, and what passed health checks.

Each instance has a versioned environment configuration. Secret values are encrypted at rest and masked in the console. Editing advances the saved version; the deployed version records the configuration the sandbox successfully started with. A mismatch appears as pending configuration drift.

A deployment selects an image or git revision through a capable provider. The hub records the requested revision, job progress and bounded build log, then records the resolved digest or commit when supplied. Successful health checks mark the deployment and configuration as applied. A failed deployment remains visible in history.

Access & routing

A stable address reaches the current sandbox; each OS owns its session.

Human management uses the hub’s server-side WorkOS sign-in and sealed session. The external identity maps to a local user ID, and instance operations check that owner. Launch checks that the instance is running, then opens its own AuthKit login entry point when WorkOS is configured. The OS establishes its own session through the shared identity environment.

Cloud URLs stay under os.zionru.dev while the underlying provider endpoint can change. The hub proxy looks up the hostname, checks the running state and forwards to the current endpoint in sandbox metadata. Unknown, stopped or unreachable instances return explicit errors. Docker uses a loopback host port.

Rooms

Manage collaboration spaces and keep the result after they close.

The Rooms page creates or links owned Getaroom rooms, shows seats and shared context, edits supported permission rules and issues participant keys. Getaroom owns the room sandbox and runtime enforcement. The hub owns its room link, operation records, cached snapshots and retained receipts.

Create and close intent is persisted before the remote request. Ambiguous creation goes to review unless the remote service guarantees idempotent creation. Closing seals the room; receipt archival retries separately if retrieval fails. Live events refresh the detail view, while snapshots restore its current state after reconnecting.

Background room work uses the owner’s verified access token in memory. After restart or expiry it waits for the user to reopen Rooms or Networks; unattended service authorization is a later step.

Networks

Group your instances, discover peers, and prepare access to shared rooms.

A network groups OS instances owned by one hub user and links Getaroom rooms. Enrollment stages a separate machine credential in encrypted instance configuration; the authentication record stores its hash. Rotation or revocation invalidates that identity. Membership enables scoped discovery, while availability comes from client heartbeats rather than sandbox running status.

Invitations carry instructions and an optional coordinator. Peer requests require owner approval by default, and every recipient independently accepts. The hub then prepares a room credential for that instance, tracks join reports and revokes access when the invitation ends. The coordinator label describes the task; it grants no extra room privileges.

The Hub side is implemented. Until the OS client connects, members await their first connection and invitations await acceptance. Creating an invitation does not start an agent; uncertain seat creation requires reconciliation.

State

Keep the fleet’s control records separate from each OS’s working data.

One SQLite database holds users, provider accounts, instances, jobs, deployments, metrics and activity, plus room links, receipts, networks, machine identities and invitations. Agent sessions, app data and runtime memory belong inside each Zion OS sandbox, with persistence determined by its provider.

The hub currently runs as one process: lifecycle jobs, monitoring, room reconciliation and invitation cleanup execute alongside the API. Lifecycle progress is stored, but the executing job is not a durable queue. Room and invitation intent supports more explicit recovery, including review states for uncertain remote effects.

Keep the encryption key with a recoverable database backup. The storage abstraction, organization/team model and production scaling topology are documented plans; they are not implemented guarantees.