Agent-readable docs index: /llms.txt. Full docs in one file: /llms-full.txt. Download /docs.zip to grep all markdown files locally.

/

Getting Started

Install
Quick Example
Next Steps

Prerequisites
Create Your First Sandbox
Next Steps

Virtual Machines
Hibernation
Checkpoints & Forking
Templates
Elasticity
Networking

Sandboxes

Creating a Sandbox
Parameters
Connecting to an Existing Sandbox
Lifecycle
Hibernation & Wake
Methods
Properties
Python Context Manager
Forking from Checkpoints
Related

Running Commands

Quick Commands: exec.run()
Parameters
ProcessResult
Async Commands: exec.start() / exec.background()
ExecStartOpts
ExecSession
Stateful Shell: exec.shell()
Reattaching to an open shell
Terminal-tab semantics
Streaming output
Managing Sessions
List Sessions
Attach to Running Session
Kill a Session

Working with Files

Reading Files
Writing Files
Listing Directories
EntryInfo
Managing Files
Create Directory
Remove
Check Existence
Large Files
Examples
Upload and Run a Script

How it works
Supported Backends
Examples
S3 (AWS)
S3-compatible (MinIO, R2, Tigris, etc.)
Google Cloud Storage
SFTP
Custom Config
Read-only by default
Listing and removing
Hibernate behavior
Stale credentials
CLI
Troubleshooting
Bring your own FUSE
The {mountpoint} token
env and secrets
Requirements
Example: gcsfuse
Example: bindfs

How It Works
Generating URLs
Downloading Files
Uploading Files
Large Files
Security

Interactive Terminals

Creating a PTY
Parameters
PtySession
Resize
CLI

Timeout & Hibernation

Default: persistent (no auto-hibernate)
Setting a timeout
Update on a running sandbox
What happens when the timeout expires
Waking up
Choosing a timeout
See also

Checkpoint Types
Checkpoints vs Hibernation
What Gets Preserved
API Reference
Create Checkpoint
List Checkpoints
Fork from Checkpoint
Restore Checkpoint
Delete Checkpoint
CheckpointInfo
Example: Parallel Exploration

Declarative image building
Build memory
Creating pre-built snapshots
Sizing a fork's memory
Managing snapshots
Default template
Image configuration
SnapshotInfo

How it works
Quick start
Per-secret host restrictions
Egress allowlists
Managing secrets
Secrets with snapshots and checkpoints
Snapshot template with secrets
Checkpoint fork with secrets
Layering rules
Security properties
Next steps

API Reference
Create Patch
List Patches
Delete Patch
When Patches Run
Execution Order
PatchInfo
Example: Environment-Specific Forks

Quick Access
Authentication
Enable at create time
Making authenticated requests
Rotation
What's stored and what's not
Where the check happens
Explicit Preview URLs
API Reference
Create Preview URL
List Preview URLs
Delete Preview URL
Custom Domains
Persistence
Multiple Ports

WebhooksPreview

Events
Destinations
Subscribe at create
Deliveries
Signing, retries, and dedupe
Verify a webhook

Autoscaling
Enable
Behavior
Disable
Inspect
Manual Scaling (Control Plane)
In-VM Scaling
Scale Memory
Check Current Limits
Example: Rust Compilation
Example: Custom Scaling Loop
Locking Resources

Burst Sandboxes

Pricing
Create a Burst Sandbox
What Happens on Interruption
Good Fits
Poor Fits
Alpha Limitations
Reliability Pattern
Related

Usage Monitoring

Example
Request
Response
Allocated vs used
Calling it
Bucket semantics

Browser Sessions

Browser Sessions

Create a Browser
Profile Auth Checks
Playwright
Magnitude
Save and Load Profiles
Authentication

Reserved Capacity

Reserved Capacity

Reservations are non-refundable
The unit is 1 GB-hour
A small example
Why reserve instead of running on-demand?
Where to go next

Interval
Reservation
The reservation log
Calendar
Per-org capacity cap
Usage and overage
Where to go next

Reading the Calendar

Request
Response
Top-level fields
Per-interval fields
reservableGb is the planning field
The calendar is a snapshot, not a hold
Race patterns
Plan then write
Plan then write, lost race
Multi-interval request, partial conflict
Choosing the window
What the calendar does not tell you
Where to go next

Reserving Capacity

Make a reservation
Validation
Capacity shortfall (409)
Idempotency
Cancellation does not exist
List your reservations
Concurrency and atomicity
Where to go next

Usage and Overage

Every second is its own settlement
A worked example
Three contrasting cases
Reservation and overage are independent
Common confusions
Edge cases
Why per-second
Where to go next

CLI

Installation
Sign in
Credential resolution
Global Flags
Key Workflows
Quick Start
JSON Output & Scripting
Top-level Shortcuts
Create and Shell In
Hibernate for Cost Savings
Checkpoint and Fork
Command Reference

Sandbox Management

Creating a Sandbox
Listing & Inspecting
Hibernation & Wake
Adjusting Timeout
Killing a Sandbox
Common Patterns
Create and Shell In
Filter Running Sandboxes
Batch Cleanup

Running Commands

Running a Command
Working Directory & Environment
Timeouts
Creating an Exec Session
Capturing Output as JSON
Managing Exec Sessions
Shell vs Exec

Opening a Shell
Choosing a Shell
What Works
Shell vs Exec
Tips
Create and Shell In
Shell with Custom Environment

Creating a Checkpoint
Forking from a Checkpoint
Restoring
Listing and Deleting
Checkpoint vs Hibernate

What Patches Do
Creating a Patch
Layering Setup
Inspecting Patches
Removing a Patch

Exposing a Port
Sharing a Dev Server
Multiple Ports
Custom Domains
Cleanup
Bearer-Token Authentication

Secret stores
Secrets
Using secrets in sandboxes

Guides

Build a Lovable Clone

Prerequisites
Step 1: Sign Up for OpenComputer
Step 2: Generate an API Token
Step 3: (Optional) Add a Custom Domain
Step 4: Set Up the Project
How It Works
Generation Flow
Sandbox as Tool Calls
Limitations of This Approach
Deployment Model
How Deployment Works
Why a Separate Sandbox?
Hibernation and Wake-Up
Limitations and What's Coming
Current Limitations
What's Changed Since This Guide Was Written
Still Planned

Browser Automation

When to reach for a browser (vs. an API)
Step 1: Build a snapshot with Chromium pre-installed
Step 2: Per-boot setup that can't be baked in
Networking: the secretStore requirement
Step 3: Run a headless browser
Step 4: Run a headed browser (for interactive login)
Step 5: Persist login across runs
Resource and concurrency limits
Choosing a browser automation library
Troubleshooting
Next steps

Install
Prerequisites
Usage

TypeScript SDK

Installation
Modules

Static Methods
Sandbox.create(opts?)
Sandbox.connect(sandboxId, opts?)
Sandbox.createFromCheckpoint(checkpointId, opts?)
Sandbox.createCheckpointPatch(checkpointId, opts)
Sandbox.listCheckpointPatches(checkpointId, opts?)
Sandbox.deleteCheckpointPatch(checkpointId, patchId, opts?)
Instance Methods
sandbox.kill()
sandbox.isRunning()
sandbox.hibernate()
sandbox.wake(opts?)
sandbox.setTimeout(timeout)
sandbox.createCheckpoint(name, opts?)
sandbox.listCheckpoints()
sandbox.restoreCheckpoint(checkpointId)
sandbox.deleteCheckpoint(checkpointId)
sandbox.getPreviewDomain(port)
sandbox.downloadUrl(path, opts?)
sandbox.uploadUrl(path, opts?)

How the three interact
sandbox.scale(opts)
sandbox.setAutoscale(opts)
sandbox.getAutoscale()
sandbox.setScalingLock(locked)
sandbox.getScalingLock()
Errors
ScalingLockedError
PlanLimitError

usage.forSandbox(sandboxId, opts?)
usage.bySandbox(opts?)
usage.byTag(tagKey, opts?)
tags.set(sandboxId, tags)
tags.get(sandboxId)
tags.listKeys()
Units
Types

sandbox.exec.run(command, opts?)
sandbox.exec.start(command, opts?)
sandbox.exec.background(command, opts?)
sandbox.exec.shell(opts?)
Shell
ShellRunOpts
sandbox.exec.attach(sessionId, opts?)
sandbox.exec.list()
sandbox.exec.kill(sessionId, signal?)
ExecSession
Types

sandbox.files.read(path)
sandbox.files.readBytes(path)
sandbox.files.write(path, content)
sandbox.files.list(path?)
sandbox.files.makeDir(path)
sandbox.files.remove(path)
sandbox.files.readStream(path)
sandbox.files.writeStream(path, stream)
sandbox.files.exists(path)
Types

sandbox.pty.create(opts?)
PtySession

Image.base()
Builder Methods
image.aptInstall(packages)
image.pipInstall(packages)
image.runCommands(...cmds)
image.env(vars)
image.workdir(path)
image.addFile(remotePath, content)
image.addLocalFile(localPath, remotePath)
image.addLocalDir(localPath, remotePath)
image.builderMemory(mb)
Utility Methods
image.toJSON()
image.cacheKey()

Constructor
snapshots.create(opts)
snapshots.list()
snapshots.get(name)
snapshots.delete(name)
Types

SecretStore.create(opts)
SecretStore.list(opts?)
SecretStore.get(storeId, opts?)
SecretStore.update(storeId, opts)
SecretStore.delete(storeId, opts?)
SecretStore.setSecret(storeId, name, value, opts?)
SecretStore.listSecrets(storeId, opts?)
SecretStore.deleteSecret(storeId, name, opts?)
Using Secrets with Sandboxes
Using Secrets with Snapshots and Checkpoints
Snapshot template with secrets
Checkpoint fork with secrets
Types

Python SDK

Installation
Modules

Class Methods
await Sandbox.create(...)
await Sandbox.connect(sandbox_id, ...)
await Sandbox.create_from_checkpoint(checkpoint_id, ...)
await Sandbox.create_checkpoint_patch(checkpoint_id, script, ...)
await Sandbox.list_checkpoint_patches(checkpoint_id, ...)
await Sandbox.delete_checkpoint_patch(checkpoint_id, patch_id, ...)
Context Manager
Instance Methods
await sandbox.kill()
await sandbox.is_running()
await sandbox.set_timeout(timeout)
await sandbox.create_checkpoint(name, kind=None, retention_policy=None)
await sandbox.list_checkpoints()
await sandbox.restore_checkpoint(checkpoint_id)
await sandbox.delete_checkpoint(checkpoint_id)
await sandbox.download_url(path, *, expires_in=3600)
await sandbox.upload_url(path, *, expires_in=3600)
await sandbox.create_preview_url(port, domain?, auth_config?)
await sandbox.list_preview_urls()

How the three interact
sandbox.scale(memory_mb)
sandbox.set_autoscale(enabled, *, min_memory_mb=None, max_memory_mb=None)
sandbox.get_autoscale()
sandbox.set_scaling_lock(locked)
sandbox.get_scaling_lock()
Errors
ScalingLockedError
PlanLimitError

await sandbox.exec.run(command, ...)
await sandbox.exec.start(command, ...)
await sandbox.exec.background(command, ...)
await sandbox.exec.shell(...)
Shell
await sandbox.exec.attach(session_id, ...)
await sandbox.exec.list()
await sandbox.exec.kill(session_id, signal=9)
ExecSession
Types

await sandbox.files.read(path)
await sandbox.files.read_bytes(path)
await sandbox.files.write(path, content)
await sandbox.files.list(path="/")
await sandbox.files.make_dir(path)
await sandbox.files.remove(path)
await sandbox.files.exists(path)
await sandbox.files.read_stream(path)
await sandbox.files.write_stream(path, stream)
Types

await sandbox.pty.create(cols=80, rows=24, on_output=None)
PtySession

Image.base()
Builder Methods
image.apt_install(packages)
image.pip_install(packages)
image.run_commands(*cmds)
image.env(vars)
image.workdir(path)
image.add_file(remote_path, content)
image.add_local_file(local_path, remote_path)
image.add_local_dir(local_path, remote_path)
image.builder_memory(mb)
Utility Methods
image.to_dict()
image.cache_key()

Constructor
await snapshots.create(name, image, on_build_logs=None)
await snapshots.list()
await snapshots.get(name)
await snapshots.delete(name)
SnapshotInfo

await SecretStore.create(**kwargs)
await SecretStore.list(**kwargs)
await SecretStore.get(store_id, **kwargs)
await SecretStore.update(store_id, **kwargs)
await SecretStore.delete(store_id, **kwargs)
await SecretStore.set_secret(store_id, name, value, **kwargs)
await SecretStore.list_secrets(store_id, **kwargs)
await SecretStore.delete_secret(store_id, name, **kwargs)
Using Secrets with Sandboxes
Using Secrets with Snapshots and Checkpoints
Snapshot template with secrets
Checkpoint fork with secrets

CLI Reference

Global Flags
Commands

oc sandbox create
oc sandbox list
oc sandbox get <id>
oc sandbox kill <id>
oc sandbox hibernate <id>
oc sandbox wake <id>
oc sandbox set-timeout <id> <seconds>
oc sandbox allowed-hosts <id>
Layered forks

oc sandbox scaling

oc sandbox autoscale <id>
oc sandbox scale <id> <memory-mb>
oc sandbox lock <id>
oc sandbox unlock <id>
oc sandbox lock-status <id>

oc exec <id> [flags] -- <command...>
oc exec list <id>
oc exec attach <id> <session-id>
oc exec kill <id> <session-id>

oc checkpoint create <sandbox-id>
oc checkpoint list <sandbox-id>
oc checkpoint restore <sandbox-id> <checkpoint-id>
oc checkpoint spawn <checkpoint-id>
oc checkpoint delete <sandbox-id> <checkpoint-id>

oc patch create <checkpoint-id>
oc patch list <checkpoint-id>
oc patch delete <checkpoint-id> <patch-id>

oc preview create <sandbox-id>
oc preview list <sandbox-id>
oc preview delete <sandbox-id> <port>
oc preview rotate-auth <sandbox-id>

Agent URLs and Hooks

oc agent invoke
oc agent hook create
oc agent hooks
oc agent hook get
oc agent hook revoke

Login and identity

oc login
oc whoami
oc logout

oc config set <key> <value>
oc config show

API Reference

Base URL
Authentication
WebSocket Authentication
Error Format

List DirectoryGET

Create DirectoryPOST

Delete File or DirectoryDELETE

Generate Download URLPOST

Generate Upload URLPOST

Signed DownloadGET

Signed UploadPUT

Resources

Troubleshooting

Common Errors
401 Unauthorized
Sandbox not found
Connection refused
Timeout errors
Agent exits immediately
Debugging Tips
Check sandbox status
List running processes
Capture agent errors
Read sandbox logs
Getting Help

Self-hosting

Architecture
Control plane
Data plane
In-VM agent
Request lifecycle
Deployment shapes
Single-cell development
Scalable hosting
State and storage
Networking and security
Moving from development to scalable hosting

GCP development cell

What gets created
Prerequisites
Configure the deployment
Restrict ingress before creating the VM
Create the host
Deploy OpenComputer
Wait for worker registration
Validate the cell
Use the dashboard during development
Start the development UI
Forward it to your machine
Operations
Rebuild the rootfs
Storage and shutdown
Troubleshooting
no workers available
/dev/kvm is missing
The control-plane root redirects to localhost:3000
API requests return 401
The public IP changed

Read File

Returns file content as plain text (not JSON).

path idstringrequired

Sandbox ID

query pathstringrequired

Absolute path to the file

Ask AI about this page

Response example

1Hello, World!

Powered byHolocron

Prev pageNext page