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/cloud and sign in with your account. You’ll land on the cloud dashboard.

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 machine is created in stopped state. It starts automatically when you run your first command.

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