Getting Started with smolcloud

smolcloud is a managed platform for running microVMs. Create isolated machines, execute commands, upload files, and scale workloads — all via a REST API.

1. Sign up

Go to smolmachines.com/console and sign in with your account. You’ll land on the console.

New accounts join a waitlist and are activated after a short demo. Once your account is active, you can create API keys and machines.

2. Create an API key

Navigate to API Keys and create a key. Save it — you’ll need it for API calls.

export SMOLCLOUD_KEY="smk_your_key_here"
export SMOLCLOUD_URL="https://api.smolmachines.com"

3. Create a machine

curl -X POST $SMOLCLOUD_URL/v1/machines \
  -H "Authorization: Bearer $SMOLCLOUD_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source": {"type": "image", "reference": "alpine"},
    "resources": {"cpus": 1, "memoryMb": 256},
    "name": "my-first-machine",
    "network": {"mode": "open"}
  }'

The response includes the machine’s id — use it in place of MACHINE_ID in the calls below:

{
  "id": "mach-abc123",
  "name": "my-first-machine",
  "state": "stopped"
}

The machine is created in stopped state. It starts automatically when you run your first command.

Expose a web server

To make a machine reachable over the web, publish its port with ports and opt in to public ingress with public: true:

curl -X POST $SMOLCLOUD_URL/v1/machines \
  -H "Authorization: Bearer $SMOLCLOUD_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source": {"type": "image", "reference": "nginx"},
    "resources": {"cpus": 1, "memoryMb": 256},
    "name": "my-web",
    "network": {"mode": "open"},
    "ports": [{"port": 80}],
    "public": true
  }'

Once the machine is started, its url field carries a public app URL of the form https://<name>-<slug>.apps.smolmachines.com (where <slug> identifies your tenant). Omit public (the default is false) to keep the app login-gated so only your account can reach it.

Wait until it’s ready

Poll GET /v1/machines/:id and wait for ready: true before sending traffic — state: "started" only means the VM process launched, while ready means the guest and your server have actually finished booting. Skipping this is the most common integration bug: a warm start reaches started in well under a second, so hitting the URL immediately can fail until the server is up.

until curl -s "$SMOLCLOUD_URL/v1/machines/MACHINE_ID" \
  -H "Authorization: Bearer $SMOLCLOUD_KEY" | grep -q '"ready":true'; do sleep 1; done

Reach a port without exposing it publicly

Instead of public ingress, you can bridge an authenticated connection straight to a published guest port — no tunnel, no public URL:

curl "$SMOLCLOUD_URL/v1/machines/MACHINE_ID/connect/80/" \
  -H "Authorization: Bearer $SMOLCLOUD_KEY"

GET /v1/machines/:id/connect/:port also accepts WebSocket upgrades, so a worker can listen on a published port and you dial in to it. See the Cloud API reference.

4. Run a command

# Machine auto-starts on first exec
curl -X POST $SMOLCLOUD_URL/v1/machines/MACHINE_ID/exec \
  -H "Authorization: Bearer $SMOLCLOUD_KEY" \
  -H "Content-Type: application/json" \
  -d '{"command": "echo hello from smolcloud"}'

Response:

{
  "stdout": "hello from smolcloud\n",
  "stderr": "",
  "exitCode": 0,
  "durationMs": 14,
  "machineId": "mach-abc123"
}

5. Install software

With network: open, machines can install packages:

curl -X POST $SMOLCLOUD_URL/v1/machines/MACHINE_ID/exec \
  -H "Authorization: Bearer $SMOLCLOUD_KEY" \
  -H "Content-Type: application/json" \
  -d '{"command": "apk add --no-cache python3 nodejs", "timeoutSeconds": 120}'

Installed packages persist across commands and machine restarts.

6. Upload and run a script

# Upload
curl -X PUT $SMOLCLOUD_URL/v1/machines/MACHINE_ID/files/workspace/app.py \
  -H "Authorization: Bearer $SMOLCLOUD_KEY" \
  --data-binary @app.py

# Run
curl -X POST $SMOLCLOUD_URL/v1/machines/MACHINE_ID/exec \
  -H "Authorization: Bearer $SMOLCLOUD_KEY" \
  -H "Content-Type: application/json" \
  -d '{"command": "python3 /workspace/app.py"}'

# Download results
curl $SMOLCLOUD_URL/v1/machines/MACHINE_ID/files/workspace/output.json \
  -H "Authorization: Bearer $SMOLCLOUD_KEY"

7. Pipe data via stdin

curl -X POST $SMOLCLOUD_URL/v1/machines/MACHINE_ID/exec \
  -H "Authorization: Bearer $SMOLCLOUD_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "command": ["jq", ".items | length"],
    "stdin": "{\"items\": [1, 2, 3, 4, 5]}\n"
  }'

8. Stop and restart

# Stop (compute billing stops immediately)
curl -X POST $SMOLCLOUD_URL/v1/machines/MACHINE_ID/stop \
  -H "Authorization: Bearer $SMOLCLOUD_KEY"

# Restart (packages and files are still there)
curl -X POST $SMOLCLOUD_URL/v1/machines/MACHINE_ID/start \
  -H "Authorization: Bearer $SMOLCLOUD_KEY"

9. Check your usage

curl "$SMOLCLOUD_URL/v1/usage?from=2026-05-01T00:00:00Z&to=2026-06-01T00:00:00Z" \
  -H "Authorization: Bearer $SMOLCLOUD_KEY"

10. Clean up

curl -X DELETE $SMOLCLOUD_URL/v1/machines/MACHINE_ID \
  -H "Authorization: Bearer $SMOLCLOUD_KEY"

What’s next