Containers
API reference for Docker containers - deploying, changing, redeploying and removing containers, any container or image on a server, and Docker itself.
The /containers endpoints manage Docker containers from public images. /containers/:id are the containers VaultPanel deployed; /containers/servers/:serverId/... reach every container on a server, VaultPanel's or not, and Docker itself. Changes and reads on a server are jobs for its agent, which talks to Docker's API, never a shell. The server's agent must be 0.10.0 or newer.
Hosting customers have no access (403 FORBIDDEN). For the workflow, see Containers.
| Method | Path | Description |
|---|---|---|
| GET | /api/v1/containers/servers | List servers with Docker |
| GET | /api/v1/containers | List containers |
| POST | /api/v1/containers | Deploy a container |
| GET | /api/v1/containers/:id | Get a container |
| PATCH | /api/v1/containers/:id | Change a container |
| DELETE | /api/v1/containers/:id | Remove a container |
| GET | /api/v1/containers/:id/environment | Get environment variables |
| POST | /api/v1/containers/:id/redeploy | Redeploy a container |
| POST | /api/v1/containers/:id/:action | Start, stop or restart a container |
| POST | /api/v1/containers/servers/:serverId/docker/status | Read Docker's state |
| POST | /api/v1/containers/servers/:serverId/docker/install | Install or start Docker |
| POST | /api/v1/containers/servers/:serverId/containers/list | List every container on a server |
| POST | /api/v1/containers/servers/:serverId/containers/:ref/logs | Read a container's logs |
| POST | /api/v1/containers/servers/:serverId/containers/:ref/inspect | Inspect a container |
| POST | /api/v1/containers/servers/:serverId/containers/:ref/:action | Act on any container |
| POST | /api/v1/containers/servers/:serverId/containers/:ref/remove | Remove any container |
| POST | /api/v1/containers/servers/:serverId/images/list | List images |
| POST | /api/v1/containers/servers/:serverId/images/pull | Pull an image |
| POST | /api/v1/containers/servers/:serverId/images/remove | Remove an image |
How changes work
Deploying or changing a container keeps the change in pending until its CONTAINER_DEPLOY job succeeds. If the new container does not stay up for healthCheckSeconds, the agent puts the old one back, and the record keeps its old settings with lastError. Only one change runs at a time per container.
The server-level requests (everything under /containers/servers/:serverId/) return the queued job with 202 Accepted. When the job succeeds, its output holds the answer: wait for it with GET /api/v1/jobs/:id or panel.jobs.wait().
These errors can come from most endpoints on this page:
| Status | Code | When |
|---|---|---|
| 404 | NOT_FOUND | No container or server with this id. |
| 409 | SERVER_NOT_READY | The server has no connected agent yet. |
| 409 | AGENT_OUTDATED | The server's agent is older than 0.10.0. |
| 409 | DOCKER_NOT_INSTALLED, DOCKER_NOT_RUNNING | Docker is missing or stopped on the server (deploying, changing, pulling and removing images). |
| 409 | CONTAINER_BUSY | A deployment or removal of this container is still running (details.jobId). |
| 409 | PROTECTED_CONTAINER | The container runs VaultPanel's own database or Redis; it cannot be stopped, restarted or removed from the panel. |
| 409 | DUPLICATE_OPERATION | The same job is already queued or running (details.jobId). |
The container object
| Field | Type | Description |
|---|---|---|
id, serverId, serverName | string | The container record and its server. |
name | string | 3 to 32 lowercase letters, digits and dashes, starting with a letter. Containers on the vaultpanel Docker network reach each other by name. |
image | string | Such as nginx:1.27, ghcr.io/owner/app:latest or redis. |
ports | object[] | { address, hostPort, containerPort, protocol }. |
volumes | object[] | { volume, path, readOnly }: a named Docker volume mounted at a path. |
restartPolicy | string | unless-stopped, always, on-failure or no. |
memoryMb, cpuPercent | integer or null | Limits; cpuPercent 100 is one core. |
command | string or null | The command run instead of the image's own. |
healthCheckSeconds | integer | How long a new container must stay up. |
envKeys | string[] | Variable names only. Values: Get environment variables. |
status | string | deploying, active, failed (first deployment failed) or removing. |
state, stateDetail, stateCheckedAt | What Docker last reported: running, exited… | |
dockerId, deployedAt | Docker's id for the container, and when it was last deployed. | |
pending | object or null | The image and settings being deployed. |
lastJobId, lastError | The last job, and { code, message } of the last failure. |
List servers with Docker
/api/v1/containers/serversReturns every server with what its agent last said about Docker, container counts, how many containers VaultPanel deployed there, and whether its agent can manage containers (supported).
Example request
curl https://panel.example.com/api/v1/containers/servers \
-H "Authorization: Bearer $VAULTPANEL_TOKEN"const { items } = await panel.containers.servers();Response 200 OK
{
"success": true,
"data": {
"items": [
{
"id": "9b2e7c1a-0d3f-4e8b-a6c5-7d8e9f0a1b2c",
"name": "web-1",
"status": "online",
"isLocal": true,
"agentVersion": "0.41.0",
"supported": true,
"docker": { "installed": true, "running": true, "source": "package", "service": "docker", "version": "28.1.1" },
"containers": { "total": 4, "running": 4 },
"deployed": 2,
"protectedPorts": [3307, 6379],
"lastSeenAt": "2026-11-10T10:15:02.000Z"
}
]
},
"message": "OK",
"requestId": "…"
}List containers
/api/v1/containersReturns the containers VaultPanel deployed, a page at a time.
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
serverId | string (UUID) | No | Only containers on this server. |
search | string | No | Part of the name, up to 100 characters. |
page, pageSize | integer | No | Page from 1; 1 to 100 per page (default 25). |
sort, order | string | No | name (default) or createdAt; asc (default) or desc. |
Example request
curl "https://panel.example.com/api/v1/containers?serverId=9b2e7c1a-0d3f-4e8b-a6c5-7d8e9f0a1b2c" \
-H "Authorization: Bearer $VAULTPANEL_TOKEN"const { items, pagination } = await panel.containers.list({ serverId });Response 200 OK: { items, pagination } of container objects.
Deploy a container
/api/v1/containersDeploys a new container. Host ports are checked against apps, other containers, SSH, the panel's own port, VaultPanel's database and Redis, and 80 and 443 when NGINX is installed.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
serverId | string (UUID) | Yes | The server. |
name | string | Yes | 3 to 32 lowercase letters, digits and dashes, starting with a letter. Unique on the server. |
image | string | Yes | Image reference, up to 255 characters. |
ports | object[] | No | Up to 10 { address, hostPort, containerPort, protocol }. address is 127.0.0.1 (default, this server only, for a reverse proxy) or 0.0.0.0 (public: Docker opens it even when the firewall has no rule). protocol is tcp (default) or udp. |
volumes | object[] | No | Up to 10 { volume, path, readOnly }. volume is lowercase letters, digits and dashes; path an absolute path inside the container. |
env | object[] | No | Up to 100 { key, value }. Keys: letters, digits and underscores, not starting with a digit. Values up to 8192 characters. |
restartPolicy | string | No | unless-stopped (default), always, on-failure or no. |
memoryMb | integer or null | No | 32 to 262144. |
cpuPercent | integer or null | No | 5 to 6400 (100 is one core). |
command | string or null | No | One line, up to 1000 characters, split into arguments like a shell would but never run through one. Empty uses the image's command. |
healthCheckSeconds | integer | No | 3 to 300. Default 10. |
Example request
curl https://panel.example.com/api/v1/containers \
-X POST \
-H "Authorization: Bearer $VAULTPANEL_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"serverId": "9b2e7c1a-0d3f-4e8b-a6c5-7d8e9f0a1b2c",
"name": "uptime",
"image": "louislam/uptime-kuma:1",
"ports": [{ "address": "127.0.0.1", "hostPort": 3001, "containerPort": 3001 }],
"volumes": [{ "volume": "uptime-data", "path": "/app/data" }],
"memoryMb": 512
}'const { container, job } = await panel.containers.create({
serverId: '9b2e7c1a-0d3f-4e8b-a6c5-7d8e9f0a1b2c',
name: 'uptime',
image: 'louislam/uptime-kuma:1',
ports: [{ address: '127.0.0.1', hostPort: 3001, containerPort: 3001 }],
volumes: [{ volume: 'uptime-data', path: '/app/data' }],
memoryMb: 512,
});
await panel.jobs.wait(job.id);Response 202 Accepted
{
"success": true,
"data": {
"container": {
"id": "6b7c8d9e-…",
"serverId": "9b2e7c1a-0d3f-4e8b-a6c5-7d8e9f0a1b2c",
"name": "uptime",
"image": "louislam/uptime-kuma:1",
"ports": [{ "address": "127.0.0.1", "hostPort": 3001, "containerPort": 3001, "protocol": "tcp" }],
"volumes": [{ "volume": "uptime-data", "path": "/app/data", "readOnly": false }],
"restartPolicy": "unless-stopped",
"memoryMb": 512,
"cpuPercent": null,
"command": null,
"healthCheckSeconds": 10,
"envKeys": [],
"status": "deploying",
"state": null,
"pending": null,
"lastError": null
},
"job": { "id": "…", "type": "CONTAINER_DEPLOY", "status": "queued" }
},
"message": "Deploying the container",
"requestId": "…"
}Errors: those above, and 422 VALIDATION_ERROR for a name already used on the server, a host port already in use or reserved (the error names what uses it), a volume or path used twice, a variable listed twice, or another invalid field.
Get a container
/api/v1/containers/:idReturns one container object.
Example request
curl https://panel.example.com/api/v1/containers/6b7c8d9e-0f1a-4b2c-8d3e-4f5a6b7c8d9e \
-H "Authorization: Bearer $VAULTPANEL_TOKEN"const container = await panel.containers.get(containerId);Response 200 OK: the container.
Change a container
/api/v1/containers/:idChanges the container and deploys a replacement. Every field of Deploy a container except serverId and name may be given; env, when given, replaces every variable. Send at least one field besides pull.
| Extra field | Type | Description |
|---|---|---|
pull | boolean | Pull the image again even when it is already on the server. Default false. |
Example request
curl https://panel.example.com/api/v1/containers/6b7c8d9e-0f1a-4b2c-8d3e-4f5a6b7c8d9e \
-X PATCH \
-H "Authorization: Bearer $VAULTPANEL_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "image": "louislam/uptime-kuma:2", "pull": true }'const { container, job } = await panel.containers.update(containerId, {
image: 'louislam/uptime-kuma:2',
pull: true,
});Response 202 Accepted: { container, job } with the change in pending, message Deploying the change.
Remove a container
/api/v1/containers/:idRemoves the container and its record (CONTAINER_REMOVE).
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
removeVolumes | boolean | No | Also delete its volumes and their data. Default false. |
Example request
curl -X DELETE \
"https://panel.example.com/api/v1/containers/6b7c8d9e-0f1a-4b2c-8d3e-4f5a6b7c8d9e?removeVolumes=true" \
-H "Authorization: Bearer $VAULTPANEL_TOKEN"await panel.containers.remove(containerId, { removeVolumes: true });Response 202 Accepted: { container, job } with status removing, message Removing the container.
Get environment variables
/api/v1/containers/:id/environmentReturns the values of the container's variables. Values are stored encrypted, and every read is recorded in the audit log.
Example request
curl https://panel.example.com/api/v1/containers/6b7c8d9e-0f1a-4b2c-8d3e-4f5a6b7c8d9e/environment \
-H "Authorization: Bearer $VAULTPANEL_TOKEN"const { variables } = await panel.containers.environment(containerId);Response 200 OK
{
"success": true,
"data": { "variables": [{ "key": "TZ", "value": "Europe/Berlin" }] },
"message": "OK",
"requestId": "…"
}Redeploy a container
/api/v1/containers/:id/redeployRecreates the container with the same settings, pulling its image again by default, which picks up a new build of the same tag. Also retries a failed first deployment.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
pull | boolean | No | Pull the image first. Default true. |
Example request
curl https://panel.example.com/api/v1/containers/6b7c8d9e-0f1a-4b2c-8d3e-4f5a6b7c8d9e/redeploy \
-X POST \
-H "Authorization: Bearer $VAULTPANEL_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "pull": true }'const { job } = await panel.containers.redeploy(containerId, { pull: true });Response 202 Accepted: { container, job }, message Redeploying the container.
Start, stop or restart a container
/api/v1/containers/:id/:action:action is start, stop or restart. Returns the queued job (CONTAINER_START, CONTAINER_STOP or CONTAINER_RESTART).
Example request
curl https://panel.example.com/api/v1/containers/6b7c8d9e-0f1a-4b2c-8d3e-4f5a6b7c8d9e/restart \
-X POST \
-H "Authorization: Bearer $VAULTPANEL_TOKEN"const job = await panel.containers.restart(containerId);Response 202 Accepted: the job, message Starting the container, Stopping the container or Restarting the container.
Read Docker's state
/api/v1/containers/servers/:serverId/docker/statusQueues a DOCKER_STATUS job that reads whether Docker is installed and running on the server, and its version.
Example request
curl https://panel.example.com/api/v1/containers/servers/9b2e7c1a-0d3f-4e8b-a6c5-7d8e9f0a1b2c/docker/status \
-X POST \
-H "Authorization: Bearer $VAULTPANEL_TOKEN"const job = await panel.containers.onServer.docker(serverId);
const done = await panel.jobs.wait(job.id);
console.log(done.output);Response 202 Accepted: the job, message Reading Docker’s status.
Install or start Docker
/api/v1/containers/servers/:serverId/docker/installQueues a DOCKER_INSTALL job that installs Docker, or starts it when it is installed but stopped.
Example request
curl https://panel.example.com/api/v1/containers/servers/9b2e7c1a-0d3f-4e8b-a6c5-7d8e9f0a1b2c/docker/install \
-X POST \
-H "Authorization: Bearer $VAULTPANEL_TOKEN"const job = await panel.containers.onServer.installDocker(serverId);Response 202 Accepted: the job, message Installing or starting Docker.
List every container on a server
/api/v1/containers/servers/:serverId/containers/listQueues a CONTAINER_LIST job: every container Docker runs on the server, whether VaultPanel deployed it or not, in the job's output.
Example request
curl https://panel.example.com/api/v1/containers/servers/9b2e7c1a-0d3f-4e8b-a6c5-7d8e9f0a1b2c/containers/list \
-X POST \
-H "Authorization: Bearer $VAULTPANEL_TOKEN"const job = await panel.containers.onServer.list(serverId);
const { output } = await panel.jobs.wait(job.id);Response 202 Accepted: the job, message Listing containers.
In the following server-level endpoints, :ref is a container's Docker ID (12 to 64 hexadecimal characters) or its name.
Read a container's logs
/api/v1/containers/servers/:serverId/containers/:ref/logsQueues a CONTAINER_LOGS job with the container's last lines of output.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
lines | integer | No | 10 to 2000. Default 200. |
Example request
curl https://panel.example.com/api/v1/containers/servers/9b2e7c1a-0d3f-4e8b-a6c5-7d8e9f0a1b2c/containers/uptime/logs \
-X POST \
-H "Authorization: Bearer $VAULTPANEL_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "lines": 500 }'const job = await panel.containers.onServer.logs(serverId, 'uptime', { lines: 500 });
const { output } = await panel.jobs.wait(job.id);Response 202 Accepted: the job, message Reading the logs.
Inspect a container
/api/v1/containers/servers/:serverId/containers/:ref/inspectQueues a CONTAINER_INSPECT job with the container's configuration and state in its output.
Example request
curl https://panel.example.com/api/v1/containers/servers/9b2e7c1a-0d3f-4e8b-a6c5-7d8e9f0a1b2c/containers/uptime/inspect \
-X POST \
-H "Authorization: Bearer $VAULTPANEL_TOKEN"const job = await panel.containers.onServer.inspect(serverId, 'uptime');Response 202 Accepted: the job, message Reading the container.
Act on any container
/api/v1/containers/servers/:serverId/containers/:ref/:actionStarts, stops or restarts any container on the server. :action is start, stop or restart. VaultPanel's own database and Redis containers cannot be stopped or restarted.
Example request
curl https://panel.example.com/api/v1/containers/servers/9b2e7c1a-0d3f-4e8b-a6c5-7d8e9f0a1b2c/containers/3f2a1b0c9d8e/stop \
-X POST \
-H "Authorization: Bearer $VAULTPANEL_TOKEN"const job = await panel.containers.onServer.act(serverId, '3f2a1b0c9d8e', 'stop');Response 202 Accepted: the job.
Remove any container
/api/v1/containers/servers/:serverId/containers/:ref/removeRemoves any container on the server. Removing a container VaultPanel deployed removes its record too, keeping its volumes. VaultPanel's own database and Redis containers cannot be removed.
Example request
curl https://panel.example.com/api/v1/containers/servers/9b2e7c1a-0d3f-4e8b-a6c5-7d8e9f0a1b2c/containers/3f2a1b0c9d8e/remove \
-X POST \
-H "Authorization: Bearer $VAULTPANEL_TOKEN"const job = await panel.request('POST', `/containers/servers/${serverId}/containers/3f2a1b0c9d8e/remove`);Response 202 Accepted: the job, message Removing the container.
List images
/api/v1/containers/servers/:serverId/images/listQueues an IMAGE_LIST job with the server's images in its output.
Example request
curl https://panel.example.com/api/v1/containers/servers/9b2e7c1a-0d3f-4e8b-a6c5-7d8e9f0a1b2c/images/list \
-X POST \
-H "Authorization: Bearer $VAULTPANEL_TOKEN"const job = await panel.containers.onServer.images(serverId);Response 202 Accepted: the job, message Listing images.
Pull an image
/api/v1/containers/servers/:serverId/images/pullQueues an IMAGE_PULL job.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
image | string | Yes | Image reference, such as nginx:1.27. |
Example request
curl https://panel.example.com/api/v1/containers/servers/9b2e7c1a-0d3f-4e8b-a6c5-7d8e9f0a1b2c/images/pull \
-X POST \
-H "Authorization: Bearer $VAULTPANEL_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "image": "nginx:1.27" }'const job = await panel.containers.onServer.pullImage(serverId, { image: 'nginx:1.27' });Response 202 Accepted: the job, message Pulling the image.
Remove an image
/api/v1/containers/servers/:serverId/images/removeQueues an IMAGE_REMOVE job.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
imageId | string | Yes | The full image id: sha256: and 64 hexadecimal characters. |
Example request
curl https://panel.example.com/api/v1/containers/servers/9b2e7c1a-0d3f-4e8b-a6c5-7d8e9f0a1b2c/images/remove \
-X POST \
-H "Authorization: Bearer $VAULTPANEL_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "imageId": "sha256:3b25b682ea82b2db3cc4fd48db818be788ee3f902ac7378090cf2624ec2442df" }'const job = await panel.request('POST', `/containers/servers/${serverId}/images/remove`, {
body: { imageId: 'sha256:3b25b682ea82b2db3cc4fd48db818be788ee3f902ac7378090cf2624ec2442df' },
});Response 202 Accepted: the job, message Removing the image.