---
title: "Create a runtime pool"
method: POST
path: "/api/runtime-pools"
tags: ["Runtime pools"]
---

# Create a runtime pool

`POST /api/runtime-pools`

## Request

- Base URL: `http://localhost:3013`
- URL: `http://localhost:3013/api/runtime-pools`
- Auth: HTTP bearer

## Request body

- object
  - `name` string, required
  - `kind` 'static' | 'docker' | 'e2b' | 'boxd' | 'k8s', required
  - `placements` string[], required
  - `image` string, nullable
  - `lifecycle` 'idle' | 'per-task'
  - `idleMinutes` integer, nullable
  - `slotsPerRuntime` integer
  - `maxRuntimes` integer, nullable
  - `minRuntimes` integer
  - `delivery` 'poll' | 'push' | 'null', nullable
  - `env` object
  - `resources` object, nullable
    - `cpu` number
    - `memoryMb` integer
  - `cache` object, nullable
    - `mountPath` string, required
  - `ttlSec` integer, nullable
  - `enabled` boolean

## Response `200`

Success

- object
  - `pool` RuntimePool, required
    - `name` string, required
    - `kind` 'static' | 'docker' | 'e2b' | 'boxd' | 'k8s', required
    - `placements` string[], required
    - `image` string, nullable
    - `lifecycle` 'idle' | 'per-task'
    - `idleMinutes` integer, nullable
    - `slotsPerRuntime` integer
    - `maxRuntimes` integer, nullable
    - `minRuntimes` integer
    - `delivery` 'poll' | 'push' | 'null', nullable
    - `env` object
    - `resources` object, nullable
      - `cpu` number
      - `memoryMb` integer
    - `cache` object, nullable
      - `mountPath` string, required
    - `ttlSec` integer, nullable
    - `enabled` boolean
    - `id` string, required
    - `resolvedImage` string, nullable, required
    - `consecutiveFailures` integer, required
    - `circuitOpenUntil` string, nullable, required
    - `lastError` string, nullable, required
    - `lastErrorAt` string, nullable, required
    - `createdBy` string, nullable, required
    - `updatedBy` string, nullable, required
    - `createdAt` string, required
    - `updatedAt` string, required
  - `warning` string

## Other responses

- `400`: Invalid configuration
- `403`: Permission denied
- `404`: Not found or runtime pools disabled
- `409`: Entity is in use or already exists

## Changes

- **2026-10-30** `2726b97e6ecb`: 2 info
  - added the new optional request property `cache`
  - added the optional property `pool/cache` to the response with the `200` status
- **2026-10-29** `03ff25ddf270`: 1 warning, 1 info
  - added the new `boxd` enum value to the `pool/kind` response property for the response status `200`
  - added the new `boxd` enum value to the request property `kind`
- **2026-10-12** `2d005144fe35`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/desplega-ai/apis/agent-swarm-api/changes/api/runtime-pools/post.md)

---

[API](https://skmtc.dev/desplega-ai/apis/agent-swarm-api.md) - [All operations](https://skmtc.dev/desplega-ai/apis/agent-swarm-api/llms.txt) - [OpenAPI document](https://skmtc.dev/desplega-ai/apis/agent-swarm-api/revisions/7e4c7198192a?raw)