Self-hosting

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.

GCP development cell

Run a complete single-cell development environment on one nested-KVM Compute Engine VM.

Configuration reference

Review the control-plane environment-variable shape.

Ask AI about this page

Architecture

OpenComputer has three runtime tiers:

text

12345678910111213141516171819202122232425262728293031Client, 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:

The control plane authenticates the request and selects a worker with capacity.
The worker creates a copy-on-write disk from the selected rootfs image.
QEMU starts the sandbox with KVM acceleration.
The worker waits for osb-agent, applies sandbox networking and environment configuration, and reports the sandbox as running.
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

123456789+--------------------------------------------------+
| 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 for this topology.

Scalable hosting

A scalable deployment separates the control plane from a pool of worker machines:

text

12345678910111213141516171819202122                         +----------------------+
                         | 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.