Quickstart#

Create a sandbox, run a command, expose a port, and pause it. Takes about five minutes.

Private beta. You need a beta account. Join the waitlist. The Free plan includes 20 one-time hours of the default size, no card required.

1. Get an API key#

Create a key in the dashboard (Settings → API keys) or with the CLI after taskcloud login:

taskcloud key create --name quickstart --preset full-sandbox

Keys look like taskcloud_sk_... and are shown once. Export it:

export TASKCLOUD_API_KEY="taskcloud_sk_..."

The SDKs and the CLI read TASKCLOUD_API_KEY automatically.

2. Install#

npm install @taskcloud/sdk        # TypeScript / JavaScript (Node.js 20+; PTY needs Node.js 22+ or the `ws` package)
pip install taskcloud             # Python 3.9+

The CLI is built from source during the beta (go build in cli/, Go 1.27.3+); see CLI. The install script (curl -fsSL https://task.cloud/install.sh | sh) and prebuilt binaries work once the first CLI release is tagged.

3. Create a sandbox and run a command#

TypeScript#

import { Client } from "@taskcloud/sdk";

const client = new Client(); // reads TASKCLOUD_API_KEY

const sandbox = await client.sandboxes.create({
  template: "base",
  size: "default",
  name: "quickstart",
  auto_pause: { enabled: true, idle_timeout_seconds: 300 },
});
console.log(sandbox.id, sandbox.state); // sbx_... running

const result = await sandbox.exec({ command: "uname -a && python3 --version" });
console.log(result.exit_code, result.stdout);

Python#

from taskcloud import Client

client = Client()  # reads TASKCLOUD_API_KEY

sandbox = client.sandboxes.create(
    template="base",
    size="default",
    name="quickstart",
    auto_pause={"enabled": True, "idle_timeout_seconds": 300},
)
print(sandbox.id, sandbox.state)

result = sandbox.exec(command="uname -a && python3 --version")
print(result.exit_code, result.stdout)

CLI#

id=$(taskcloud create --template base --size default --name quickstart --json | jq -r .id)
taskcloud exec "$id" -- uname -a

curl#

API=https://api.task.cloud/v1

id=$(curl -sS -X POST "$API/sandboxes" \
  -H "Authorization: Bearer $TASKCLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"template":"base","size":"default","name":"quickstart"}' | jq -r .id)

curl -sS -X POST "$API/sandboxes/$id/exec" \
  -H "Authorization: Bearer $TASKCLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"command":"uname -a && python3 --version"}'
# {"command_id":"cmd_...","exit_code":0,"stdout":"Linux ...","stderr":"","duration_ms":41}

POST /sandboxes waits until the sandbox is running (target p95 < 500 ms from a template) and returns 201. Pass "wait": false to get 202 immediately.

4. Start a server and open it in the browser#

await sandbox.files.write("/home/user/www/index.html", "<h1>Hello from TaskCloud</h1>");
await sandbox.exec({ command: "python3 -m http.server 8080", cwd: "/home/user/www", background: true });
const port = await sandbox.ports.expose({ port: 8080, visibility: "public" });
console.log(port.url); // https://<short_id>-8080.taskhost.cloud
sandbox.files.write("/home/user/www/index.html", "<h1>Hello from TaskCloud</h1>")
sandbox.exec(command="python3 -m http.server 8080", cwd="/home/user/www", background=True)
port = sandbox.ports.expose(port=8080, visibility="public")
print(port.url)
taskcloud exec "$id" --background --cwd /home/user/www -- python3 -m http.server 8080
taskcloud port expose "$id" 8080 --public

5. Pause, then wake it with a request#

await sandbox.pause();            // RAM + disk snapshot; compute billing stops
// ...later: any request wakes it. Opening port.url, an SSH login or an API call all work:
const again = await sandbox.exec({ command: "echo still here" }); // resumes transparently
curl -sS -X POST "$API/sandboxes/$id/pause" -H "Authorization: Bearer $TASKCLOUD_API_KEY"
short=${id#sbx_}                                # hostnames use the ID without sbx_
curl -sS "https://$short-8080.taskhost.cloud/"   # wakes the sandbox, then serves the page

You do not have to pause manually: with the default auto_pause, a sandbox with no activity for 5 minutes pauses itself. See Lifecycle.

6. Clean up#

await sandbox.delete();
taskcloud delete "$id" --yes

Next steps#

Edit this page Report an issue View Markdown