Cats
中文Open console
Menu
ProductDocsLifecycleCurrent scope中文Open console

Cats documentation

Public Cats user documentation for cloud workspaces, lifecycle, storage, endpoints, CLI, HTTP and Runtime APIs, identity, and troubleshooting.

Documentation
Cats documentationGetting startedCats and lifecycleStorage and disksEndpoints and networkingCLI referenceHTTP API referenceGuest Runtime APIConsole, identity, and workspacesOperations and troubleshooting
Public by design

These product and usage docs require no Cats session. The console and resource APIs still enforce their normal authentication boundaries.

Choose a path

Get startedBuild the CLI, configure access, create a Cat, and run your first command. Cats and lifecycleUnderstand Running, Suspended, Warm, Cold, wake behavior, and deletion. Storage and disksUse RootDisk, PersistentDisk, snapshots, resize, mount, and durable FLUSH. EndpointsPublish a Guest port, choose wake behavior, and understand current networking scope. CLI referenceAll commands, global options, output modes, and automation behavior. HTTP API referenceRoutes, authentication scopes, idempotency, request bodies, Operations, and errors. Guest Runtime APIKeep work-driven Cats awake through HTTP over a Guest-local Unix socket. Console and identityWorkOS browser/device sign-in, workspaces, sessions, and language settings. Operations and troubleshootingFollow asynchronous work, read errors, and recover from common failures.

Product model

A Cat is a long-lived Linux microVM with a required RootDisk. Compute may stop while the Cat name and durable disk remain. A Workspace is the user-visible authorization and resource boundary; the V1 HTTP API keeps the compatible project path segment underneath.

  • RootDisk follows the Cat and is deleted with it.
  • PersistentDisk is independent, grow-only in V1, and read-write attached to at most one Cat.
  • Endpoint maps a stable hostname to one Guest port and may wake a sleeping Cat.
  • Operation records every asynchronous mutation and its final structured error.

Current V1 developer shape

The Rust workspace implements the control plane, CLI, embedded user/admin consoles, node and Guest agents, endpoint gateway contracts, ChunkStore engine, provider-neutral storage adapters, and a Cloud Hypervisor Phase-A path. The following limitations matter when evaluating or operating this source version:

AreaCurrent statusWhat it means
Block frontendKernel NBD in Cloud Hypervisor Phase ANative vhost-user-blk remains a later performance milestone.
Guest networkingTap/overlay not implementedEndpoint routing is covered in the FakeVmm development path; do not claim full CH Guest networking yet.
Suspended memory reclaimCH Phase A currently pauses onlyThe designed page-out path is not implemented, so Suspended currently saves vCPU rather than Host memory.
Control metadataSQLite development storeThe PostgreSQL storage metadata adapter exists, but the project resource store is still SQLite-shaped development state.
Privilege separationNot implementedRun development components only in an appropriately isolated environment.
Performance numbers are evidence, not an SLA

Repository benchmark results preserve sample count, environment, measurement boundary, and correctness oracle. Never promote those prototype measurements to a production commitment.

Documentation conventions

Examples use the Workspace selected by cats login and a Cat named dev. Replace them for your deployment. Sizes accept binary suffixes such as 512MiB and 8GiB.