Skip to main content

​
What is warm pool?

Warm pool keeps a set of pre-provisioned VMs ready for your project. Each VM has your repositories cloned, environment variables set, and setup commands executed — so when a task starts, it gets a warm VM instantly instead of waiting for provisioning from scratch. This is especially useful for projects with large repos or slow dependency installs (Nix, Docker builds, etc.).

​
Setup workflow

The typical workflow for configuring warm pool via the API:
  1. Configure — Set your setup commands, pool size, and branch via PATCH /warm-pool
  2. Test — Trigger a test boot via POST /warm-pool/test to verify your setup works
  3. Poll — Check the test result via GET /warm-pool/instances/:id until status is ready or failed
  4. Debug — If failed, read summary.failedStep and summary.error to find what broke
  5. Iterate — Adjust setup commands and repeat from step 2
Once your setup commands work reliably, enable the pool and it will maintain your target number of warm VMs automatically.

​
Quick start

​
1. Get your project ID

curl -H "Authorization: Bearer capy_xxxx" \
  https://capy.ai/api/v1/projects
Find your project in the response and copy its id.

​
2. Configure warm pool

curl -X PATCH \
  -H "Authorization: Bearer capy_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "targetSize": 3,
    "branch": "main",
    "setupCommands": [
      {"name": "install", "command": "cd /home/myrepo && npm install"},
      {"name": "build", "command": "cd /home/myrepo && npm run build"}
    ]
  }' \
  https://capy.ai/api/v1/projects/{projectId}/warm-pool
Setup commands run from /home after repos are cloned. Your repo is available at /home/<repo-name> (e.g., /home/myrepo for org/myrepo).

​
3. Trigger a test boot

curl -X POST \
  -H "Authorization: Bearer capy_xxxx" \
  -H "Content-Type: application/json" \
  -d '{}' \
  https://capy.ai/api/v1/projects/{projectId}/warm-pool/test
Response: 
{ "id": "abc-123-def" }
You can pass setupCommands in the test boot body to save new commands and boot in one call — useful for tight iteration loops.

​
4. Poll for results

curl -H "Authorization: Bearer capy_xxxx" \
  https://capy.ai/api/v1/projects/{projectId}/warm-pool/instances/abc-123-def
Poll until status is ready (success) or failed. We recommend polling every 3–5 seconds. Success response: 
{
  "status": "ready",
  "summary": {
    "success": true,
    "totalDurationMs": 45000,
    "failedStep": null,
    "error": null,
    "completedSteps": 6,
    "totalSteps": 6
  },
  "steps": [...]
}
Failure response: 
{
  "status": "failed",
  "summary": {
    "success": false,
    "failedStep": "warm_pool_setup",
    "error": "exit code 1: npm ERR! Could not resolve dependency...",
    "completedSteps": 4,
    "totalSteps": 5
  },
  "steps": [...]
}
The summary object gives you the answer at a glance:
  • summary.success — did the boot complete successfully?
  • summary.failedStep — which provisioning step failed (e.g., clone_repo, warm_pool_setup)
  • summary.error — the error message from the failed step
  • steps — full step-by-step log with output, errors, and timing for each step

​
5. Iterate on failures

If the boot failed, adjust your setup commands and test again: 
curl -X POST \
  -H "Authorization: Bearer capy_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "setupCommands": [
      {"name": "install", "command": "cd /home/myrepo && npm ci --ignore-scripts"}
    ]
  }' \
  https://capy.ai/api/v1/projects/{projectId}/warm-pool/test
Test VMs are automatically deleted after 15 minutes.

​
Provisioning steps

Each warm pool boot runs these steps in order:
StepDescription
create_vmProvisions a fresh VM
ensure_serverWaits for the VM server to be ready
set_env_varsWrites project environment variables to /home/.env
clone_repoClones each repo (runs once per repo)
init_repoInitializes each repo (runs hooks from .capy/settings.json)
project_setupRuns project-level setup commands from devbox settings
repo_setupRuns per-repo setup commands from devbox settings
warm_pool_setupRuns setup commands configured via this API
If any step fails, provisioning stops and the instance is marked failed.
VMs run as root with full sudo access. Setup commands can install system packages, modify system configs, and perform any root-level operations.

​
Managing the pool

​
Check pool status

curl -H "Authorization: Bearer capy_xxxx" \
  https://capy.ai/api/v1/projects/{projectId}/warm-pool
The status object shows how many VMs are ready, provisioning, or failed.

​
Clear and rebuild

If VMs have gone stale or you’ve changed your setup: 
curl -X POST \
  -H "Authorization: Bearer capy_xxxx" \
  -H "Content-Type: application/json" \
  -d '{"replenish": true}' \
  https://capy.ai/api/v1/projects/{projectId}/warm-pool/clear
This deletes all active VMs and immediately starts provisioning fresh ones.