> ## Documentation Index > Fetch the complete documentation index at: https://docs.opencomputer.dev/llms.txt > Use this file to discover all available pages before exploring further. # Self-hosting > Understand the OpenComputer architecture and choose a development or scalable deployment shape. OpenComputer can run inside your own cloud account. A self-hosted deployment combines an API control plane with Linux hosts that use QEMU/KVM to run isolated sandbox VMs. Self-hosting is an operator workflow. You are responsible for provisioning the cloud resources, securing the API, operating the data stores, and upgrading the OpenComputer services. Run a complete single-cell development environment on one nested-KVM Compute Engine VM. Review the control-plane environment-variable shape. ## Architecture OpenComputer has three runtime tiers: ```text theme={null} Client, SDK, CLI, or dashboard | | HTTP v +---------------+----------------+ | Control plane | | | | API and authentication | | Sandbox lifecycle and routing | | Worker coordination | +---------------+----------------+ | | worker RPC v +---------------+----------------+ | Data plane worker | | | | QEMU/KVM VM lifecycle | | Networking and storage | | Checkpoint and hibernation | +---------------+----------------+ | | virtio serial / vsock v +---------------+----------------+ | Sandbox VM | | | | Full Linux filesystem | | OpenComputer in-VM agent | | User commands and processes | +--------------------------------+ ``` ### Control plane The control plane exposes the OpenComputer HTTP API. It authenticates requests, tracks sandbox state, chooses a worker, and routes operations to the worker that owns each sandbox. The control-plane binary is named `opensandbox-server`. The historical `opensandbox` name also appears in environment variables as the `OPENSANDBOX_*` prefix. ### Data plane Data-plane workers run on Linux machines with KVM. Each worker starts QEMU microVMs, configures their networking and disks, and maintains the connection to the agent inside each VM. The worker binary is named `opensandbox-worker`. A worker registers itself with the control plane through Redis and advertises its capacity and RPC address. ### In-VM agent Every sandbox image contains `osb-agent`. It receives command, file, terminal, and process operations from the worker over a VM-local transport. User workloads do not need direct access to the worker host. ## Request lifecycle When a client creates a sandbox: 1. The control plane authenticates the request and selects a worker with capacity. 2. The worker creates a copy-on-write disk from the selected rootfs image. 3. QEMU starts the sandbox with KVM acceleration. 4. The worker waits for `osb-agent`, applies sandbox networking and environment configuration, and reports the sandbox as running. 5. Subsequent API calls are routed to the owning worker and then to the in-VM agent. OpenComputer can keep paused VMs in a warm pool. Claiming a prepared VM avoids most cold-start work while preserving VM isolation. ## Deployment shapes ### Single-cell development A development cell can run every component on one VM: ```text theme={null} +--------------------------------------------------+ | One development VM | | | | opensandbox-server :8080 | | opensandbox-worker | | PostgreSQL + Redis | | QEMU/KVM sandbox VMs | | local rootfs images and sandbox disks | +--------------------------------------------------+ ``` This is the fastest way to test real VM behavior. It is not highly available, and local storage can be ephemeral. Use the [GCP development guide](/self-hosting/gcp-development) for this topology. ### Scalable hosting A scalable deployment separates the control plane from a pool of worker machines: ```text theme={null} +----------------------+ | HTTPS load balancer | +----------+-----------+ | +----------v-----------+ | Control plane | | one or more replicas | +----+-------------+---+ | | +---------v--+ +--v-----------+ | PostgreSQL | | Redis | +------------+ +--------------+ | +---------v-------------------------+ | Worker pool | | KVM host | KVM host | KVM host | +------------------+----------------+ | +--------v---------+ | Object storage | | durable VM data | +------------------+ ``` A production-shaped deployment should include: * Multiple control-plane replicas behind HTTPS. * A worker pool spread across failure domains. * Durable PostgreSQL and Redis services. * S3-compatible object storage for checkpoints, hibernation archives, and durable image artifacts. * A secrets manager for database credentials, signing keys, storage credentials, and third-party integrations. * Monitoring, centralized logs, backups, and tested recovery procedures. * Private worker networking. Only the control-plane or edge endpoint should be public. The control plane can launch cloud workers using the supported provider integrations, or workers can be provisioned independently and configured to register with the cell. ## State and storage Different data has different durability requirements: | Data | Recommended storage | | ---------------------------------------- | -------------------------------------------- | | Organizations, API keys, sandbox records | PostgreSQL | | Worker registry and coordination | Redis | | Checkpoints and hibernation archives | S3-compatible object storage | | Golden rootfs images | Worker image or durable object storage | | Active sandbox disks | Fast local NVMe or provisioned block storage | Fast local disks are a good fit for active copy-on-write sandbox disks, but they must not be the only copy of data that needs to survive a worker replacement. ## Networking and security At minimum: * Terminate public traffic with HTTPS. * Keep worker RPC, Redis, PostgreSQL, and worker HTTP ports on private networks. * Use a randomly generated API key for development and a managed authentication flow for shared environments. * Store secrets outside source control. * Restrict administrative SSH access to known source addresses or an identity aware access layer. * Treat preview URLs and sandbox egress as security boundaries, not ordinary application routes. The single-cell development guides intentionally trade availability and durability for simplicity. Do not expose one directly to untrusted traffic. ## Moving from development to scalable hosting Use the single-cell environment to validate: * KVM and sandbox boot. * The unified rootfs and in-VM agent. * Command, file, and terminal APIs. * Checkpoint and wake behavior after object storage is configured. * Your client and SDK integration. Before serving production traffic, move PostgreSQL, Redis, and durable artifacts off the worker host; place the API behind HTTPS; provision replaceable workers; and test worker loss while sandboxes are running.