Quickstart

This page is the fastest way to go from “I have credentials” to “I proved Quilt works.”

We are going to do four things:

1. authenticate
2. check health
3. create a container
4. run a command inside it

Prerequisites

• an API key or bearer token
• access to https://backend.quilt.sh
• curl available locally

Step 1: Set Your Base URL and Credentials

X-Api-Key: <key>
Authorization: Bearer <token>

export QUILT_BASE_URL="https://backend.quilt.sh"
export QUILT_API_KEY="your_api_key_here"

Step 2: Check Health the Safe Way

curl "$QUILT_BASE_URL/health"

Then check the container concern specifically:

curl \
  -H "X-Api-Key: $QUILT_API_KEY" \
  "$QUILT_BASE_URL/api/containers/health"

Step 3: Create a Container

curl -X POST \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: $QUILT_API_KEY" \
  "$QUILT_BASE_URL/api/containers" \
  -d '{
    "name": "hello-quilt",
    "image": "prod",
    "command": ["/bin/sh", "-lc", "echo hello from quilt && sleep 300"],
    "memory_limit_mb": 256
  }'

This returns 201 Created with the full container and readiness payload. No operation polling required — the container has already been created and started by the time you get a response.

Example shape:

{
  "container_id": "ctr_123",
  "name": "hello-quilt",
  "state": "running",
  "exec_ready": true,
  "network_ready": true,
  "checks": {
    "state_running": true,
    "minit_responsive": true,
    "network_configured": true,
    "managed_image_valid": true,
    "gui_backend_reachable": null
  }
}

Step 4: Confirm Readiness

Check exec_ready in the create response. If it is true, the container is already ready and you can proceed.

If you need to recheck later, poll the readiness route:

curl \
  -H "X-Api-Key: $QUILT_API_KEY" \
  "$QUILT_BASE_URL/api/containers/<container_id>/ready"

You want exec_ready=true before you run commands.

Step 5: Run a Command

curl -X POST \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: $QUILT_API_KEY" \
  "$QUILT_BASE_URL/api/containers/<container_id>/exec" \
  -d '{
    "command": ["/bin/sh", "-lc", "id && pwd && echo ready"],
    "workdir": "/",
    "timeout_ms": 30000
  }'

That returns the completed result inline:

{
  "container_id": "ctr_123",
  "exit_code": 0,
  "stdout": "uid=0(root) gid=0(root) groups=0(root)\n/\nready\n",
  "stderr": "",
  "execution_time_ms": 14,
  "timed_out": false
}

The One Command-Format Rule to Remember

Quilt expects argv arrays, not a single shell string.

{
  "command": ["npm", "test"]
}

{
  "command": ["/bin/sh", "-lc", "npm test && npm run lint"]
}

{
  "command": "npm test"
}