Docs / Quickstart
60-SECOND QUICKSTART

From zero to live microVM,
Postgres, and fork() in 60s.

Follow four concrete CLI steps to spin up a 2 vCPU sandbox in us-east, attach a dedicated NVMe PostgreSQL 17 database on private DNS, live-fork your VM, and pause idle compute down to $0.00/hr.

STEP 01

Create your account & export your API key

~10 sec

Sign up at /register to receive $10 in starter credit and generate a workspace Bearer token from your dashboard, then install the uncage CLI binary.

# Install the uncage CLI
$ curl -fsSL https://uncage.sh/install.sh | sh

# Authenticate your shell session
$ export UNCAGE_API_URL="https://api.uncage.sh"
$ export UNCAGE_API_KEY="ucg_live_your_api_key_here"

# Verify connectivity
$ uncage status
{ "status": "ok" }
STEP 02

Create a project & launch a 2 vCPU VM in us-east

~15 sec

Every project gets its own private internal DNS namespace. Pick your cores, memory, and region (us-east, eu-central, us-west, or ap-south) and boot an isolated Linux microVM.

# Create a project in us-east (Virginia)
$ uncage projects create --name quickstart --region us-east
{
  "id": "proj_01j9qs",
  "name": "quickstart",
  "region": "us-east"
}

# Launch a 2 vCPU · 4 GB AI sandbox microVM
$ uncage workloads create \
    --project proj_01j9qs \
    --name dev-box \
    --surface sandbox \
    --image uncage/sandbox-python:3.12 \
    --vcpu 2 --mem 4096

# Active rate: $0.0936/hr  |  Idle/Paused rate: $0.0000/hr
STEP 03

Attach dedicated NVMe PostgreSQL 17 on private DNS

~15 sec

Provision PostgreSQL 17 inside the exact same project. Your sandbox reaches it immediately via private internal DNS with zero public port exposure.

# Provision PostgreSQL 17 in proj_01j9qs
$ uncage workloads create \
    --project proj_01j9qs \
    --name pg-quickstart \
    --surface database \
    --image postgres:17 \
    --vcpu 2 --mem 4096 --port 5432

# Verify private DNS connectivity from inside your sandbox
$ uncage workloads exec <dev-box-id> -- \
    sh -c 'pg_isready -h pg-quickstart.quickstart.internal -p 5432'
pg-quickstart.quickstart.internal:5432 - accepting connections
STEP 04

Live-fork memory + disk state, then pause to $0/hr

~20 sec

Clone a running sandbox in ~180ms to test an alternative branch or migration without redoing setup, then pause idle workloads so compute billing drops strictly to $0.00/hr.

# Create a warm state inside dev-box
$ uncage workloads exec <dev-box-id> -- python3 -c "print('state ready')"

# Live copy-on-write fork (~180ms, memory + disk preserved)
$ uncage workloads fork <dev-box-id> --name dev-box-exp-b
{
  "id": "wl_01j9fork",
  "name": "dev-box-exp-b",
  "state": "running"
}

# Pause when finished — RAM + disk preserved at $0.00/hr compute
$ uncage workloads pause <dev-box-id>
{ "id": "<dev-box-id>", "state": "sleeping" }

# Resume anytime in sub-second time
$ uncage workloads resume <dev-box-id>
QUICKSTART FAQ

Common setup questions.

01 How do I authenticate the uncage CLI?
Sign up at /register, copy your API key from the dashboard, and export UNCAGE_API_KEY="ucg_live_..." and UNCAGE_API_URL="https://api.uncage.sh" in your shell profile.
02 How does my sandbox connect to a PostgreSQL database I just created?
Workloads inside the same project can reach each other immediately over private internal DNS (for example, pg-quickstart.quickstart.internal:5432) with no firewall rules required.
03 What happens to my billing when I run uncage workloads pause?
Compute billing drops immediately to $0.0000/hr while memory and disk snapshots are preserved. You only pay $0.10/GB-month for stored disk capacity.
TRY IT LIVE

Ready to run step 01 in your terminal?

Create a free account to claim $10 in starter credit and generate your Bearer API key instantly.

✓ $10 starter credit on signup
✓ Strictly $0.00/hr compute when sleeping
✓ Sub-second boot across 4 global regions