API Reference

Containers

API reference for Docker containers - deploying, changing, redeploying and removing containers, any container or image on a server, and Docker itself.

Last updated

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.

MethodPathDescription
GET/api/v1/containers/serversList servers with Docker
GET/api/v1/containersList containers
POST/api/v1/containersDeploy a container
GET/api/v1/containers/:idGet a container
PATCH/api/v1/containers/:idChange a container
DELETE/api/v1/containers/:idRemove a container
GET/api/v1/containers/:id/environmentGet environment variables
POST/api/v1/containers/:id/redeployRedeploy a container
POST/api/v1/containers/:id/:actionStart, stop or restart a container
POST/api/v1/containers/servers/:serverId/docker/statusRead Docker's state
POST/api/v1/containers/servers/:serverId/docker/installInstall or start Docker
POST/api/v1/containers/servers/:serverId/containers/listList every container on a server
POST/api/v1/containers/servers/:serverId/containers/:ref/logsRead a container's logs
POST/api/v1/containers/servers/:serverId/containers/:ref/inspectInspect a container
POST/api/v1/containers/servers/:serverId/containers/:ref/:actionAct on any container
POST/api/v1/containers/servers/:serverId/containers/:ref/removeRemove any container
POST/api/v1/containers/servers/:serverId/images/listList images
POST/api/v1/containers/servers/:serverId/images/pullPull an image
POST/api/v1/containers/servers/:serverId/images/removeRemove 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:

StatusCodeWhen
404NOT_FOUNDNo container or server with this id.
409SERVER_NOT_READYThe server has no connected agent yet.
409AGENT_OUTDATEDThe server's agent is older than 0.10.0.
409DOCKER_NOT_INSTALLED, DOCKER_NOT_RUNNINGDocker is missing or stopped on the server (deploying, changing, pulling and removing images).
409CONTAINER_BUSYA deployment or removal of this container is still running (details.jobId).
409PROTECTED_CONTAINERThe container runs VaultPanel's own database or Redis; it cannot be stopped, restarted or removed from the panel.
409DUPLICATE_OPERATIONThe same job is already queued or running (details.jobId).

The container object

FieldTypeDescription
id, serverId, serverNamestringThe container record and its server.
namestring3 to 32 lowercase letters, digits and dashes, starting with a letter. Containers on the vaultpanel Docker network reach each other by name.
imagestringSuch as nginx:1.27, ghcr.io/owner/app:latest or redis.
portsobject[]{ address, hostPort, containerPort, protocol }.
volumesobject[]{ volume, path, readOnly }: a named Docker volume mounted at a path.
restartPolicystringunless-stopped, always, on-failure or no.
memoryMb, cpuPercentinteger or nullLimits; cpuPercent 100 is one core.
commandstring or nullThe command run instead of the image's own.
healthCheckSecondsintegerHow long a new container must stay up.
envKeysstring[]Variable names only. Values: Get environment variables.
statusstringdeploying, active, failed (first deployment failed) or removing.
state, stateDetail, stateCheckedAtWhat Docker last reported: running, exited…
dockerId, deployedAtDocker's id for the container, and when it was last deployed.
pendingobject or nullThe image and settings being deployed.
lastJobId, lastErrorThe last job, and { code, message } of the last failure.

List servers with Docker

GET/api/v1/containers/servers
Auth
Session cookie (+ CSRF token) or API token
Permission
containers.read
Token scope
read

Returns 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

GET/api/v1/containers
Auth
Session cookie (+ CSRF token) or API token
Permission
containers.read
Token scope
read

Returns the containers VaultPanel deployed, a page at a time.

Query parameters

NameTypeRequiredDescription
serverIdstring (UUID)NoOnly containers on this server.
searchstringNoPart of the name, up to 100 characters.
page, pageSizeintegerNoPage from 1; 1 to 100 per page (default 25).
sort, orderstringNoname (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

POST/api/v1/containers
Auth
Session cookie (+ CSRF token) or API token
Permission
containers.manage
Token scope
manage

Deploys 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

FieldTypeRequiredDescription
serverIdstring (UUID)YesThe server.
namestringYes3 to 32 lowercase letters, digits and dashes, starting with a letter. Unique on the server.
imagestringYesImage reference, up to 255 characters.
portsobject[]NoUp 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.
volumesobject[]NoUp to 10 { volume, path, readOnly }. volume is lowercase letters, digits and dashes; path an absolute path inside the container.
envobject[]NoUp to 100 { key, value }. Keys: letters, digits and underscores, not starting with a digit. Values up to 8192 characters.
restartPolicystringNounless-stopped (default), always, on-failure or no.
memoryMbinteger or nullNo32 to 262144.
cpuPercentinteger or nullNo5 to 6400 (100 is one core).
commandstring or nullNoOne line, up to 1000 characters, split into arguments like a shell would but never run through one. Empty uses the image's command.
healthCheckSecondsintegerNo3 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

GET/api/v1/containers/:id
Auth
Session cookie (+ CSRF token) or API token
Permission
containers.read
Token scope
read

Returns 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

PATCH/api/v1/containers/:id
Auth
Session cookie (+ CSRF token) or API token
Permission
containers.manage
Token scope
manage

Changes 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 fieldTypeDescription
pullbooleanPull 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

DELETE/api/v1/containers/:id
Auth
Session cookie (+ CSRF token) or API token
Permission
containers.manage
Token scope
manage

Removes the container and its record (CONTAINER_REMOVE).

Query parameters

NameTypeRequiredDescription
removeVolumesbooleanNoAlso 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

GET/api/v1/containers/:id/environment
Auth
Session cookie (+ CSRF token) or API token
Permission
containers.manage
Token scope
manage

Returns 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

POST/api/v1/containers/:id/redeploy
Auth
Session cookie (+ CSRF token) or API token
Permission
containers.manage
Token scope
manage

Recreates 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

FieldTypeRequiredDescription
pullbooleanNoPull 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

POST/api/v1/containers/:id/:action
Auth
Session cookie (+ CSRF token) or API token
Permission
containers.operate
Token scope
deploy

: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

POST/api/v1/containers/servers/:serverId/docker/status
Auth
Session cookie (+ CSRF token) or API token
Permission
containers.read
Token scope
read

Queues 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

POST/api/v1/containers/servers/:serverId/docker/install
Auth
Session cookie (+ CSRF token) or API token
Permission
containers.manage
Token scope
manage

Queues 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

POST/api/v1/containers/servers/:serverId/containers/list
Auth
Session cookie (+ CSRF token) or API token
Permission
containers.read
Token scope
read

Queues 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

POST/api/v1/containers/servers/:serverId/containers/:ref/logs
Auth
Session cookie (+ CSRF token) or API token
Permission
containers.logs
Token scope
logs

Queues a CONTAINER_LOGS job with the container's last lines of output.

Request body

FieldTypeRequiredDescription
linesintegerNo10 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

POST/api/v1/containers/servers/:serverId/containers/:ref/inspect
Auth
Session cookie (+ CSRF token) or API token
Permission
containers.read
Token scope
read

Queues 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

POST/api/v1/containers/servers/:serverId/containers/:ref/:action
Auth
Session cookie (+ CSRF token) or API token
Permission
containers.operate
Token scope
deploy

Starts, 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

POST/api/v1/containers/servers/:serverId/containers/:ref/remove
Auth
Session cookie (+ CSRF token) or API token
Permission
containers.manage
Token scope
manage

Removes 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

POST/api/v1/containers/servers/:serverId/images/list
Auth
Session cookie (+ CSRF token) or API token
Permission
containers.read
Token scope
read

Queues 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

POST/api/v1/containers/servers/:serverId/images/pull
Auth
Session cookie (+ CSRF token) or API token
Permission
containers.manage
Token scope
manage

Queues an IMAGE_PULL job.

Request body

FieldTypeRequiredDescription
imagestringYesImage 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

POST/api/v1/containers/servers/:serverId/images/remove
Auth
Session cookie (+ CSRF token) or API token
Permission
containers.manage
Token scope
manage

Queues an IMAGE_REMOVE job.

Request body

FieldTypeRequiredDescription
imageIdstringYesThe 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.