Built to be driven by code.
One lifecycle, many ways in. Use the API from your agent harness, the SDKs from your app, the CLI from your terminal, or SSH from anywhere.
Pick your interface
All of them sit on the same contract, so you can mix them freely.
- REST API
- Every lifecycle action as one call under https://api.usedock.io/v1, with stable error codes.
- TypeScript SDK
- npm install @usedock/sdk. Typed client generated from the same OpenAPI contract as the API.
- Python SDK
- pip install dock-sdk. Same operations, same contract, versioned in lockstep with the API.
- dock CLI
- For people and shell scripts. Add --json to any command for line-delimited JSON output.
- SSH and SCP
- Plain SSH into any running dock. Your agent harness can treat it like any other Linux box.
Five lines with the SDK
Create a dock, run real work, keep the state.
quickstart.tsTypeScript
1import { Dock } from '@usedock/sdk'2const dock = new Dock()3const d = await dock.docks.create()4await d.commands.run('pnpm test')5await d.archive()
snapshot saved, dock archived
Or from the terminal
The dock CLI covers the lifecycle for people and scripts.
$ dock newCreate a dock and wait until it is ready$ dock sshOpen a shell on a running dock$ dock listList docks in your workspace and their states$ dock stopArchive a dock: snapshot the disk and stop billing$ dock branchStart a new, independent dock from a snapshot--jsonon any command prints one JSON object per line.
Core endpoints
Authenticate with a dock_ service key as a bearer token. Lifecycle calls are async: they return a transitional state you can poll.
| Method | Path | What it does |
|---|---|---|
| POST | /v1/docks | Create a dock |
| GET | /v1/docks | List docks, filtered by state |
| GET | /v1/docks/:id | Read state, size, tier, IP, TTL, and environment |
| POST | /v1/docks/:id/stop | Archive a dock (async, returns 202) |
| POST | /v1/docks/:id/resume | Resume an archived dock under the same ID |
| POST | /v1/docks/:id/branch | Create a new dock from a snapshot |
| GET | /v1/docks/:id/snapshots | List snapshots for a dock |
| GET | /v1/docks/:id/stats | Current usage plus 1h and 24h history |
| GET | /v1/operations/:id | Poll a long-running operation |
| DELETE | /v1/docks/:id | Delete a dock |
| GET | /v1/toolbox | Catalog of tools you can preinstall |
| POST | /v1/webhooks/endpoints | Get lifecycle events pushed to you |
Predictable responses
Every response uses the same envelope. Errors carry a stable snake_case code you can branch on, and create accepts an Idempotency-Key so retries never make a second dock.
// success
{
"ok": true,
"data": { "id": "dk_7f3a91", "state": "provisioning" }
}
// failure
{
"ok": false,
"code": "environment_not_found",
"message": "No environment named staging"
}Want an API key?
Keys are issued with private beta access. Tell us what you are building.