Skip to content

REST API ​

The agent serves a JSON REST API. shipwick and the dashboard are clients of it and have no private channel: anything they do can be done with curl. This page covers authentication and roles, the envelopes, error codes, every endpoint (applications and deployments, backups, traffic, certificates, registries, tokens, the audit trail, signing in and access rules, export, import and the standby, and the Prometheus endpoint), the asynchronous deployment pattern, log streaming, and the types.

Basics ​

Base path/api/v1. The one endpoint outside it is GET /metrics, because that is where a scraper looks.
Default addresshttp://127.0.0.1:9000, or https://<SHIPWICK_AGENT_DOMAIN> when served through Caddy
FormatJSON in responses. Request bodies are JSON, except for deploy and validate, which take the deploy.yaml document, the volume restore, the static upload and the image upload, which take a tar archive, and the import, which takes an export.
TimestampsRFC 3339, UTC

Every response carries Cache-Control: no-store and X-Content-Type-Options: nosniff. JSON responses have Content-Type: application/json; charset=utf-8.

The API speaks plain HTTP. See Security for how to expose it.

Authentication ​

Every endpoint except GET /api/v1/health, GET /api/v1/auth and POST /api/v1/auth/exchange requires an API token as a bearer token:

http
Authorization: Bearer <token>

A missing, wrong or revoked token is answered with 401 UNAUTHORIZED and the header WWW-Authenticate: Bearer realm="shipwick".

Guessing is slowed down. After 20 failed authentications within a minute from one client address, its further wrong tokens are answered 429 RATE_LIMITED for the next minute, with a Retry-After header in seconds. A valid token is never refused: behind the proxy every client shares one address, and a guesser must not be able to lock anyone else out. Only failures count, so a mistyped token does not reach the limit, and GET /health is not limited.

The API answers the proxy, the dashboard and the server itself. Since 0.8 a request that comes from the container of an application is 403 APPLICATION_CALLER on every endpoint, GET /health included, whatever token it carries. The token is not looked at, and the request is not counted as a failed authentication:

json
{
  "error": {
    "code": "APPLICATION_CALLER",
    "message": "the API answers the proxy, the dashboard and the server itself, not the containers of applications; from a container, call it at its hostname",
    "details": {}
  }
}

Which requests those are depends on how the agent is installed. With the control network, shipwick-control, they are the requests from every address that is not of that network. Without it, they are the requests from the addresses of the containers the agent manages, and GET /server then carries open_to_applications: true: only the token keeps anything else on the applications' network out. A request that reaches the API through the proxy, at the API's hostname, comes from the proxy and is answered like any other; that is how an application that calls the API on purpose does it. See Who can reach the API.

A token has a role, and every endpoint requires one. A role includes the ones below it:

RoleMay
readSee everything: GET /server, /applications…, /deployments…, logs, the log archive and its search, events, metrics, traffic and requests, volumes, the list of backups, jobs and runs, the names of the secrets, the registries that have a credential, the supplied certificates, the volumes on the server, what a standby holds (/standby and /standby/promotion), and GET /metrics
deployAnd change what runs: deploy, validate, redeploy, rollback, stop, start, run a job or a one-off command, upload an image or a static folder, take a backup and verify one; since 0.7 POST /applications and POST /validate, which take a document that names its application, and GET /applications/:name/config, the document of what runs
adminAnd everything else: DELETE /applications/:name, the volume archives, restoring, downloading and removing a backup, removing a volume, the /tokens endpoints, setting and removing /secrets, /registries and /certificates, POST /server/rotate-key, the backups of the agent's own state, adopting backups, export, import, pulling and promoting a standby, GET /audit, GET /audit/export, and the /access endpoints

A deploy token may be limited to applications. It then has the deploy row for the applications it names and the read row for everything. An endpoint of the deploy row is under /applications/:name, and :name is what is checked, also when a deploy would create the application; or, since 0.7, it takes a deploy.yaml as its body (POST /applications, POST /validate), and the name in that document is what is checked, before anything else of the document is read. For another application the answer is 403 TOKEN_LIMITED:

json
{
  "error": {
    "code": "TOKEN_LIMITED",
    "message": "this token is limited to my-api and web; it can read worker and not change it",
    "details": { "applications": ["my-api", "web"], "application": "worker" }
  }
}

An endpoint that takes deploy and is not about one application is refused to a limited token in the same way, without application in the details; there is none today. So is a document without a name that can be read — not YAML, no name, not a valid name — with a message that ends in and the document does not name an application; a token that is not limited gets the 400 INVALID_CONFIG of the document instead. The role is judged first: what takes admin is 403 FORBIDDEN for a limited token as for any other deploy token. read and admin tokens cannot be limited.

There are two kinds of token. The root token is the one the agent is configured with: SHIPWICK_AGENT_TOKEN, or the one generated on first start. It has the admin role and the name root, is not stored in the database and cannot be revoked through the API. Every other token is created with POST /tokens, named, given a role, optionally a list of applications and a time at which it expires, and shown exactly once. Since 0.7 its applications and its expiry can be changed with PUT /tokens/:name; its role and its value cannot.

The agent holds only the SHA-256 hash of each token. The presented token is hashed, the root token's hash is compared in constant time, and a stored token is found by its hash and compared in constant time as well, so neither a token's content nor its length leaks through timing. Each use of a stored token is recorded, to the minute, as its last_used_at.

A valid token whose role does not cover the endpoint is 403 FORBIDDEN, and details says which role it has and which the endpoint wants:

json
{
  "error": {
    "code": "FORBIDDEN",
    "message": "this token has the read role; deploying needs deploy or admin",
    "details": { "role": "read", "required": "deploy" }
  }
}

For an endpoint that needs admin, the message ends in this needs admin.

A token past its expires_at is 401 TOKEN_EXPIRED:

json
{
  "error": {
    "code": "TOKEN_EXPIRED",
    "message": "token ci expired on 2026-10-02 at 12:00 UTC; an admin creates a new one with: shipwick token create",
    "details": { "name": "ci", "expired_at": "2026-10-02T12:00:00Z" }
  }
}

Only the token itself gets this answer, so it tells nothing to anyone who does not hold it; a wrong token is 401 UNAUTHORIZED whatever else exists. An expired token does not count towards the rate limit and is never answered 429. The root token does not expire.

GET /server tells a client who it is and what it may do:

json
"token": { "name": "ci", "role": "deploy", "kind": "token",
           "applications": ["my-api"], "expires_at": "2027-01-01T00:00:00Z" }

kind is "token", or "user" for a person who signed in: name is then the person's name — the e-mail address, or what the agent names people by — and what follows is said of the session. applications is the list a token is limited to, and empty for one that is not limited; expires_at is null for one that does not expire. From these a client knows what to offer: what takes deploy on an application is allowed when role is admin, or when role is deploy and applications is empty or names that application. An agent before 0.6 sends name and role only.

Next to it, "sign_in": {"configured": true, "issuer": "https://accounts.example.com", "name_claim": "email"} says whether people can sign in at all; an agent before 0.6 leaves it out. name_claim is the ID token claim people are named by, "" without a provider; an agent before 0.7 leaves it out, and names people by email. With an OpenID Connect provider configured on the agent, a person signs in at the provider and the agent issues a session: a credential that is presented exactly like a token, Authorization: Bearer sws_…, and is the same kind of caller, with a role, optionally a list of applications, and an expires_at. Everything in this section holds for it: the role table, the application limit, GET /server → token, the audit trail. A session that is refused for its role or its limit gets the same codes as a token, FORBIDDEN and TOKEN_LIMITED, with "this session" in the message. Tokens are not affected by sign-in. See POST /auth/exchange.

See Agent configuration, Create tokens for CI and teammates and Sign in with your company's accounts.

Envelopes ​

Success:

json
{ "data": … }

Failure. details is always an object, empty when there is nothing to add:

json
{
  "error": {
    "code": "INVALID_CONFIG",
    "message": "invalid deploy.yaml",
    "details": {
      "fields": [
        { "field": "resources.memory", "message": "invalid value \"abc\"", "expected": "128mb, 512mb, 1gb, ..." }
      ]
    }
  }
}

Six kinds of response have no envelope: 204 No Content from DELETE, from the volume restore and from setting a secret or a registry credential; the NDJSON stream of followed logs; a tar archive, which is the body of GET and PUT …/volumes/:volume/archive both ways and of a backup's archive; the export that POST /export streams; the CSV or NDJSON that GET /audit/export streams; and the Prometheus text of GET /metrics. Errors are the JSON envelope everywhere.

Error codes ​

HTTPcodeMeaning
400INVALID_REQUESTMalformed application name, volume name, job name, deployment or run id, or query parameter; the name in the document differs from the name in the URL; an invalid JSON body, or an unknown field in it; an invalid image in a redeploy or rollback request; a missing or invalid command in a run request, or a name or role in a token request, applications on a token that is not a deploy token, or an expires_at that has passed; an access rule whose kind, subject, role or applications breaks the rules, or a 201st rule; a sign-in request with a missing or malformed field, or a redirect_uri that is not the configured one; DELETE /auth/session sent with a token; an invalid since, before, actor_kind, action or outcome of the audit trail, more than 20 actions, an export of it without format or with limit or before; a token update that names nothing to change, names both expires_at and never_expires, or is asked of root; a search of the logs whose q is longer than 256 bytes or has a line break, whose times are not RFC 3339, whose until is before its since, or whose cursor no answer returned; a restore body that is not Content-Type: application/x-tar or does not start with a tar header; an image archive that is not sent as application/x-tar, or that does not carry exactly one image tagged shipwick.local/<name>:<tag>; a deploy.yaml with build but no image, or a redeploy of such an application with an image from elsewhere; a static upload that is not application/x-tar, holds no files, or holds anything but files and directories; a static deploy without ?static=, or ?static= on a container application; since 0.8 a field of ?plain= that is not env.<NAME> with a variable the document sets; a secret's name or value that breaks the rules, or a 501st secret; a volume name that is not shipwick_<application>_<volume>; revoking root; a backup or export id that is not a positive number; a layers list that is empty, longer than 256 or holds anything but diff IDs; a registry name with a scheme or a path, a username or password that breaks the rules, or a 51st registry; a certificate's hostname that is not one, a missing or oversized certificate or key, or a 51st certificate; an export passphrase shorter than 12 characters; an import that is not sent as application/octet-stream or carries no passphrase header; a key rotation asked of an agent that has no encryption key.
400INVALID_CONFIGdeploy.yaml failed validation. details.fields lists every problem as {field, message, expected}; expected is omitted when there is nothing to suggest. Also returned when a hostname is already served by another application (as its domain, an alias or a redirect), by the agent or by the dashboard: one entry whose field names the offending line, domain, aliases[0], redirects[1], and whose message names the owner. And with the field publish[i].host when a server port the configuration publishes is already published by another application, or is one the agent or the proxy listens on. Returned by redeploy and rollback too, since a stored configuration's hostnames and ports may have been taken since. Also when an env value refers to a ${NAME} that is not among the stored secrets: one entry per reference, field env.<VARIABLE>, expected the command that stores it; the same for a password of proxy.basic_auth, under the field proxy.basic_auth[i].password. When two applications want the same path of a hostname, the field is path, or domain or aliases[i] for an application that names no path. And for a wildcard hostname (*.example.com as domain or an alias) that no certificate can be had for: the agent has no DNS challenge configured and no supplied certificate covers it; expected says both ways out. Since 0.7 also for a document that holds "********", the mask, as an env value or a basic-auth password: one entry per field, see GET /applications/:name/config; and, from POST /applications and POST /validate, for a document whose name cannot be read, with the field name. Since 0.8 also for what the security block refuses.
400REGISTRY_LOGIN_FAILEDA registry did not accept the credential of a PUT /registries/:registry, or could not be asked; details: {registry, refused}. Nothing was stored.
400INVALID_CERTIFICATEThe certificate or key in a PUT /certificates/:hostname cannot serve that hostname; message is a sentence that says why.
400INVALID_EXPORTThe body of an import is not an export, its passphrase does not match, it breaks off, or, since 0.9, it uses a key of the configuration this agent does not know; the message then names the key and the version that wrote the export, and nothing was taken in.
401UNAUTHORIZEDMissing, wrong or revoked token.
401TOKEN_EXPIREDThe token is a real one, past its expires_at; details: {name, expired_at}.
401SESSION_EXPIREDThe session of a person who signed in is past its ten hours; details: {name, expired_at}.
401SESSION_ENDEDThe session was ended before its time: its rule was removed or changed, an admin signed the person out, or, since 0.7, the agent names people by another claim or no longer accepts the tenant the session came from; details: {name, reason}. See POST /auth/exchange.
401SIGN_IN_FAILEDA sign-in the provider or the ID token did not carry; details: {reason}.
403FORBIDDENThe token's role does not cover this endpoint. details is {role, required}.
403TOKEN_LIMITEDThe role would do, and the token is limited to other applications; details: {applications}, and application when the request was about one.
403ACCESS_NOT_GRANTEDA person signed in whom no access rule gives a role; details: {name, email}, both the person's name: name since 0.7, email kept for older clients.
403APPLICATION_CALLERSince 0.8. The request came from the container of an application; the API answers the proxy, the dashboard and the server itself. Answered without checking the token, see Authentication.
404NOT_FOUNDUnknown application, deployment, volume, job, run, token, secret, backup or export, or an entry of the log archive that does not exist, belongs to another application or has aged out, including a rollback's deployment_id that does not exist; a deploy whose ?static= digest names no upload the agent has; a registry or a hostname nothing is stored for; latest when the application has no successful backup; GET /import when the server has run no import; GET /standby/promotion on a server that was never promoted; a standby pull when the bucket holds no export.
404ENDPOINT_NOT_FOUNDThe agent has no such operation: an older agent, a typo in the path, or a method the path does not support. There is no 405. Answered without checking the token.
409DEPLOYMENT_IN_PROGRESSAnother operation holds this application.
409NOT_DEPLOYEDThe application has no active deployment to act on.
409NO_ROLLBACK_TARGETThere is no earlier successful deployment; or the requested one is the active one, never succeeded, or belongs to another application.
409TOKEN_EXISTSA token with that name exists.
409APPLICATION_RUNNINGA volume restore was asked of an application that is not stopped.
409JOB_ALREADY_RUNNINGA run of this job has not finished yet; a job runs one at a time.
409STATIC_APPLICATIONLogs, metrics, jobs or a one-off command were asked of an application the proxy serves from a folder; it has no containers.
409IMAGE_INCOMPLETEAn image archive left out layers the server does not have; nothing was loaded. Send the whole archive.
409VOLUME_IN_USEThe volume belongs to an application that still exists; details: {application}. Delete the application first, or replace the data with a restore.
409KEY_ROTATION_PENDINGThe encryption key was already rotated since the agent started, and the agent's environment still holds the old one; details: {key_file}.
409TRAFFIC_UNAVAILABLETraffic or requests were asked of an agent that has no access log to read: no proxy, or one that is not the caddy container of its compose project.
409BACKUP_BUSYThe backup is still being taken, verified, restored or removed; or a backup of the agent's state is already running.
409BACKUP_NOT_USABLEA verification, a restore or a download was asked of a backup that failed, so nothing was kept of it; or of one whose files do not decrypt with the agent's passphrase. Also the answer of an agent that was started without anywhere to keep backups.
409NO_VOLUMESA backup was asked of an application without volumes.
409FOREIGN_BUCKETBackups were to be adopted from a bucket that, under the agent's prefix, another installation writes to.
409BACKUPS_NOT_ENCRYPTEDA backup of the agent's state, or an export to where backups go, was asked for and SHIPWICK_BACKUP_PASSPHRASE is not set; or an encrypted backup was asked for and the agent no longer has a passphrase.
409IMPORT_IN_PROGRESSAn import is running; a server takes one at a time.
409EXPORT_IN_PROGRESSAn export to where backups go is being written already.
409STANDBY_NOT_CONFIGUREDAn import from the bucket was asked of an agent that has no bucket to read exports from.
409PROMOTION_IN_PROGRESSA promotion is running: a second one was asked for, or an import. GET /standby/promotion follows the one that runs.
409SIGN_IN_NOT_CONFIGUREDA sign-in was asked of an agent without an OpenID Connect provider.
409CLOUDFLARE_NOT_CONFIGUREDSince 0.9. A check of the Cloudflare token was asked of an agent that has none: SHIPWICK_CLOUDFLARE_API_TOKEN is not set.
429CLOUDFLARE_CHECKED_RECENTLYSince 0.9. The Cloudflare token was checked less than a minute ago, and a check writes a DNS record in every zone; details: {checked_at, retry_after_seconds}, Retry-After the same, and GET /server has the result of that check.
429RATE_LIMITEDA wrong token, after 20 authentications from this address failed within a minute; Retry-After says in how many seconds wrong tokens are answered 401 again. A valid token is never refused.
413INVALID_REQUESTA body over its limit: a deploy body (the deploy.yaml) larger than 64 KB; a redeploy or rollback body larger than 4 KB; a secret, registry, certificate or sign-in body larger than its limit; a volume archive larger than 10 GB; an image archive larger than 4 GB; a static folder larger than 512 MB. The message names the limit. Since 0.10 every body over its limit is 413; before, a redeploy, rollback, secret, registry, certificate or sign-in body over it was 400.
502SIGN_IN_UNAVAILABLEThe sign-in provider could not be reached or used; message says what to change.
503RUNTIME_UNAVAILABLEThe agent is shutting down; or, since 0.8, the Docker daemon does not answer: it is not running, or it took a question about containers and said nothing for 15 seconds. message says which, and for Docker where to look. An agent before 0.8 answers 500 INTERNAL_ERROR for a daemon that is not running, and does not answer at all for one that is silent. See Docker does not answer.
507DISK_FULLSince 0.8. The server's disk has no room for what the request writes: a record in the agent's database, an uploaded folder, an image. Nothing was changed, and the same request succeeds once there is room. An agent before 0.8 answers 500 INTERNAL_ERROR, or 400 INVALID_REQUEST for a folder. See The disk is full.
500INTERNAL_ERRORAnything else. message carries the cause: callers are authenticated operators, and the cause is more useful to them than an opaque message. Error messages never contain environment values.

DEPLOYMENT_IN_PROGRESS is returned at once when another user operation holds the application. When the supervisor holds it, which it does for moments at a time, or a backup that the schedule started, the request waits up to 30 seconds before giving the same answer.

Endpoints ​

Paths are relative to /api/v1. The role is the least a token needs.

MethodPathRole
GET/healthnoneLiveness. No token.
GET/serverreadFacts about the host, the agent, the proxy, the disk, backups, notifications and the network, the active alerts, whether people can sign in, the caller's own token, since 0.7 the log archive and whether a newer release exists, since 0.8 the swap, the applications without a memory limit, how the Docker daemon runs and whether applications can reach the API, and since 0.9 the networks the proxy is missing, the kernel's table of neighbours and what the agent found out about its Cloudflare token
POST/server/rotate-keyadminReplace the key stored secrets are encrypted with and re-encrypt them
POST/server/cloudflare/verifyadminCheck what the Cloudflare token can do, from this server's address and in every zone it sees, and answer with the result; at most once a minute. Since 0.9
GET/server/backupsadminThe backups of the agent's own state
GET/server/backups/:idadminOne of them
POST/server/backupsadminBack up the agent's state now
POST/server/backups/adoptadminRecord the backups the destinations hold and the database does not know
GET/applicationsreadSummaries of all applications, each with whether a certificate or an alert wants a look
GET/applications/:namereadOne application in detail, with the certificate of each hostname
POST/applications/:name/deploydeployStart a deployment from a deploy.yaml; ?static=<digest> for a static application; since 0.8 ?plain= names the env values written in plain sight
POST/applications/:name/validatedeployAsk whether a deployment of a deploy.yaml would be accepted, without deploying it
POST/applicationsdeployStart a deployment of the document in the body, for the application the document names. Since 0.7
POST/validatedeployvalidate for such a document. Since 0.7
GET/applications/:name/configdeployThe deploy.yaml that describes what the application runs, with references to stored secrets and, since 0.8, values deployed as plain kept and other secret values masked. Since 0.7
POST/applications/:name/imagesdeployLoad an image archive built by the client
POST/applications/:name/images/missingdeployWhich layers of an image about to be sent the server lacks
PUT/applications/:name/staticdeployUpload the folder of a static application
POST/applications/:name/redeploydeployDeploy the active configuration again
POST/applications/:name/rollbackdeployDeploy the configuration of an earlier successful deployment
POST/applications/:name/stopdeployStop all replicas
POST/applications/:name/startdeployStart a stopped application
DELETE/applications/:nameadminRemove containers and history
GET/applications/:name/logsreadLast log lines, or a live stream; since 0.9 the stream carries a heartbeat while it is quiet, and since takes it up from a time
GET/applications/:name/logs/archivereadWhat is kept of the output of ended containers and runs, newest first, without the lines. Since 0.7
GET/applications/:name/logs/archive/:idreadOne entry with its lines. Since 0.7
GET/applications/:name/logs/searchreadLines that contain a text, in the archive and in the replicas that exist, a page at a time. Since 0.7
GET/applications/:name/eventsreadThe application's event feed
GET/applications/:name/metricsreadPoint-in-time CPU and memory
GET/applications/:name/metrics/historyreadCPU and memory of each replica over the last hour, day or week
GET/applications/:name/trafficreadRequests, status classes, bytes and latency percentiles over the last hour, day or week
GET/applications/:name/requestsreadThe most recent requests as the proxy logged them
GET/applications/:name/volumesreadThe volumes of the active deployment
GET/applications/:name/volumes/:volume/archiveadminThe volume's contents as a tar archive
PUT/applications/:name/volumes/:volume/archiveadminReplace the volume's contents with a tar archive
GET/applications/:name/backupsreadThe backups the agent took of the application
GET/applications/:name/backups/:idreadOne backup, with the output of its last verification
POST/applications/:name/backupsdeployTake a backup now
POST/applications/:name/backups/:id/verifydeployProve that the backup restores; :id may be latest
POST/applications/:name/backups/:id/restoreadminReplace the application's volumes with the backup's
GET/applications/:name/backups/:id/volumes/:volume/archiveadminOne volume of the backup as a tar archive, decrypted
DELETE/applications/:name/backups/:idadminRemove the backup from every destination
GET/applications/:name/jobsreadThe scheduled jobs of the active deployment, with their last and next run
GET/applications/:name/runsreadRuns of jobs, hooks and one-off commands, without output
GET/applications/:name/runs/:idreadOne run with its output
POST/applications/:name/jobs/:job/rundeployStart a scheduled job now
POST/applications/:name/rundeployRun a one-off command
GET/deploymentsreadDeployment history
GET/deployments/:idreadOne deployment with configuration and events
GET/tokensadminThe stored tokens, without their values
POST/tokensadminCreate a token; the value is in this response and nowhere else
PUT/tokens/:nameadminChange the applications a token is limited to, its expiry, or both; the role and the value stay. Since 0.7
DELETE/tokens/:nameadminRevoke a token
GET/auditadminWho changed what, newest first
GET/audit/exportadminEverything that matches the same filters, streamed as CSV or as one JSON object per line; itself recorded. Since 0.7
GET/authnoneWhether people can sign in, and what an authorization request needs. No token.
POST/auth/exchangenoneTurn the code the provider sent the browser back with into a session. No token.
DELETE/auth/sessionreadForget the session the request is made with
GET/access/rulesadminWho may sign in, and as what
POST/access/rulesadminGive an address, a group, a domain or a name a role, creating or replacing the rule
DELETE/access/rules/:idadminRemove a rule; sessions that rested on it end with their next request
GET/access/sessionsadminWho is signed in right now
DELETE/access/sessions/:emailadminEnd every session of a person, named as the sessions list them
GET/secretsreadThe secrets stored on the server, names, scopes and dates only
PUT/secrets/:nameadminStore a secret, creating or replacing it; since 0.9 for one application with application in the body, else for the server
DELETE/secrets/:nameadminRemove a secret: the server's, or since 0.9 an application's own with ?application=
GET/registriesreadThe registries the agent holds a credential for, without passwords
PUT/registries/:registryadminCheck a credential against its registry and store it, creating or replacing it
DELETE/registries/:registryadminRemove a registry's credential
GET/certificatesreadThe certificates you supplied: what each says about itself, never the key or the PEM
PUT/certificates/:hostnameadminStore a certificate and its key under a hostname, creating or replacing it
DELETE/certificates/:hostnameadminRemove a certificate
GET/volumesreadEvery volume Shipwick created, with its application and size
DELETE/volumes/:nameadminRemove a volume whose application was deleted
POST/exportadminEverything the server runs as one encrypted file
POST/importadminTake in an export sent as the body and deploy what it holds
GET/importadminThe import that is running, or ran last
GET/exportsadminThe exports written to where backups go
GET/exports/:idadminOne of them
POST/exportsadminWrite one there now
GET/standbyreadThe applications that were imported stopped, the DNS records a promotion asks for, how the scheduled import is doing, and the promotion that runs or ran last
POST/standby/pulladminImport the newest export in the bucket now, stopped
POST/standby/promoteadminStart the applications that were imported stopped, in order; ?wait=false answers at once
GET/standby/promotionreadThe promotion that is running, or ran last
GET/metricsreadThe Prometheus text format. Not under /api/v1.

In every path, :name of an application must be a valid application name (lowercase letters, digits and dashes, at most 63 characters), and :volume follows the same rule. Anything else is 400 INVALID_REQUEST before the request reaches the engine. Every authenticated endpoint can also answer 401, 403, 429 and 500, since 0.8 503 RUNTIME_UNAVAILABLE when it asks a Docker daemon that does not answer, and 507 DISK_FULL when it writes to a disk without room; these are not repeated below.

GET /health ​

Liveness, for load balancers and shipwick server status. It takes no token and reveals nothing beyond the version.

StatusBody
200Health
json
{ "data": { "status": "ok", "version": "v1.1.0" } }

It asks neither Docker nor the database, and answers 200 while the Docker daemon does not: the agent itself is up. From the container of an application it is 403 APPLICATION_CALLER like every endpoint, see Authentication.

GET /server ​

StatusBody
200Server
503 RUNTIME_UNAVAILABLEThe Docker daemon does not answer; the endpoint asks it
json
{
  "data": {
    "agent_version": "v1.1.0", "hostname": "vps-1",
    "os": "linux", "kernel": "6.8.0", "architecture": "amd64", "docker_version": "29.8.0",
    "cpus": 4, "memory_bytes": 8589934592, "applications": 3, "containers": 5,
    "swap_bytes": 2147483648, "unlimited_memory": ["worker"],
    "docker": { "rootless": false, "unenforced_limits": [], "socket": "proxy" },
    "proxy": { "enabled": true, "reachable": true, "error": "", "routes": 4, "dns_challenge": false },
    "token": { "name": "ci", "role": "deploy", "kind": "token",
               "applications": ["my-api"], "expires_at": "2027-01-01T00:00:00Z" },
    "sign_in": { "configured": true, "issuer": "https://accounts.example.com", "name_claim": "email" },
    "notifications": { "webhook": true },
    "dashboard_url": "https://dashboard.example.com",
    "disk": { "total_bytes": 42949672960, "used_bytes": 37580963840 },
    "alerts": [
      { "kind": "disk", "severity": "warning", "application": "", "replica": 0,
        "message": "The server's disk is 87% full (5 GB of 40 GB free). See what takes the space with: docker system df",
        "since": "2026-03-01T09:41:30Z" },
      { "kind": "memory", "severity": "warning", "application": "my-api", "replica": 1,
        "message": "my-api replica 1 is at 93% of its memory limit (240 MB of 256 MB). At the limit it is killed and restarted; raise resources.memory in deploy.yaml, or watch it with: shipwick status my-api",
        "since": "2026-03-01T09:58:00Z" }
    ],
    "backups": { "destination": "s3", "encrypted": true,
                 "state_last_at": "2026-03-01T03:17:04Z", "state_error": "" },
    "network": {
      "proxy": "proxy.example.com:3128",
      "docker_proxy": false,
      "ca_file": true,
      "dns_resolvers": ["system"],
      "acme_directory": "https://ca.example.internal/acme/acme/directory"
    }
  }
}

Since 0.7 there are two more objects:

json
"log_archive": { "enabled": true, "entries": 278, "bytes": 63974240, "max_bytes": 1073741824, "retention_days": 14 },
"update": { "enabled": true, "latest_version": "v1.1.0", "checked_at": "2026-10-04T09:00:00Z", "available": false }

swap_bytes, unlimited_memory and docker are since 0.8. So are two fields that are present only when true, and absent from the example for that reason: proxy.plain_lookups and open_to_applications.

Since 0.9 there are three more, each present only when there is something to say:

json
"proxy": { "enabled": true, "reachable": true, "error": "", "routes": 4, "dns_challenge": false,
           "networks_missing": ["shipwick-control"] },
"kernel_limits": { "neighbour_table": 1024 },
"cloudflare": { "checked_at": "2026-10-11T09:00:00Z", "ok": false, "address": "2a01:4f8:1c1b:5e07::1",
                "zones": [ { "name": "example.com", "dns_edit": true }, { "name": "shipwick.com", "dns_edit": false } ],
                "problems": [ "the token cannot edit DNS records of shipwick.com: it needs Zone → DNS → Edit (DNS Settings, DNS Firewall and DNS Views are other permissions)" ] }

token is the token, or the session, this request was made with, so that a client knows what it may do before it tries: its role, the applications it is limited to and when it expires, as Authentication describes. sign_in says whether people can sign in with an OpenID Connect provider, and with which. notifications.webhook says whether SHIPWICK_WEBHOOK_URL is set on the agent. architecture is what a client building an image for this server passes to docker build --platform; see Images built by the client.

  • proxy.dns_challenge is true when certificates are obtained through a DNS record (SHIPWICK_CLOUDFLARE_API_TOKEN), so hostnames may be proxied by Cloudflare and may be wildcards.
  • proxy.plain_lookups, since 0.8, is present and true when the proxy is not Shipwick's image of this version — the proxy of an older release, the official Caddy image, an image of your own that was not built from Shipwick's Dockerfile.caddy. Such a proxy still serves; it finds an application's replicas without keeping the last answer of a name lookup, so a lookup that goes unanswered holds every request. The field is absent otherwise. See A proxy image of your own.
  • swap_bytes, since 0.8, is how much swap the server has; 0 is a server without swap. It is absent where the agent cannot tell, a development build off Linux.
  • unlimited_memory, since 0.8, names the running applications that have no memory limit, sorted: each may use whatever the server has. A stopped application and a static one are not among them. [] when there are none (an agent before 0.10 left the field out then), absent from an agent before 0.8.
  • docker, since 0.8, is what the daemon says about itself. rootless is true when it runs as an ordinary user of the server and not as root. unenforced_limits lists which of memory and cpu it accepts as a limit of resources and does not apply, because it has no cgroup controller for them; [] where it applies both. socket, since 1.1, is how the agent reaches the daemon, read off the address it was given: "proxy" through the filtered socket of the installation's socket proxy, which is every installation the installer makes, or "direct" on the daemon's own socket, as with compose.direct-socket.yml or an agent installed from a package. Absent from an agent older than 1.1, which is not a claim either way. See Limits that are not enforced, Rootless Docker and The Docker socket.
  • open_to_applications, since 0.8, is present and true when the containers of applications can reach the API over the network, so that only the token keeps them out; absent otherwise. See Authentication.
  • proxy.networks_missing, since 0.9, names the installation's networks the proxy's container is not attached to — among shipwick, shipwick-services and shipwick-control, in the compose file's order — looked at every 30 seconds. A proxy on some of its networks serves some applications and not others, or cannot reach the agent; docker compose up -d --force-recreate caddy on the server makes the container again. [] when the proxy is on all of them (an agent before 0.10 left the field out then), absent from an agent before 0.9. See When things break.
  • kernel_limits.neighbour_table, since 0.9, is net.ipv4.neigh.default.gc_thresh3: how many neighbours the kernel keeps before containers stop reaching each other, 1024 in a stock kernel. It is present only where the agent can read it, which is an agent that runs as a process of the host, installed from a package; the kernel shows the setting in the host's own network namespace only, so an agent in a container cannot. shipwick doctor warns from a quarter of the table on. See Prepare a server.
  • cloudflare, since 0.9, is what the agent found out about its Cloudflare token when it last checked it, the shape of POST /server/cloudflare/verify's answer. Absent without a token, before the first check has finished, and from an agent older than 0.9.
  • dashboard_url is https://<SHIPWICK_DASHBOARD_DOMAIN>, or "" when the dashboard has no hostname.
  • disk is the filesystem that holds the agent's data directory. used_bytes / total_bytes is the percentage df shows: total_bytes leaves out the blocks reserved for root. It is null where the agent cannot measure it, a development build off Linux.
  • alerts are the conditions that hold right now, oldest first; [] when there are none. kind is memory, disk, restarts, unhealthy or, since 0.8, docker; severity is warning or critical: disk and unhealthy become critical, and docker always is. memory and restarts name an application and a replica; unhealthy an application, with replica 0; disk and docker neither. since is when the alert was raised, and stays when a warning turns critical. Alerts are kept in memory: an agent that restarts raises again what still holds. An alert about an application is also in its events, with the type alert.
  • The docker alert is raised when the Docker daemon has not answered for 30 seconds and cleared by its first answer. While it stands, GET /server itself is answered 503 RUNTIME_UNAVAILABLE, so this alert is never read here: it is read from the webhook and from GET /metrics, which never asks Docker. The memory alert is not raised on a server whose Docker does not enforce the memory limit.
  • backups.destination is s3 when a bucket is configured, local when backups stay in the agent's directory, and none for an agent started without anywhere to keep them. encrypted says whether SHIPWICK_BACKUP_PASSPHRASE is set. state_last_at is the last successful backup of the agent's state, null if there has been none. state_error is why there is none (no passphrase) or why the last attempt failed, and empty when the last attempt succeeded.
  • network says how the server reaches what is outside it:
    • proxy is the proxy the agent's own requests go through (the webhook, the bucket, the sign-in provider) as host:port, from HTTPS_PROXY or HTTP_PROXY; "" when there is none. The proxy's URL may hold a password, which is never part of it.
    • docker_proxy says whether the Docker daemon has a proxy configured. Images are pulled by the daemon: proxy set and docker_proxy false is the usual reason a pull fails behind a proxy.
    • ca_file is true when certificate authorities of your own are trusted in addition to the system's (SHIPWICK_CA_FILE).
    • dns_resolvers are the name servers asked whether a hostname points at the server: addresses with their port, or ["system"]. [] means the public ones.
    • acme_directory is the ACME server certificates are obtained from; "" is Let's Encrypt.
  • sign_in.name_claim, since 0.7, is the ID token claim people are named by: email unless the agent is configured otherwise (SHIPWICK_OIDC_NAME_CLAIM), "" without a provider.
  • log_archive, since 0.7, reports the log archive as a whole. enabled is false when SHIPWICK_LOG_RETENTION_SIZE is 0; entries is how many are kept; bytes is what they take on the disk, max_bytes what they may take, retention_days how long each is kept.
  • update, since 0.7, says whether a newer release than the agent exists. The agent asks GitHub itself, once a day; nothing can be asked of the agent to make it check now.
    • enabled is false when the agent was told not to ask (SHIPWICK_UPDATE_CHECK=off); the other three are then "", null and false.
    • latest_version is the tag of the latest release that is not a pre-release, with its v; "" until the agent has been able to ask — the first seconds after its first start, or for as long as it cannot reach GitHub.
    • checked_at is when GitHub last answered, null until then. An attempt that failed does not move it: a server that lost its way out keeps the last answer and the time it is from.
    • available is true when latest_version is newer than agent_version by semantic versioning. It is false for an agent that runs the latest release, a pre-release of a later one, or a development build.

A pull that fails before the registry answers (no route, a proxy that refuses, a certificate the daemon does not trust) fails the deployment with the daemon's message followed by what to change on the server; it has no error code of its own. See Run behind a corporate proxy or without internet.

An agent before 0.5 sends none of dashboard_url, disk, alerts, backups and proxy.dns_challenge. An agent before 0.6 sends no network and no sign_in, and only name and role in token. An agent before 0.7 sends no log_archive, no update and no sign_in.name_claim. An agent before 0.8 sends none of swap_bytes, unlimited_memory, docker, open_to_applications and proxy.plain_lookups, so the absence of a field says nothing there; docker, which an agent of 0.8 always sends, tells the two apart. An agent before 0.9 sends none of proxy.networks_missing, kernel_limits and cloudflare, each of which an agent of 0.9 sends only when there is something to say, so their absence says nothing about the agent's version. See Alerts and metrics.

POST /server/rotate-key ​

The agent generates a new encryption key, re-encrypts every stored env value, secret, registry password and certificate key under it in one transaction, and uses it from then on. No application is touched. No body.

bash
curl -X POST …/server/rotate-key
StatusBody
200KeyRotation
400 INVALID_REQUESTThe agent has no encryption key to rotate
409 KEY_ROTATION_PENDINGThe key was already rotated since the agent started, and its environment still holds the old one; details: {key_file}
json
{ "data": { "values": 3, "deployments": 12,
            "key_source": "file", "key_file": "/var/lib/shipwick/encryption.key" } }

values counts the re-encrypted secrets, registry passwords, certificate keys and, since 0.7, the references kept for deployments — one for each deployment whose document referred to a secret, see GET /applications/:name/config — deployments the deployment records whose env was re-encrypted. key_source is file when the agent keeps the key in its data directory; it has then replaced key_file, and the key is not in the response.

With the key in SHIPWICK_ENCRYPTION_KEY, key_source is environment: the agent cannot change its own environment, so the response carries the new key, this once, for you to put there, and key_file is a copy the agent keeps in its data directory until it has been started with the new key:

json
{ "data": { "values": 3, "deployments": 12, "key_source": "environment",
            "key": "5f0c…64 hexadecimal characters",
            "key_file": "/var/lib/shipwick/encryption.key.new" } }

The agent keeps working with the new key. Started again with the old one in its environment, it refuses to start and says where the new key is. Until it has been restarted with the new key, another rotation is 409 KEY_ROTATION_PENDING.

The rotation is recorded in the agent's log with the name of the token that asked for it. It is not an application event, and the key is never logged. See Rotate the encryption key.

POST /server/cloudflare/verify ​

Since 0.9. The agent checks what its Cloudflare token (SHIPWICK_CLOUDFLARE_API_TOKEN) can do, the way the proxy is going to use it: it asks Cloudflare whether it accepts the token from the address the server calls from (GET /user/tokens/verify), lists the zones the token sees (GET /zones), and in each creates and at once removes a TXT record of its own — _shipwick-check.<zone>, TTL 60, a value that names the server and the time — which is the only sure test of Zone → DNS → Edit. It runs the same check once when it starts. No body.

bash
curl -X POST …/server/cloudflare/verify
StatusBody
200CloudflareStatus
409 CLOUDFLARE_NOT_CONFIGUREDThe agent has no Cloudflare token
429 CLOUDFLARE_CHECKED_RECENTLYThe token was checked less than a minute ago; details: {checked_at, retry_after_seconds} and a Retry-After header. The result of that check is cloudflare in GET /server
json
{ "data": {
  "checked_at": "2026-10-11T09:00:00Z",
  "ok": false,
  "address": "2a01:4f8:1c1b:5e07::1",
  "zones": [ { "name": "example.com", "dns_edit": true },
             { "name": "shipwick.com", "dns_edit": false } ],
  "problems": [ "the token cannot edit DNS records of shipwick.com: it needs Zone → DNS → Edit (DNS Settings, DNS Firewall and DNS Views are other permissions)" ]
} }

ok is true when the token is valid and active, sees at least one zone and can edit the DNS records of every zone it sees; problems is then empty. address is the address Cloudflare saw the check come from — the one an IP filter on the token has to name — or "" when it could not be learned. problems are sentences a person acts on, one per thing that is wrong: Cloudflare refuses the token from this server's address 2a01:…: an IP filter on the token must name that address, or the token is not valid (Cloudflare answered HTTP 403, code 10000: Authentication error) — the two cannot be told apart from Cloudflare's answer; the token is not valid (…); the token is disabled: …; the token cannot list zones: it needs Zone → Zone → Read (…); no zone is visible to the token: …; the one above for a zone it cannot edit; the check record _shipwick-check.<zone> was created and could not be removed: delete that TXT record by hand (…); Cloudflare's API could not be reached from this server: …; and the token sees more than 50 zones, and only those were checked: …. Nothing of the token itself is in the result, in the log or in any error.

A check writes, so the agent refuses one within a minute of the last; two requests at once share one check. The request needs the admin role and is recorded in the audit trail as cloudflare.verify. shipwick doctor with an admin token makes this request, and reads GET /server with any other. See Put Cloudflare in front of the server.

GET /server/backups ​

The backups of the agent's own state, newest first: its database and the key that encrypts the secrets in it. The agent takes one daily. They have the shape of an application's backup, with volumes naming the two files, shipwick.db and encryption.key.

ParameterDefault
limit501 to 500
StatusBody
200Array of BackupRun
400 INVALID_REQUESTInvalid limit

GET /server/backups/:id ​

StatusBody
200BackupRun
400 INVALID_REQUEST:id is not a positive number
404 NOT_FOUNDNo such backup

POST /server/backups ​

Backs up the agent's state now. No body.

StatusBody
202BackupRun with status: "running", and a Location header: /api/v1/server/backups/<id>. Poll it until completed_at is set.
409 BACKUPS_NOT_ENCRYPTEDSHIPWICK_BACKUP_PASSPHRASE is not set: the key is never written unencrypted
409 BACKUP_BUSYA backup of the agent's state is already running
409 BACKUP_NOT_USABLEThe agent was started without anywhere to keep backups

There is no endpoint that restores the state; that is done with the agent stopped. See Back up and restore volumes and Bring a lost server back.

POST /server/backups/adopt ​

A database restored from a backup of the agent's state does not know the backups taken after it, whose files are still in the directory and in the bucket. This endpoint records them. The body is optional:

json
{ "application": "postgres" }
FieldType
applicationstringOptional. Looks at one application's backups. Without it: every application's, the agent's state and the exports.
StatusBody
200BackupAdoption, once the destinations have been listed
400 INVALID_REQUESTA name that is not an application's; a body that is not JSON, or too large
409 FOREIGN_BUCKETThe bucket, under the agent's prefix, is marked by another installation
409 BACKUP_NOT_USABLEThe agent was started without anywhere to keep backups
500 INTERNAL_ERRORThe bucket cannot be listed; the message carries the service's answer
json
{ "data": { "adopted": [
    { "kind": "application", "application": "postgres",
      "backup": { "id": 13, "trigger": "adopted", "status": "succeeded",
        "started_at": "2026-03-02T03:00:41Z", "completed_at": "2026-03-02T03:00:41Z",
        "volumes": [{ "volume": "data", "size_bytes": 2254857830 }],
        "destinations": ["s3"], "encrypted": true, "error": "",
        "activity": "", "verified_at": null, "verify_error": "",
        "restored_at": null, "restore_error": "" } },
    { "kind": "state", "application": "", "backup": { "id": 14, "trigger": "adopted", "…": "…" } }
  ],
  "skipped": [
    { "kind": "state", "application": "", "id": 15,
      "reason": "encryption.key.enc is missing: the backup was not finished" }
  ] } }
  • kind is application, state or export; application is empty for the last two, whose backups are then listed by GET /server/backups and GET /exports.
  • A backup is recorded under the id its files carry, with what they say: volumes from their names, size_bytes from their sizes (for an encrypted file the size of what it holds), started_at and completed_at both from when the newest of them was written, destinations from where all of them are, encrypted from their names. Its trigger is adopted.
  • skipped lists the runs whose files are not a backup that can be recorded: one of the agent's state or an export that lacks a file, files that are partly encrypted, a file that has one size in the directory and another in the bucket. Nothing is changed for them.
  • Both lists are empty when the database knows everything. Nothing is adopted twice, and no file is written, moved or removed.
  • An adopted backup is verified, restored, downloaded, removed and counted towards backups.keep like any other.
  • Whether an application's backup was finished cannot be told from its files: it is adopted with the volumes that are there.

An agent before 0.6 answers 404 ENDPOINT_NOT_FOUND. See Bring a lost server back.

GET /applications ​

StatusBody
200Array of Application

Each carries its domain and, when it serves only a part of it, its path: the address of an application is https://<domain><path>.

Every application, in the list and on its own, says whether it wants a look:

json
{ "name": "my-api", "status": "HEALTHY", "…": "…",
  "certificate_problem": { "hostname": "www.example.com", "status": "waiting_for_dns",
    "message": "does not resolve yet; create an A record for it that points to 203.0.113.10" },
  "alert_count": 2, "alert_severity": "critical" }
  • certificate_problem is null while no certificate of the application is known to be out of order. Otherwise it names one hostname (the domain, an alias or a redirect) with the status and message that certificates carries for it: the worst among them, waiting_for_dns before expiring before obtaining, and of two equally bad the first in the order of certificates. unknown (no proxy, not checked yet, the proxy does not answer) is not a problem.
  • alert_count is how many alerts about the application are active and alert_severity the highest severity among them: warning, critical, or "" when there is none. The alerts themselves are in GET /server.

Both are read from what the agent has in memory; listing costs no more for them. An agent older than 0.6 sends neither field.

GET /applications/:name ​

Status, the active configuration with environment values, basic-auth passwords and, since 0.10, logging.options.splunk-token masked, the active deployment, every container of the application, and the certificate of each hostname.

StatusBody
200ApplicationDetail
404 NOT_FOUNDUnknown application

certificates is the certificate the proxy presents for each hostname the application answers to, its domain, aliases and redirects:

json
"certificates": [
  { "hostname": "api.example.com", "status": "ok", "issuer": "Let's Encrypt E7",
    "not_after": "2026-05-20T08:00:00Z", "message": "" },
  { "hostname": "www.example.com", "status": "waiting_for_dns", "issuer": "", "not_after": null,
    "message": "does not resolve yet; add an A record: www.example.com → 203.0.113.10 (DNS only, not proxied)" },
  { "hostname": "shop.example.com", "status": "obtaining", "issuer": "", "not_after": null,
    "message": "the proxy has no certificate for it yet: Let's Encrypt could not connect to the server on port 443 (tls-alpn-01): a firewall in front of it?",
    "failure": { "at": "2026-10-11T14:00:12.5Z", "challenge": "tls-alpn-01",
                 "reason": "Let's Encrypt could not connect to the server on port 443 (tls-alpn-01): a firewall in front of it?",
                 "detail": "203.0.113.10: Timeout during connect (likely firewall problem)" } }
]
statusMeaning
okThe proxy presents a certificate for this name with more than 14 days left
expiring14 days or less left, or already expired; message says how long (expires in 9 days, on 2026-03-10). The proxy renews with a third of the lifetime to go, so this means renewal is failing.
obtainingThe proxy serves the hostname but has no certificate for it yet: the handshake fails, or presents one for another name
waiting_for_dnsThe hostname does not point at this server and is not handed to the proxy; message is the reason, with the record to create
unknownNot looked at yet, the proxy did not answer, or the agent has no proxy; message says which

issuer and not_after are set once a certificate has been seen, message for every status but ok. The agent looks once a minute per hostname, every ten seconds while it is obtaining, by connecting to the proxy with the hostname as the server name; it reports the certificate and does not verify its chain. A certificate that lives less than 56 days is expiring in the last quarter of its lifetime rather than the last 14 days. The list is empty for an application without a domain. See Certificates.

failure, since 0.9, is the last failure the proxy logged while obtaining or renewing the hostname's certificate, read from the proxy's own log: at, the ACME challenge that failed (tls-alpn-01, http-01, dns-01, or "" when the failure came before one was tried), reason — a sentence with the cause and what to look at — and detail, the proxy's own words, trimmed. It is present with any status: with obtaining the message ends with the reason, with ok or expiring it means the renewal is failing. It is absent while the proxy logged nothing since the certificate last arrived, and from an agent older than 0.9. The reasons the agent writes: Let's Encrypt could not connect to the server on port 443 (tls-alpn-01): a firewall in front of it? (port 80 for http-01); the DNS record for the challenge could not be created: … with the sentence of the Cloudflare token check when it found something, otherwise with Cloudflare's answer as the proxy quoted it; Let's Encrypt did not find the DNS record for the challenge (dns-01): …; Let's Encrypt was answered by something other than this server (tls-alpn-01): …; Let's Encrypt refuses for now, its rate limit is reached: …; it lifts within the hour; and Let's Encrypt did not issue it: … for anything else, with the certificate authority in place of the name when SHIPWICK_ACME_DIRECTORY is set. The application's events record each new reason once, as a warning. certificate_problem in GET /applications is unchanged in shape; its message carries the reason for obtaining.

containers also lists the containers the agent is retiring in the background, replaced by a deployment or left over, each with stopping: true until its process exits or its deploy.stop_timeout is over. Such a container is not a replica any more; see Container.

POST /applications/:name/deploy ​

Starts a deployment. The body is the deploy.yaml document. JSON is accepted as well. The maximum size is 64 KB. name in the document must equal :name. An application is created by its first deployment.

${NAME} placeholders in env values, and in the passwords of proxy.basic_auth, are filled in by the agent from the secrets stored on the server, before the deployment is recorded; the record holds the values, so a later change of a secret does not reach a redeploy or rollback of it. $${NAME} there is a literal ${NAME}. A placeholder anywhere else is a convention of shipwick, which fills it in before sending, and is stored literally here.

bash
curl -X POST http://localhost:9000/api/v1/applications/my-api/deploy \
  -H "Authorization: Bearer $SHIPWICK_AGENT_TOKEN" \
  --data-binary @deploy.yaml
Parameter
staticFor a static application only: the digest of a folder uploaded with PUT …/static. Required with static in the document, refused without it.
plainSince 0.8. The env values of the document that were written in it in plain sight, as fields: ?plain=env.LOG_LEVEL,env.REGION, separated by commas, or the parameter repeated. See below.
StatusBody
202Deployment with status PENDING, and a Location header. See Asynchronous deployments.
400 INVALID_CONFIGValidation failed; a hostname, a path of it or a published port is taken; an env value or a basic-auth password refers to a ${NAME} that is not stored; a wildcard hostname that no certificate can be had for
400 INVALID_REQUESTThe document names another application than the URL; unreadable body; a build document without an image (the client builds and loads the image first, then names it here); a static document without ?static=, or ?static= on a container application; a field of ?plain= that is not env.<NAME> with a variable the document sets
404 NOT_FOUND?static= names no upload the agent has
409 DEPLOYMENT_IN_PROGRESSAnother operation holds the application
413 INVALID_REQUESTBody larger than 64 KB
503 RUNTIME_UNAVAILABLEThe agent is shutting down, or the Docker daemon does not answer
507 DISK_FULLThe agent's database has no room for the record of the deployment

?plain= says which env values of the document stood in it as they are, as opposed to filled in by whoever sends it. The agent keeps the statement with the deployment and does one thing with it: those values are in the document of what runs as they are, where every other value is masked. It is the sender's word, taken by an endpoint that takes deploy; nothing else the API returns changes, and without the parameter nothing is plain. A value that holds a ${NAME} for the agent stays the reference it is, whatever the parameter says of it. shipwick deploy names the values that stand in the file as it sends them. An agent before 0.8 ignores the parameter.

Paths and the proxy block ​

path and proxy in the deploy.yaml are part of the stored configuration, and come back in every spec:

json
{
  "domain": "example.com",
  "path": "/api",
  "proxy": {
    "strip_prefix": true,
    "headers": { "X-Frame-Options": "DENY" },
    "basic_auth": [
      { "path": "/api/admin", "username": "admin", "password": "********" }
    ],
    "redirects": [
      { "from": "/api/old", "to": "/api/new", "status": 308 }
    ]
  },
  "static": { "dir": "dist", "fallback": "index.html" }
}

Each of path, proxy and its four members is left out when it is not set, and so is static.fallback; basic_auth[].path is left out for an account of the whole application; redirects[].status is always present, 308 when the document named none. path: / is stored as no path.

init: true in the deploy.yaml comes back as "init": true in the spec; the key is left out when it is not set or false. A redirect hostname of an application with a path is answered with 308 to https://<domain><path> plus the request's path and query.

A password is always ******** in a response, like an env value. In the request it is the password, or a ${NAME} that the agent fills in from the stored secrets exactly as it does for env; $${NAME} is a literal ${NAME}. The record holds the value, encrypted. A name that is not stored is refused with the field proxy.basic_auth[i].password and the same message and expected as for an env value. A stored value that cannot be a password, shorter than 8 characters or longer than 72 bytes, is refused under the same field, with ${NAME} filled in from the server's secrets, the password is too short: at least 8 characters, without repeating it.

Applications may share a hostname when their paths differ. It is 400 INVALID_CONFIG when they do not: field is path when this application names one, example.com/api is already served by application "api"; applications share a domain under different paths, and domain or aliases[i] when it names none and another application has the rest of the hostname. A hostname in another application's redirects, and the agent's and the dashboard's own, cannot be shared under any path. Paths are compared without regard to case.

The step event of a deployment with a path reads Routed https://example.com/api to 2 replicas. See Paths and the proxy block.

The security block ​

Since 0.8. security in the deploy.yaml comes back in every spec as it was understood:

json
{
  "user": "1000:1000",
  "security": {
    "read_only": true,
    "tmpfs": [
      { "path": "/tmp", "size_bytes": 67108864 },
      { "path": "/var/cache/api", "size_bytes": 209715200 }
    ],
    "capabilities": [],
    "non_root": true
  }
}

security is left out for an application without the block, and for a block that asks for nothing. read_only and non_root are left out when false, tmpfs when empty; size_bytes is always present, 67108864 when the document named no size. Nothing in the block is a secret, and nothing is masked.

capabilities has three states:

capabilitiesThe containers keep
left outDocker's default set
[]Nothing: the document said none
a listThose, in upper case without CAP_ and in alphabetical order, whatever the document wrote

A client that reads a missing capabilities as an empty list turns "everything" into "nothing".

A document is refused with 400 INVALID_CONFIG and the usual fields for:

fieldWhat is refused
securityA key of the block that does not exist; a value that is not a block; the block next to static
security.capabilitiesAn empty list (none is how to say it); a word other than none
security.capabilities[i]A capability outside Docker's default set, or one listed twice
security.tmpfsMore than 10 entries
security.tmpfs[i].pathA path that is missing, is not absolute and clean, is /, or is mounted already by a volume or another entry
security.tmpfs[i].sizeA size that cannot be read, or is outside 1 MB to 1 GB
userUnder non_root: true, a user that is root, the id 0 or a name

What only the image can say is checked when the image is on the server. A deployment under non_root: true whose image names no user, the user root, the id 0 or a user by name, and whose spec has no user, is accepted with 202 and fails: status FAILED, no container created, the previous version untouched, and in error:

text
security.non_root refuses image nginx:1.27: it names no user, and a container without one runs as root; set user in deploy.yaml to a numeric id the image can run as, e.g. user: "1000:1000", or build the image with a USER instruction

A job or a one-off command that would create such a container later — the tag names another image by then — fails the same way: the run is failed with the sentence in its output.

An agent before 0.8 answers a document with the block as it answers every key it does not know: 400 INVALID_CONFIG, field line N, message unknown field "security". See Containers locked down further.

POST /applications/:name/validate ​

Takes the same body as deploy and answers what deploy would answer, without deploying: nothing is recorded, pulled or started, and the application is not locked. While a deployment runs, validate still answers, where deploy would answer 409 DEPLOYMENT_IN_PROGRESS.

bash
curl -X POST http://localhost:9000/api/v1/applications/my-api/validate \
  -H "Authorization: Bearer $SHIPWICK_AGENT_TOKEN" \
  --data-binary @deploy.yaml
StatusBody
200Validation: {"valid": true}
400 INVALID_CONFIGWhat deploy would give, status and body alike: a field that does not validate, a hostname or a published port that something else holds, a ${NAME} that is not among the stored secrets
400 INVALID_REQUESTThe document names another application than the URL; unreadable body
413 INVALID_REQUESTBody larger than 64 KB
json
{ "data": { "valid": true } }

It is meant to be asked before an image is built or a folder uploaded, so it does not ask for either: a document with build and no image is valid here, where deploy refuses it, and a static application needs no ?static=. An agent that predates the endpoint answers 404 ENDPOINT_NOT_FOUND; deploy without asking then.

POST /applications ​

Since 0.7. POST /applications/:name/deploy for a caller that has a document and has not parsed it: the application is the one the document's name says. Body, query (?static=<digest> for a static application, and since 0.8 ?plain=), answers and errors are those of the endpoint it stands for.

bash
curl -X POST http://localhost:9000/api/v1/applications \
  -H "Authorization: Bearer $SHIPWICK_AGENT_TOKEN" \
  --data-binary @deploy.yaml
StatusBody
202As deploy
400 INVALID_CONFIGAs deploy; also a document whose name cannot be read, with the field name
403 TOKEN_LIMITEDThe token is limited to other applications than the one the document names, or the document names none that can be read

The name is read from the document before the request is authorized, and nothing else of the document is: a token limited to applications is checked against it, and the audit trail records the deployment under it, as if it had been in the address. The audit entry of a document whose name cannot be read has no application. An agent before 0.7 answers 404 ENDPOINT_NOT_FOUND; use the endpoint with the name then.

POST /validate ​

Since 0.7. POST /applications/:name/validate for a document that names its application, in the same way as POST /applications: body, answers and errors are those of validate, and a limited token is checked against the document's name. An agent before 0.7 answers 404 ENDPOINT_NOT_FOUND.

GET /applications/:name/config ​

Since 0.7. Writes the configuration of the active deployment as the deploy.yaml that describes it, in the key order and style shipwick init uses.

ParameterDefault
escapefalsetrue writes the document for a file that shipwick deploy reads: the CLI fills in ${NAME} everywhere, the agent only in the secret values, so a literal ${NAME} elsewhere — in a command, say — is written $${NAME}. Without it the document is what the agent itself reads, and what goes back to POST /applications. The secret values are the same in both.
StatusBody
200ApplicationConfig
403 TOKEN_LIMITEDThe token is limited to other applications
404 NOT_FOUNDUnknown application
409 NOT_DEPLOYEDNo active deployment
json
{
  "data": {
    "application": "my-api",
    "deployment_id": 12, "sequence": 7, "version": "1.4.2",
    "document": "# A value shown as \"********\" was given when …\n\nname: my-api\n\nimage: ghcr.io/company/my-api:1.4.2\n\n…",
    "masked": ["env.API_KEY", "proxy.basic_auth[0].password"],
    "plain": ["env.LOG_LEVEL"]
  }
}

document, for an application deployed with ?plain=env.LOG_LEVEL, one reference and one value nobody spoke for:

yaml
# A value shown as "********" was given when the application was deployed and
# is not handed out. Write it again, or store it on the server with
# shipwick secret set NAME and refer to it as ${NAME}. A deployment of this
# file is refused until every such value has been replaced.

name: my-api

image: ghcr.io/company/my-api:1.4.2

port: 8080

replicas: 1

env:
  API_KEY: "********" # not handed out: write the value again, or refer to a secret as ${NAME}
  DATABASE_URL: postgres://app:${DB_PASSWORD}@db:5432/app
  LOG_LEVEL: debug

restart:
  policy: always

The secret values of a configuration, env values and the passwords of proxy.basic_auth, are never in it, and an env value is one unless its deployment said otherwise. A value is one of three kinds:

  • A value the deployed document wrote with a ${NAME} that the agent filled in from its secrets is that text again, the placeholders in place. The agent keeps it next to the deployment, encrypted like a secret; a redeploy and a rollback carry it on, and so do a key rotation, an export and an import.
  • An env value that the deployment named in ?plain=, since 0.8, is the value, a literal ${NAME} in it written $${NAME}. plain names those fields, sorted; it is [] when there are none, and absent from an agent before 0.8. The statement is kept and carried on like a reference. A deployment of the document that names the same fields again keeps them plain; one that does not masks them from then on. shipwick deploy names the values that stand in the file as it sends them; the dashboard names the ones it was handed out as plain and that were not edited.
  • Every other value — filled in by the CLI from its environment or --env-file, or sent by a client that said nothing, which the agent cannot tell apart from a password — is the mask, "********", with a comment on its line. masked names those fields, in the order of the document; it is [] when there are none. The comment at the top is there only when there are some. A basic-auth password is never plain, and neither is logging.options.splunk-token, which since 0.10 is masked, kept and refused like a basic-auth password (logging.options.splunk-token in masked and in fields).

What is written in a deploy.yaml in plain sight is therefore readable by whoever may deploy the application; a password belongs in a ${NAME}.

The text around a reference and a plain value are given back as they arrived, which GET /applications/:name masks along with the rest. That is why the endpoint takes deploy, and a limited token gets the documents of its applications only: whoever may deploy an application can read its environment by running a command in it.

Deployed again unchanged — to POST /applications or to POST /applications/:name/deploy — a document without masks gives the same configuration, its references filled in from the secrets as they are then. A document that holds a mask is refused, by every endpoint that takes a document and whoever wrote it:

json
{ "error": { "code": "INVALID_CONFIG", "message": "invalid deploy.yaml",
             "details": { "fields": [ {
               "field": "env.API_KEY",
               "message": "******** is what the server shows in the place of this value, not the value",
               "expected": "the value itself, or ${NAME} with the value stored by shipwick secret set NAME" } ] } } }

So "********" cannot be a value of env or a basic-auth password; a stored secret may hold it.

For a static application static_digest is the folder the active deployment serves ("sha256:…"); a deployment of the document names it in ?static=. The field is absent otherwise. An application deployed by an agent before 0.7 has no references kept, and all its secret values are masked until it is deployed again. In the same way, an application last deployed by an agent or a client before 0.8 has no value that is plain: every env value that is not a reference is masked until it is deployed again with ?plain=. An agent before 0.7 answers 404 ENDPOINT_NOT_FOUND. See Get deploy.yaml back from the server.

POST /applications/:name/images ​

Loads an image archive for an application whose deploy.yaml has build:. The image is built where shipwick deploy runs and sent here; the agent never builds. The CLI does three things, and any client may do the same:

  1. docker build --platform <the server's> -t shipwick.local/<name>:<tag> …, where <tag> is <UTC yyyymmdd-hhmmss>-<4 hex> and the platform follows architecture from GET /server.
  2. POST /applications/:name/images with the output of docker save as the body, Content-Type: application/x-tar, chunked or with a Content-Length.
  3. POST /applications/:name/deploy with image set to the reference the answer named.
bash
docker save shipwick.local/my-api:20260927-153000-a1b2 \
  | curl -X POST -H "Authorization: Bearer $SHIPWICK_AGENT_TOKEN" -H "Content-Type: application/x-tar" \
      --data-binary @- http://localhost:9000/api/v1/applications/my-api/images
StatusBody
201LoadedImage: the reference that was loaded, and its size
400 INVALID_REQUESTThe body is not Content-Type: application/x-tar; the archive does not carry exactly one image tagged shipwick.local/<name>:<tag> for this application. What was loaded is removed again, by its ID, and since 0.10 every tag the load moved — another application's, the proxy's or the agent's — is pointed back at the image it named; an agent before 0.10 left such an image without its name, and its next redeploy, rollback or replica recreation failed with "is not on this server".
409 IMAGE_INCOMPLETEThe archive leaves out a layer the server's Docker cannot produce. Nothing stays loaded; send the whole archive. See …/images/missing.
413 INVALID_REQUESTThe archive is larger than 4 GB
507 DISK_FULLSince 0.8. The server's disk has no room for the image
json
{ "data": { "image": "shipwick.local/my-api:20260927-153000-a1b2", "size_bytes": 68800000 } }

Loading takes no application lock. A deployment that ends FAILED or ROLLED_BACK removes the image it named unless something else needs it, and says so in a step. shipwick.local is a host that does not exist: the agent never pulls such an image, and a deployment whose local image is not on the server — pruned, or a rollback to a version this server was never sent — fails with … is not on this server; it was built on a developer's machine — run shipwick deploy from the project again. Local images are pruned like any other: the one running and the rollback target stay. A redeploy of such an application with an image from elsewhere is 400 INVALID_REQUEST; without one, it keeps the image it has. The deployment's event reads Using image shipwick.local/my-api:…, sent from a developer's machine in place of Pulled image ….

POST /applications/:name/images/missing ​

Between building an image and sending it, a client may ask what it need not send. The body lists the image's layers as diff IDs, base layer first (RootFS.Layers of docker image inspect), 1 to 256 of them, each sha256:<64 hex characters>:

json
{"layers": ["sha256:74d9…f711", "sha256:ba32…b114", "sha256:2e1f…4057"]}
StatusBody
200MissingLayers: the layers the server's Docker does not have, in the same order; an empty list when it has them all
400 INVALID_REQUESTInvalid JSON or an unknown field; layers is empty, longer than 256, or holds something that is not a diff ID
json
{"data": {"missing": ["sha256:2e1f…4057"]}}

The request reads the daemon and changes nothing. A layer is on the server when an image there starts with the same diff IDs up to and including it, so the answer is always the end of the list. The archive sent afterwards may then leave out the files of the other layers (blobs/sha256/<digest>, as manifest.json in the archive lists them, in the same order as the diff IDs) and nothing else: the manifests and the image's configuration always travel.

The answer is advice. If the archive leaves out a layer the daemon cannot produce, because the image that held it was pruned in the meantime or the client left out more than it was told, the upload is 409 IMAGE_INCOMPLETE, nothing stays loaded, and the whole archive is to be sent. An agent before 0.5 answers the question with 404 ENDPOINT_NOT_FOUND; send the whole archive.

PUT /applications/:name/static ​

Uploads the folder of a static application (static: dist/ in deploy.yaml): a folder the proxy serves itself, for which the agent creates no container. Deploying one is two requests: this upload, then POST …/deploy?static=<digest>.

The body is the folder as a tar archive with Content-Type: application/x-tar, up to 512 MB: files and directories only, paths relative to the folder, nothing outside it. A symbolic link is refused, since the proxy's file server would follow it. The agent keeps the archive under its digest, one per application; a new upload replaces the last.

bash
tar -C dist -cf - . | curl -X PUT -H "Authorization: Bearer $SHIPWICK_AGENT_TOKEN" \
  -H "Content-Type: application/x-tar" --data-binary @- \
  http://localhost:9000/api/v1/applications/web/static
curl -X POST -H "Authorization: Bearer $SHIPWICK_AGENT_TOKEN" --data-binary @deploy.yaml \
  "http://localhost:9000/api/v1/applications/web/deploy?static=sha256:3f2a…"
StatusBody
200StaticUpload: the digest, the files' sizes added up, and their count
400 INVALID_REQUESTThe body is not Content-Type: application/x-tar; the archive holds no files, or holds anything but files and directories
413 INVALID_REQUESTThe folder is larger than 512 MB
507 DISK_FULLSince 0.8. The server's disk has no room for the folder. An agent before 0.8 answers 400 INVALID_REQUEST, as for a body that is not a tar archive
json
{ "data": { "digest": "sha256:3f2a…", "size_bytes": 3250000, "files": 42 } }

The deployment then answers like any other. Its Deployment has no image; its version is the digest's first twelve hex characters, and it carries static: {digest, size_bytes, files}. Its events read Received 42 files (3.1 MB), Copied 42 files into the proxy, Found index.html, Routed https://example.com to the uploaded files. A folder without an index.html fails the deployment: FAILED: the folder has no index.html…. With static: {dir, fallback} the agent looks for that file too, Found 200.html, the fallback page or FAILED: the folder has no 200.html, which static.fallback names…, and the proxy answers every path that names no file with it, status 200.

Redeploy and rollback need no upload: the proxy keeps the folder of the serving version and of the one before it, and both re-route to a kept folder. A deployment that runs containers, for an application that was a folder, keeps the folder it replaced, the default rollback target, and removes the others (Removed 1 folder of older versions); the container deployment after it removes that one too. A rollback to a version whose folder is gone fails with the files of <version> are no longer on the server: deploy the folder again.

In the application views static is true and replicas is all zeros; the status is HEALTHY while the deployment is active and STOPPED after stop, which makes the domain answer 503 until start. Logs, metrics, the metrics history, jobs and run answer 409 STATIC_APPLICATION; volumes is an empty list.

POST /applications/:name/redeploy ​

Deploys the active configuration again, optionally with another image. The body is optional:

json
{ "image": "ghcr.io/company/my-api:1.5.0" }
FieldType
imagestringOptional. Replaces the image of the active configuration. Must be a valid image reference. For an application with build:, only an image under shipwick.local/<name> is accepted; without one, the image it has is kept. Since 0.10 an image under shipwick.local must be the application's own whatever the configuration: another application's is 400 INVALID_REQUEST, with the application it belongs to.

The body is limited to 4096 bytes. Unknown fields are rejected: a typo such as "imgae" must not quietly redeploy the old image. A static application re-uses the folder the proxy serves.

StatusBody
202Deployment with kind: "redeploy", and a Location header
400 INVALID_REQUESTInvalid JSON, unknown field, or invalid image; an image from elsewhere for an application with build:; since 0.10 an image under shipwick.local that is another application's
400 INVALID_CONFIGA hostname or a published port of the stored configuration is now held by something else
404 NOT_FOUNDUnknown application
409 NOT_DEPLOYEDNo active deployment
409 DEPLOYMENT_IN_PROGRESSAnother operation holds the application
413 INVALID_REQUESTBody larger than 4 KB; the message names the limit. Since 0.10 (400 before)
503 RUNTIME_UNAVAILABLEThe agent is shutting down

POST /applications/:name/rollback ​

Deploys the configuration of an earlier successful deployment. The body is optional:

json
{ "deployment_id": 12 }
FieldType
deployment_idintegerOptional. The id (not the sequence) of the deployment to return to. It must belong to this application and have the status SUPERSEDED. Omitted or 0: the most recent SUPERSEDED deployment.

The body is limited to 4096 bytes. Unknown fields are rejected.

StatusBody
202Deployment with kind: "rollback" and source_deployment_id set, and a Location header
400 INVALID_REQUESTInvalid JSON, unknown field, or a negative deployment_id
413 INVALID_REQUESTBody larger than 4 KB; the message names the limit. Since 0.10 (400 before)
400 INVALID_CONFIGA hostname or a published port of the stored configuration is now held by something else
404 NOT_FOUNDUnknown application, or no deployment with that id
409 NOT_DEPLOYEDNo active deployment
409 NO_ROLLBACK_TARGETNo earlier successful deployment; or the requested one is active, never succeeded, or belongs to another application
409 DEPLOYMENT_IN_PROGRESSAnother operation holds the application
503 RUNTIME_UNAVAILABLEThe agent is shutting down
bash
curl -X POST …/applications/my-api/redeploy -d '{"image": "ghcr.io/company/my-api:1.5.0"}'
curl -X POST …/applications/my-api/rollback                      # most recent successful version
curl -X POST …/applications/my-api/rollback -d '{"deployment_id": 12}'

Redeploy and rollback answer exactly like deploy because both are deployments. They differ only in where the configuration comes from: the server's own record of an earlier deployment. That is also why they exist as endpoints at all. The API only ever returns configurations with environment values masked, so no client could re-submit one.

POST /applications/:name/stop ​

Stops all replicas of the active deployment. The application stays stopped (desired_state: "stopped") until it is started or deployed again. The route goes to a static 503 first, so the domain and its aliases answer 503 while redirects keep working, and the containers receive SIGTERM second, with SIGKILL after the application's deploy.stop_timeout (10 seconds unless set); their names on the services network go with them. Scheduled jobs do not run while the application is stopped. The request returns when the replicas have stopped.

StatusBody
200ApplicationDetail, as after the stop
404 NOT_FOUNDUnknown application
409 NOT_DEPLOYEDNo active deployment
409 DEPLOYMENT_IN_PROGRESSAnother operation holds the application

The application event reads Application stopped, or Application stopped by ci when the token was not the root token.

POST /applications/:name/start ​

Starts the replicas of a stopped application and clears their restart history.

StatusBody
200ApplicationDetail, as after the start. Health is not known yet at that moment.
404 NOT_FOUNDUnknown application
409 NOT_DEPLOYEDNo active deployment
409 DEPLOYMENT_IN_PROGRESSAnother operation holds the application
500 INTERNAL_ERRORA container no longer exists; the message says to deploy the application again

DELETE /applications/:name ​

Removes every container of the application, then the application itself together with its deployment history and events. Volumes are kept. The containers are stopped gracefully, so the request may take as long as the application's deploy.stop_timeout.

StatusBody
204None
404 NOT_FOUNDUnknown application
409 DEPLOYMENT_IN_PROGRESSAnother operation holds the application

GET /applications/:name/logs ​

Logs of the replicas of the active deployment.

ParameterDefault
tail100Number of lines. 1 to 5000 without follow; 0 to 5000 with it.
followfalsetrue answers with a live stream. See Following logs.
sinceSince 0.9, with follow=true only: a time in RFC 3339. The stream begins with every line logged at or after it, tail not applied, then follows: how a client that lost the stream takes it up where it left off. See Following logs.
StatusBody
200Without follow: array of LogLine, merged across replicas in chronological order. With follow: an NDJSON stream, with the header X-Shipwick-Log-Since when since was honoured.
400 INVALID_REQUESTInvalid tail or follow; since that is not a time in RFC 3339, or since without follow=true — lines of a time are what logs/search finds
404 NOT_FOUNDUnknown application
409 NOT_DEPLOYEDNo active deployment
409 STATIC_APPLICATIONThe proxy serves this application from a folder; it has no containers and no logs. The metrics, the metrics history, the jobs and run answer the same.

Without follow, tail=N is the merged total: the last N lines across all replicas. With follow=true it applies per replica.

GET /applications/:name/logs/archive ​

Since 0.7. The agent keeps the last output of every container whose run ended — a replica that crashed, was restarted, stopped or replaced, the replicas of a deployment that failed, a run of a job or a command — for SHIPWICK_LOG_RETENTION_DAYS and within SHIPWICK_LOG_RETENTION_SIZE. This endpoint lists the entries, newest first and without their lines. See Find out why it died.

ParameterDefault
kindbothreplica or run
deploymentallOnly the entries of this deployment, by its id
replicaallOnly the entries of this replica
runallOnly the entry of this run, by its id
limit501 to 500
beforenoneThe id of an entry: the list continues after it
StatusBody
200Array of LogArchiveEntry
400 INVALID_REQUESTAn invalid parameter
404 NOT_FOUNDUnknown application
json
{
  "data": [
    {
      "id": 41,
      "application": "my-api",
      "kind": "replica",
      "deployment_id": 12,
      "sequence": 3,
      "version": "1.4.2",
      "replica": 2,
      "job": "",
      "run_id": null,
      "container": "shipwick_my-api_3_2",
      "reason": "crashed",
      "exit_code": 1,
      "oom_killed": false,
      "ended_at": "2026-10-03T23:18:58.930797736Z",
      "first_line_at": "2026-10-03T23:18:53.929370317Z",
      "last_line_at": "2026-10-03T23:18:58.929928842Z",
      "lines": 153,
      "bytes": 20311,
      "stored_bytes": 3100,
      "truncated": false
    }
  ]
}

reason of a replica:

reason
crashedThe process exited by itself with a code other than 0
exitedThe process exited by itself with code 0
oom_killedKilled for exceeding its memory limit
unhealthyRestarted by the agent after failing its health check
stoppedThe application was stopped
replacedA newer deployment took its place
deployment_failedA replica of a deployment that failed, removed with it; exit_code and oom_killed say whether it had died by itself
removedRemoved for another reason: a leftover, a rollback that failed
restartedThe run ended while no agent was running, and the container was running again when one started; why it ended is not known

For a run, reason is the run's status: succeeded, failed, timed_out or interrupted. An entry with lines: 0 is a replica that died without printing anything.

Nothing of what the three log archive endpoints return is written to the agent's log, to events or to the audit trail; the request log holds the path, not the query. Deleting an application removes its entries and their files. An agent older than 0.7 answers all three 404 ENDPOINT_NOT_FOUND.

GET /applications/:name/logs/archive/:id ​

Since 0.7. One entry with its lines, oldest first.

ParameterDefault
tailallKeep the last n lines: 1 to 10000
StatusBody
200LogArchiveDetail
400 INVALID_REQUESTAn invalid :id or tail
404 NOT_FOUNDUnknown application; an entry that does not exist, belongs to another application, or has aged out
json
{
  "data": {
    "id": 41,
    "application": "my-api",
    "kind": "replica",
    "…": "the entry's fields, as in the list",
    "output": [
      {"replica": 2, "container": "shipwick_my-api_3_2", "stream": "stderr", "time": "2026-10-03T23:18:58.929928842Z", "message": "panic: connection refused"}
    ]
  }
}

Since 0.7. Looks through the archive and through the logs of the replicas that exist, from where their last archived run ended, so that no line is found twice.

ParameterDefault
qevery lineText to look for inside lines, whatever its case; at most 256 bytes, one line
since, untilno limitOnly lines at or after, at or before, a time in RFC 3339
deployment, replica, runallOnly the output of that deployment (its id), replica or run. With run, and with a deployment that is not the active one, only the archive is read
limit200Lines in one answer, at most 1000
cursornoneThe next of the answer this one continues
StatusBody
200LogSearchResult
400 INVALID_REQUESTA q that is too long or has a line break, a time that is not RFC 3339, until before since, a cursor no answer returned
404 NOT_FOUNDUnknown application; a deployment of another one
json
{
  "data": {
    "lines": [
      {
        "replica": 1,
        "container": "shipwick_my-api_4_1",
        "stream": "stdout",
        "time": "2026-10-03T23:19:03.850907531Z",
        "message": "dial tcp 10.0.0.5:5432: connect: connection refused",
        "archive_id": null,
        "deployment_id": 14,
        "sequence": 4,
        "job": "",
        "run_id": null
      },
      {
        "replica": 2,
        "container": "shipwick_my-api_3_2",
        "stream": "stderr",
        "time": "2026-10-03T23:18:58.929928842Z",
        "message": "panic: connection refused",
        "archive_id": 41,
        "deployment_id": 12,
        "sequence": 3,
        "job": "",
        "run_id": null
      }
    ],
    "next": "a41.151",
    "sources": 3,
    "bytes": 21544
  }
}
  • A line is a LogLine with where it comes from: archive_id is the entry that holds it, null for a line read from a container that exists.
  • The order is by source, newest first, and within a source by time, newest first: the replicas that exist, from the highest index down, then the archive's entries from the newest to the oldest. Read backwards, an answer is in the order things were printed in each container.
  • next is "" when everything the question admits has been looked at. Otherwise the search goes on with cursor=<next> and the same other parameters. An answer is bounded twice — by limit, and by how much it reads, about 128 MB of output — so a page can hold fewer lines than limit, none included, and still have a next: keep asking until it is empty.
  • sources and bytes are how many containers' output this request read and how much of it.
  • Of a container that exists, its last 50,000 lines are looked at. The container of a job that is still running is not searched; its output is in the archive when the run has ended.

GET /applications/:name/events ​

The application's own feed, newest first: crashes, restarts, health changes, recreated replicas, stops and starts, restored volumes, replaced containers that had to be killed, certificates being obtained or running out, alerts, backups that failed and verifications, and scheduled jobs or one-off commands that failed or timed out. Only the newest 500 per application are kept.

ParameterDefault
limit501 to 500
StatusBody
200Array of Event
400 INVALID_REQUESTInvalid limit
404 NOT_FOUNDUnknown application
json
{ "id": 91, "deployment_id": null, "level": "warn", "type": "supervisor",
  "message": "Replica 2 exited with code 137; restarting in 2s", "created_at": "2026-03-01T10:00:00Z" }

The probe event of a deployment, since 0.9, is not in this feed either; it belongs to its deployment, see Deployment events. type is supervisor, app (stops, starts and restored volumes: Application stopped by ci, Volume data restored from a backup (12.5 MB)) or job (a run that went wrong, with level: "warn": Job nightly-report failed (exit 1), Job nightly-report timed out after 1h, Command pg_dump failed (exit 1)). A run that succeeds records nothing. Two more types exist: alert, an alert about the application, with level warn or error when it is raised and info when it is cleared; and backup, a backup that failed (Backup #12 failed: …), a verification either way, and an application that was stopped for a backup and started again. Backups that succeed record nothing.

A replaced container that did not exit within its deploy.stop_timeout and was killed is an app event at level warn: The replaced container shipwick_my-api_6_1 did not exit within 10s of SIGTERM and was killed. To let it finish its requests, handle SIGTERM in the application; to give it longer, set deploy.stop_timeout.

Deployment events are not in this feed. They belong to their deployment and are returned by GET /deployments/:id.

GET /applications/:name/metrics ​

A point-in-time sample of CPU and memory of the application and each replica of its active deployment.

StatusBody
200Metrics
404 NOT_FOUNDUnknown application
409 NOT_DEPLOYEDNo active deployment
json
{
  "data": {
    "application": "my-api", "collected_at": "2026-03-01T10:00:00Z",
    "cpu_percent": 42.1, "cpu_limit_percent": 400,
    "memory_bytes": 432013312, "memory_limit_bytes": 2147483648,
    "replicas": [
      { "replica": 1, "container": "shipwick_my-api_7_1",
        "cpu_percent": 21.0, "cpu_limit_percent": 200,
        "memory_bytes": 216006656, "memory_limit_bytes": 1073741824 }
    ]
  }
}
  • CPU is in percent of one core, as in docker stats: a replica keeping two cores busy reads 200, and cpu: 2 is a cpu_limit_percent of 200.
  • Memory is the working set: usage minus the page cache the kernel would give back. It is what the limit is enforced against.
  • Limits are 0 when unlimited. Application-level numbers are sums over the replicas.
  • unenforced_limits, since 0.8, is present when the server's Docker has no cgroup controller for a limit — rootless Docker without delegation — and lists which: ["memory", "cpu"]. The limits are then what deploy.yaml asks for and nothing holds a replica to; with both listed on a rootless daemon, the usage is that of everything the daemon runs, not the replica's. [] where Docker applies the limits (an agent before 0.10 left the field out then); absent from an agent older than 0.8. See Limits that are not enforced.
  • A replica that is not running reports zeros. It never fails the request.
  • It is a point-in-time sample; the record over time is the history. The agent keeps the previous sample of each container, so polling every few seconds is answered instantly. A first request, or one after a pause of a minute, takes about a second: CPU usage is a rate, and Docker needs two readings for it.

See Resource limits and metrics.

GET /applications/:name/metrics/history ​

The sampled CPU and memory of each replica over a window, aggregated into steps.

ParameterDefault
since1h1h, 24h or 7d. Anything else is 400 INVALID_REQUEST: since must be 1h, 24h or 7d.
StatusBody
200MetricsHistory
400 INVALID_REQUESTInvalid since
404 NOT_FOUNDUnknown application
409 NOT_DEPLOYEDNo active deployment
json
{
  "data": {
    "application": "my-api", "since": "2026-03-01T09:00:00Z", "step_seconds": 30,
    "series": [
      { "replica": 1, "points": [
          { "at": "2026-03-01T09:00:00Z", "cpu_percent": 12.5, "memory_bytes": 216006656 },
          { "at": "2026-03-01T09:00:30Z", "cpu_percent": 14.0, "memory_bytes": 216268800 }
      ] },
      { "replica": 2, "points": [ … ] }
    ],
    "limits": { "cpu": 1, "memory_bytes": 1073741824 }
  }
}
  • The agent picks step_seconds for the window: 30 for 1h, 300 for 24h, 3600 for 7d, so a series is at most a few hundred points. Since 0.10 the field is step_seconds, an integer, as in Traffic; an agent before 0.10 sends step as "30s", "5m" or "1h".
  • The agent samples every running replica every 30 seconds and keeps seven days. Each point aggregates the samples of one step: cpu_percent is their average, memory_bytes their peak. A step in which a replica has no sample, because it was not running or the agent was down, has no point: the series are sparse, not zero-filled. at is the start of the step, since the start of the window.
  • limits are the active deployment's per-replica limits as written in deploy.yaml: cpu in cores, memory_bytes in bytes, 0 when unlimited. A limit line for a CPU chart is cpu × 100.
  • Units are those of Metrics. An application that was just deployed answers with empty series until the first minute has passed.

GET /applications/:name/traffic ​

What the proxy's access log says about the application's requests over a window.

ParameterDefault
since1h1h, 24h or 7d
StatusBody
200Traffic
400 INVALID_REQUESTInvalid since
404 NOT_FOUNDUnknown application
409 TRAFFIC_UNAVAILABLEThere is no access log to read: the agent has no proxy, or the proxy is not the caddy container of the agent's compose project
json
{
  "data": {
    "application": "my-api", "since": "2026-03-01T09:00:00Z", "step_seconds": 60,
    "totals": {
      "requests": 12480, "status_2xx": 12300, "status_3xx": 40, "status_4xx": 120, "status_5xx": 20,
      "bytes": 123456789, "p50_ms": 12.4, "p95_ms": 48, "p99_ms": 210.5
    },
    "points": [
      { "at": "2026-03-01T09:00:00Z",
        "requests": 208, "status_2xx": 205, "status_3xx": 1, "status_4xx": 2, "status_5xx": 0,
        "bytes": 2057600, "p50_ms": 11.9, "p95_ms": 45.2, "p99_ms": 180 }
    ]
  }
}
  • The agent picks the step for the window: 60 seconds for 1h, 300 for 24h, 3600 for 7d, so a series is at most a few hundred points. The window starts on a step boundary, so since is up to one step earlier than asked.
  • A request belongs to the application whose domain, alias or redirect it was sent to; where several applications share a hostname by path, to the one with the longest path the request is under. Requests the proxy answered by itself count too: a redirect's 308, the 503 of a stopped application, the files of a static one. Requests for the agent's and the dashboard's own hostnames are not recorded.
  • bytes are response bodies as sent, after compression. Statuses outside 200–599 are in requests only.
  • The percentiles are estimated from a histogram of the proxy's durations, from the first byte of the request to the last of the response, with bounds at 1, 2.5, 5, 10, 25, 50, 100, 250, 500 ms and 1, 2.5, 5, 10, 30 s, and are as exact as a bucket is wide; a request slower than 30 s reads 30000. They are 0 when there were no requests.
  • at is the start of the step, as in a point of the metrics history; an agent before 0.10 names it t. A step without a request has no point: the series is sparse, and a missing point is zero. The current minute is included; minutes that have ended are kept for seven days.
  • An application without a domain, or one nobody has asked anything of, answers zero totals and no points.

See shipwick traffic.

GET /applications/:name/requests ​

The application's most recent requests as the proxy logged them, oldest first.

ParameterDefault
tail501 to 200, which is all the agent keeps per application
StatusBody
200Array of Request
400 INVALID_REQUESTInvalid tail
404 NOT_FOUNDUnknown application
409 TRAFFIC_UNAVAILABLEAs for traffic
json
{
  "data": [
    { "time": "2026-03-01T10:00:00.412365Z", "method": "GET", "path": "/api/users",
      "status": 200, "duration_ms": 12.431, "bytes": 2048, "client": "203.0.113.7" }
  ]
}

The requests are kept in memory, so the list starts empty after an agent restart. path carries no query string, and nothing of the request's or the response's headers is kept: the proxy does not write them to its log in the first place. client is the address the proxy saw. Requests are attributed to applications as for traffic.

GET /applications/:name/volumes ​

The volumes of the active deployment, as it mounts them.

StatusBody
200Array of Volume; empty when the configuration has no volumes
404 NOT_FOUNDUnknown application
409 NOT_DEPLOYEDNo active deployment
json
{ "data": [ { "name": "data", "path": "/var/lib/postgresql/data" } ] }

GET /applications/:name/volumes/:volume/archive ​

The volume's contents as a tar archive. The body is the archive, without the data envelope.

StatusBody
200The archive, Content-Type: application/x-tar, with Content-Disposition: attachment; filename="<app>-<volume>-<UTC yyyymmdd-hhmmss>.tar"
400 INVALID_REQUESTInvalid volume name
404 NOT_FOUNDUnknown application, or the active deployment mounts no volume by that name
409 NOT_DEPLOYEDNo active deployment
409 DEPLOYMENT_IN_PROGRESSAnother operation holds the application
bash
curl -H "Authorization: Bearer $SHIPWICK_AGENT_TOKEN" -OJ \
  http://localhost:9000/api/v1/applications/postgres/volumes/data/archive
  • The archive is streamed as it is read from the replica's container, running or stopped; the copy of a database that is being written to is not guaranteed consistent. The entries are the volume's contents relative to its mount point (base/…, not data/base/…).
  • The application is locked while the archive streams, so a deployment asked for meanwhile is 409 DEPLOYMENT_IN_PROGRESS.
  • Problems found before the first byte (unknown application or volume, busy) are regular JSON errors. After that, a cut connection is the only signal left. A write that stalls for 60 seconds ends the response.

PUT /applications/:name/volumes/:volume/archive ​

Replaces the volume's contents with the tar archive in the body. The application must be stopped.

bash
curl -X PUT -H "Authorization: Bearer $SHIPWICK_AGENT_TOKEN" -H "Content-Type: application/x-tar" \
  --data-binary @postgres-data-20260927-153000.tar \
  http://localhost:9000/api/v1/applications/postgres/volumes/data/archive
StatusBody
204None. The application event Volume data restored from a backup (12.5 MB) is recorded.
400 INVALID_REQUESTInvalid volume name; the body is not Content-Type: application/x-tar; the body does not start with a tar header
404 NOT_FOUNDUnknown application, or the active deployment mounts no volume by that name
409 NOT_DEPLOYEDNo active deployment
409 APPLICATION_RUNNINGThe application is not stopped, or a replica's container is still running
409 DEPLOYMENT_IN_PROGRESSAnother operation holds the application
413 INVALID_REQUESTThe archive is larger than 10 GB. Refused before anything is touched when the request says its Content-Length; a chunked upload that grows past the limit fails mid-restore.
  • The body is checked for a tar header before anything is removed. Then the replica container is removed, the volume with it, and both are created again before the archive is extracted into the mount point: what the archive does not name is gone. What the archive contains is not checked.
  • The application stays stopped; POST …/start brings it back.
  • The upload has no overall timeout; a read that stalls for 60 seconds ends it.

Listing volumes needs the read role; both archive endpoints need admin: a backup carries the application's data, a restore replaces it. See Back up and restore volumes.

GET /applications/:name/backups ​

Where the two archive endpoints above hand an archive to the caller, this and the following endpoints are about the backups the agent takes and keeps itself: on the schedule under backups in deploy.yaml, or on request. A backup is one run. This endpoint lists them, newest first.

ParameterDefault
limit501 to 500
StatusBody
200Array of BackupRun
400 INVALID_REQUESTInvalid limit
404 NOT_FOUNDUnknown application
json
{ "id": 12, "trigger": "schedule", "status": "succeeded",
  "started_at": "2026-03-01T03:00:00Z", "completed_at": "2026-03-01T03:00:41Z",
  "volumes": [{ "volume": "data", "size_bytes": 2254857830 }],
  "destinations": ["local", "s3"], "encrypted": true, "error": "",
  "activity": "", "verified_at": "2026-03-01T09:12:00Z", "verify_error": "",
  "restored_at": null, "restore_error": "" }

trigger is schedule, manual, or adopted for a backup that was recorded from its files. status is running, succeeded or failed; a failed backup has error set, empty volumes and destinations, and no files anywhere. size_bytes is the tar archive's size, before encryption. destinations lists where it went, of local (the agent's backup directory) and s3; encrypted says whether it was written with the agent's passphrase. activity is verify or restore while one of them is in progress and "" otherwise. verified_at is when the backup last proved to restore and verify_error why its last verification failed; one of them at most is set, and the same goes for restored_at and restore_error.

GET /applications/:name/backups/:id ​

One backup. :id must be a positive integer.

StatusBody
200BackupRunDetail: the backup and verify_output, the last 200 lines (64 KB) the verification's container wrote
400 INVALID_REQUEST:id is not a positive number
404 NOT_FOUNDUnknown application, or no backup with that id belongs to it

POST /applications/:name/backups ​

Takes a backup now. No body. It works without a backups block in deploy.yaml; with one, its before command runs first, for at most before_timeout ("1h0m0s" in the stored configuration unless set; an older deployment has no such field, and an hour), and stop is honoured. Since 0.7 before_in says where the command runs: absent from the stored configuration, inside the replica, where the command is not ended at the limit (error: backups.before did not finish within 1h; the backup was given up …); "container", in a container of its own beside the replica, which is stopped and removed at the limit (… did not finish within 1h and was stopped; …).

StatusBody
202BackupRun with status: "running", and a Location header naming the backup: /api/v1/applications/postgres/backups/13. Poll it until completed_at is set.
404 NOT_FOUNDUnknown application
409 NOT_DEPLOYEDNo active deployment
409 NO_VOLUMESThe application has no volumes
409 DEPLOYMENT_IN_PROGRESSAnother operation holds the application
409 BACKUP_NOT_USABLEThe agent was started without anywhere to keep backups

The application is held until the archives are written: other operations get 409 DEPLOYMENT_IN_PROGRESS, as during a deployment, and wait up to 30 seconds instead when the backup was started by the schedule. A failed backup adds an event of type: "backup" to the application's feed; a failed scheduled one is also sent to the webhook as backup.failed.

POST /applications/:name/backups/:id/verify ​

Proves that a backup restores: the agent restores it into scratch volumes, starts one container of the application's current image on them and holds it to the application's health check, as a deployment holds a new replica; without a health check, to staying up for the stabilization window. The container and the volumes are removed either way, and the application is not touched. :id may be latest: the newest successful backup.

StatusBody
202BackupRun with activity: "verify", and a Location header naming the backup. Poll it until activity is empty, then read verified_at or verify_error.
400 INVALID_REQUEST:id is neither a positive number nor latest
404 NOT_FOUNDUnknown application or backup; latest when there is no successful backup
409 BACKUP_NOT_USABLEThe backup failed, so nothing was kept of it; or its files do not decrypt with the agent's passphrase
409 BACKUP_BUSYThe backup is still running, or being verified or restored

A verification adds an event of type: "backup" to the application's feed whether it succeeds or not.

POST /applications/:name/backups/:id/restore ​

Replaces the application's volumes with the backup's archives, one after the other. As with PUT …/archive, the application must be stopped and stays stopped, and each restored volume adds the same application event.

StatusBody
202BackupRun with activity: "restore", and a Location header naming the backup. Poll it until activity is empty, then read restored_at or restore_error.
400 INVALID_REQUEST:id is not a positive number
404 NOT_FOUNDUnknown application or backup; the backup holds a volume the active deployment no longer mounts
409 APPLICATION_RUNNINGThe application is not stopped
409 BACKUP_NOT_USABLEThe backup failed, or does not decrypt
409 BACKUP_BUSYThe backup is still running, or being verified or restored

GET /applications/:name/backups/:id/volumes/:volume/archive ​

One volume of a backup as a tar archive, decrypted. The body is the archive, streamed like GET …/volumes/:volume/archive.

StatusBody
200The archive, Content-Type: application/x-tar, with Content-Length set to its size and Content-Disposition: attachment; filename="<app>-<volume>-backup-<id>.tar"
400 INVALID_REQUEST:id is not a positive number; invalid volume name
404 NOT_FOUNDUnknown application, backup or volume
409 BACKUP_NOT_USABLEThe backup failed; or it does not decrypt, when that shows in its first chunk
409 BACKUP_BUSYThe backup is still running, or being verified or restored

A backup that turns out not to decrypt later in the stream ends the connection short of Content-Length.

DELETE /applications/:name/backups/:id ​

Removes the backup's files from the directory and the bucket, then its record.

StatusBody
204None
400 INVALID_REQUEST:id is not a positive number
404 NOT_FOUNDUnknown application or backup
409 BACKUP_BUSYThe backup is still running, or being verified or restored

GET /applications/:name/jobs ​

The scheduled jobs of the active deployment, each with its last run and the next time its schedule fires.

StatusBody
200Array of Job; empty when the configuration has no jobs
404 NOT_FOUNDUnknown application
409 NOT_DEPLOYEDNo active deployment
json
{
  "data": [
    { "name": "nightly-report", "schedule": "0 3 * * *", "command": ["node", "report.js"], "timeout": "1h0m0s",
      "last_run": { "id": 42, "application": "my-api", "job": "nightly-report", "kind": "scheduled",
                    "command": ["node", "report.js"], "status": "failed", "exit_code": 1, "deployment_id": 7,
                    "started_at": "2026-03-01T03:00:00Z", "finished_at": "2026-03-01T03:00:12Z" },
      "next_run_at": "2026-03-02T03:00:00Z" }
  ]
}

Schedules are read in UTC and next_run_at is UTC. last_run is null until the job has run, next_run_at is null while the application is stopped, since a stopped application runs no jobs.

GET /applications/:name/runs ​

Runs of the application, newest first, without their output. A run is one execution of a one-off container from the application's image, with its environment and limits and without its volumes: the pre-deploy hook of a deployment (kind: "hook", job pre-deploy), a scheduled job (kind: "scheduled") or a command started by hand (kind: "manual": the job's name for jobs/:job/run, run for a one-off command).

ParameterDefault
joball jobsLimit the list to one job: a job's name, pre-deploy or run. Must be a valid job name.
limit501 to 500
StatusBody
200Array of Run
400 INVALID_REQUESTInvalid job or limit
404 NOT_FOUNDUnknown application

The agent keeps the last 50 runs of each job.

GET /applications/:name/runs/:id ​

One run with its output. :id must be a positive integer.

StatusBody
200RunDetail
400 INVALID_REQUEST:id is not a positive number
404 NOT_FOUNDUnknown application, or no run with that id belongs to it

output is the last 200 lines the container wrote, at most 64 KB, joined with newlines. Poll this endpoint until finished_at is set, then read status and exit_code.

POST /applications/:name/jobs/:job/run ​

Starts a scheduled job now, as the schedule would. No body.

StatusBody
202RunDetail with status: "running" and an empty output, and a Location header naming the run: /api/v1/applications/my-api/runs/43
400 INVALID_REQUESTInvalid job name
404 NOT_FOUNDUnknown application, or the active deployment has no job by that name
409 NOT_DEPLOYEDNo active deployment
409 JOB_ALREADY_RUNNINGAn earlier run of this job is still going. The schedule skips such firings too.
409 DEPLOYMENT_IN_PROGRESSAnother operation holds the application
503 RUNTIME_UNAVAILABLEThe agent is shutting down

The application's lock is taken only to record the run against the active deployment; it is released while the container runs, so the application stays deployable and stoppable meanwhile. Poll the Location until finished_at is set.

POST /applications/:name/run ​

Runs a one-off command in a fresh container from the active deployment's image, with its environment, limits and network, and without its volumes.

json
{ "command": ["rails", "db:migrate"] }
FieldType
commandarray of stringsRequired. Validated like a command in deploy.yaml: non-empty, at most 256 strings, each at most 4096 bytes and without NUL bytes. Handed to the container as its argv, never to a shell.

The body is limited to 4096 bytes. Unknown fields are rejected.

StatusBody
202RunDetail with job: "run", kind: "manual", status: "running", and a Location header naming the run
400 INVALID_REQUESTMissing or invalid command, invalid JSON, unknown field, body too large
404 NOT_FOUNDUnknown application
409 NOT_DEPLOYEDNo active deployment
409 DEPLOYMENT_IN_PROGRESSAnother operation holds the application
503 RUNTIME_UNAVAILABLEThe agent is shutting down

Commands are independent of one another: two may run at the same time. A command is stopped after one hour. A failed or timed-out run adds an event of type: "job" to the application's feed; a successful one records nothing. See Run scheduled jobs and one-off commands.

GET /deployments ​

Deployment history, newest first.

ParameterDefault
applicationall applicationsLimit the list to one application. Must be a valid application name.
limit501 to 500
StatusBody
200Array of Deployment
400 INVALID_REQUESTInvalid application or limit
404 NOT_FOUNDapplication names an unknown application

GET /deployments/:id ​

One deployment with its configuration (environment values masked) and its events. :id must be a positive integer.

StatusBody
200DeploymentDetail
400 INVALID_REQUEST:id is not a positive number
404 NOT_FOUNDUnknown deployment

GET /tokens ​

The stored tokens, oldest first, without their values or hashes. The root token is not listed: it is configured on the agent, not stored.

StatusBody
200Array of Token
json
{ "data": [
  { "id": 3, "name": "ci", "role": "deploy", "created_at": "2026-03-01T10:00:00Z",
    "last_used_at": "2026-03-01T10:42:00Z",
    "applications": ["my-api", "web"], "expires_at": "2027-01-01T00:00:00Z" }
] }

last_used_at is null until the token is first used, and is then kept to the minute: it says whether a token is still in use, not what it did last; a request refused because the token had expired is not a use. applications is empty for a token that is not limited, expires_at is null for one that does not expire. A token whose expires_at has passed stays listed until it is revoked.

POST /tokens ​

Creates a token. The value is in this response and nowhere else: the agent stores its SHA-256 and nothing else.

json
{ "name": "ci", "role": "deploy" }

Two optional fields narrow the token:

json
{ "name": "ci", "role": "deploy",
  "applications": ["my-api", "web"], "expires_at": "2027-01-01T00:00:00Z" }
FieldType
namestringRequired. Lowercase letters, digits and dashes, starting and ending with a letter or digit, at most 40 characters. Unique; root is taken.
rolestringRequired. read, deploy or admin.
applicationsarray of stringsOptional. Limits a deploy token to those applications, see Authentication: one to 50 application names, which need not exist yet. With another role it is 400.
expires_attimestampOptional. An RFC 3339 time in the future, after which the token is 401 TOKEN_EXPIRED. A time that has passed is 400.

The body is limited to 4096 bytes. Unknown fields are rejected. Since 0.7 applications and expires_at can be changed afterwards with PUT /tokens/:name. An agent before 0.6 answers a request with either field 400 INVALID_REQUEST, unknown field, and creates nothing.

StatusBody
201CreatedToken
400 INVALID_REQUESTMissing or invalid name or role; applications with a role other than deploy, with a name that is not an application name, or with more than 50 of them; an expires_at that has passed; invalid JSON, unknown field, body too large
409 TOKEN_EXISTSA token with that name exists
json
{
  "data": {
    "id": 3, "name": "ci", "role": "deploy", "created_at": "2026-03-01T10:00:00Z",
    "token": "swk_Xk3nM9…", "applications": [], "expires_at": null
  }
}

The answer carries applications sorted, each once. Values are 32 random bytes in unpadded base64url behind the prefix swk_, which is not part of the secret; it exists so that a token is recognizable where it must not be, such as a log or a repository.

PUT /tokens/:name ​

Since 0.7. Changes what the body names and leaves the rest. The value and the role do not change.

bash
curl -X PUT …/tokens/ci -d '{"applications": ["my-api", "web", "worker"]}'
curl -X PUT …/tokens/ci -d '{"applications": []}'                      # lifts the limit
curl -X PUT …/tokens/ci -d '{"expires_at": "2027-04-01T00:00:00Z"}'
curl -X PUT …/tokens/ci -d '{"never_expires": true}'
FieldType
applicationsarray of stringsReplaces the list the token is limited to; [] lifts the limit. Checked as on POST /tokens: valid names, at most 50, and only for a deploy token
expires_attimestampMoves the end; it must be in the future. A token that has expired works again from its next request
never_expiresbooleantrue takes the end away. Not together with expires_at
StatusBody
200Token, as GET /tokens lists it
400 INVALID_REQUESTA body that names none of the three; expires_at together with never_expires; an expires_at that has passed; applications on a token that is not a deploy token, or names that are not application names, or more than 50; an unknown field, the role and the value among them; :name is root
404 NOT_FOUNDNo token by that name

The change holds from the token's next request. In the audit trail the action is token.update, the target the token, and the detail what changed, as it was and as it is: applications my-api -> my-api web worker, applications my-api web -> all, expires 2026-10-02T12:00:00Z -> 2027-04-01T00:00:00Z, expires … -> never, or nothing changed. An agent before 0.7 has no PUT on this path and changes nothing.

DELETE /tokens/:name ​

Revokes a token. Requests with it are 401 from then on. A token may revoke itself.

StatusBody
204None
400 INVALID_REQUEST:name is root (the root token is changed on the agent, not here), or not a valid token name
404 NOT_FOUNDNo token by that name

GET /audit ​

Every request that changes something leaves an entry, whatever became of it. This endpoint lists them, newest first.

ParameterDefault
applicationall applicationsMatches exactly
actorall callersA token's name, or the name of a person who signed in. Matches exactly.
actor_kindbothtoken or user. Since 0.7
actionall actionsAn action as listed below, or the start of a family with its dot: token. is token.create, token.update and token.revoke. Several are given by repeating the parameter or separated by commas, at most 20; an entry matches when one of them does. Since 0.7
outcomeall outcomesok, refused, failed; several the same way. Since 0.7
sinceno limitA number of days or hours back (7d, 24h), a date (2026-09-01, from its start in UTC) or an RFC 3339 time
limit501 to 500
beforenoneThe id of the last entry of the page before; the list continues after it.

Each parameter narrows the others.

StatusBody
200Array of AuditEntry, and since 0.7 more next to data
400 INVALID_REQUESTInvalid application, actor, actor_kind, action, outcome, since, limit or before
json
{ "data": [
  { "id": 42, "at": "2026-10-03T17:20:17.276658220Z",
    "actor": { "kind": "token", "name": "ci" },
    "address": "172.18.0.3", "forwarded_for": "203.0.113.40",
    "action": "deploy", "application": "my-api", "target": "",
    "outcome": "ok", "status": 202, "code": "", "detail": "deployment 12" }
], "more": true }

more, since 0.7, says whether entries older than the last one match as well: false on the last page, also when that page is exactly full. An agent before 0.7 leaves it out, and there a page shorter than limit is the only sign of the end. Such an agent does not know actor_kind, action and outcome either, and ignores them: a client that sends one and finds no more in the answer has been given the unfiltered trail.

Field
actorWho made the request: kind is "token" and name the token's name (root for the agent's own), or kind is "user" and name the name of a person who signed in: the e-mail address, or what SHIPWICK_OIDC_NAME_CLAIM names them by
addressWhere the connection came from. Behind the proxy this is the proxy.
forwarded_forThe client address the proxy reported in X-Forwarded-For, "" without one. On a connection that does not come through the proxy the header is the caller's own word, which is why both are kept.
actionWhat was asked for, see below
applicationThe application it was about, "" for what is not about one
targetWhat else the request named: the job, the volume, the backup's id, the secret, the registry, the hostname of a certificate, the token
outcomeok: answered 2xx; for what runs in the background, accepted. refused: 403, the role or the application limit. failed: anything else.
status, codeThe HTTP status of the answer, and the error code of one that was not 2xx
detailWhat was started (deployment 12, run 4, backup 7, export 3), or what was asked for: a created token's role, applications and expiry; the volume of a backup download; stopped and overwrite of an import; the applications of an export

Actions: deploy, redeploy, rollback, stop, start, application.delete, run, job.run, image.upload, static.upload, backup.create, backup.verify, backup.restore, backup.download, backup.delete, server.backup, backup.adopt, volume.download, volume.restore, volume.delete, secret.set, secret.delete, registry.login, registry.logout, certificate.set, certificate.delete, token.create, token.update, token.revoke, key.rotate, export.download (POST /export), export.create (POST /exports), import, standby.pull, standby.promote, audit.export, and signin, signout, access.grant, access.revoke and access.signout, which are described with their endpoints. Every endpoint that is not a GET is recorded, except validate and images/missing, which change nothing; of the GETs, the three that hand data out whole — a volume's archive, a backup's, and the export of this trail — are.

Not recorded: reading; a request without a valid token, which has no actor (it is in the agent's log, and counted by the rate limit); what the agent does on its own, such as scheduled jobs, backups and exports, and restarts by the supervisor. Nothing from a request's body is kept except names: no env, no secret's value, no command, no passphrase.

Entries are kept for a year, and the newest 100,000 at most. An agent before 0.6 answers 404 ENDPOINT_NOT_FOUND. See See who changed what.

GET /audit/export ​

Since 0.7. Streams everything that matches, newest first, as it is read from the database, 500 entries at a time. It takes the filters of GET /audit — application, actor, actor_kind, action, outcome, since — without limit and before, which are 400 here.

ParameterDefault
formatrequiredcsv or json
formatContent-Type
csvtext/csv; charset=utf-8A header row, then one row per entry with the columns below; at in UTC to the second. A cell that begins with =, +, -, @, a tab or a carriage return gets an apostrophe in front, so that a spreadsheet shows it as text instead of running it as a formula
jsonapplication/x-ndjsonOne entry per line, the object GET /audit returns, values as recorded. Nothing matching is an empty body
text
id,at,actor_kind,actor,address,forwarded_for,action,application,target,outcome,status,code,detail
42,2026-10-03T17:20:17Z,token,ci,172.18.0.3,203.0.113.40,deploy,my-api,,ok,202,,deployment 12
41,2026-10-03T17:19:02Z,token,root,172.18.0.3,203.0.113.9,token.revoke,,'=HYPERLINK(…),failed,400,INVALID_REQUEST,
StatusBody
200The stream, not wrapped in data, with Content-Disposition: attachment; filename="shipwick-audit-<time>.csv" (.ndjson)
400 INVALID_REQUESTNo format, or one that is neither; limit or before; an invalid filter

An export that breaks off after its first byte cannot change its status any more: it announces the trailer X-Shipwick-Export-Error and sets it, as POST /export does, and a client must treat a body with that trailer as incomplete. Errors before the first byte are regular error responses.

The export is recorded as audit.export with the format, the filters and the number of entries in detail (csv, action token., since 2026-01-01T00:00:00Z, 214 entries); the entry is written when the export ends and is not part of it. An agent before 0.7 answers 404 ENDPOINT_NOT_FOUND.

GET /auth ​

Says whether people can sign in, and where to send a browser. It takes no token; all of it is public.

StatusBody
200SignInConfig
502 SIGN_IN_UNAVAILABLEThe provider's discovery document cannot be read
json
{ "data": { "configured": true,
            "issuer": "https://accounts.example.com",
            "authorization_endpoint": "https://accounts.example.com/authorize",
            "client_id": "shipwick",
            "scopes": ["openid", "email", "profile"],
            "redirect_uri": "https://dashboard.example.com/auth/callback" } }

Without a provider it answers {"configured": false, …} with the other fields empty. A provider is configured on the agent with SHIPWICK_OIDC_ISSUER, SHIPWICK_OIDC_CLIENT_ID and SHIPWICK_OIDC_CLIENT_SECRET; see Agent configuration. redirect_uri is https:// + SHIPWICK_DASHBOARD_DOMAIN + /auth/callback, from the agent's configuration and never from a request.

The flow is the authorization-code flow with PKCE, and it is the dashboard's server that drives it; the client secret never leaves the agent. The caller generates three random values of 32 bytes each, base64url without padding: state, nonce and the PKCE code_verifier. It keeps them with the browser, and redirects it to authorization_endpoint with response_type=code, client_id, redirect_uri, scope (the scopes joined by spaces), state, nonce, code_challenge (the base64url SHA-256 of the verifier) and code_challenge_method=S256. When the provider sends the browser back with code and state, the caller compares state with what it kept and hands the rest to POST /auth/exchange.

POST /auth/exchange ​

Turns the code the provider sent the browser back with into a session. It takes no token.

http
POST /api/v1/auth/exchange
Content-Type: application/json

{ "code": "…", "code_verifier": "…", "nonce": "…",
  "redirect_uri": "https://dashboard.example.com/auth/callback" }
FieldType
codestringRequired. The one the provider appended to the callback.
code_verifierstringRequired. The PKCE verifier whose S256 challenge went to the provider, 43 to 128 characters.
noncestringRequired. The one sent to the provider, at least 22 characters of base64url.
redirect_uristringRequired. The redirect_uri of GET /auth.
StatusBody
200SignedIn
400 INVALID_REQUESTA field is missing or malformed, or redirect_uri is not the configured one (details: {redirect_uri})
401 SIGN_IN_FAILEDThe sign-in itself was refused; details.reason says why, see below
403 ACCESS_NOT_GRANTEDThe person is who they say, and no rule gives them a role; details: {name, email}, both the person's name (name since 0.7; email is kept for clients from before). The message is written to be forwarded to an admin.
409 SIGN_IN_NOT_CONFIGUREDThe agent has no provider
413 INVALID_REQUESTBody over 16 KB; the message names the limit. Since 0.10 (400 before)
429 RATE_LIMITEDFailed sign-ins count like wrong tokens, see Authentication; a limited address is answered without the provider being asked
502 SIGN_IN_UNAVAILABLEThe provider could not be reached, did not answer like one, calls itself by another issuer, or refused the agent's client id or secret
json
{ "data": { "session": "sws_Zm9v…",
            "identity": { "kind": "user", "name": "[email protected]", "role": "deploy",
                          "applications": ["my-api"], "expires_at": "2026-10-03T19:00:00Z" } } }

session is in this response and nowhere else; the agent keeps its SHA-256. It is presented like a token, Authorization: Bearer sws_….

The agent redeems the code at the provider's token endpoint with the client secret and the verifier, and believes the ID token only if it is signed by one of the provider's keys (RS256 or ES256), was issued by the configured issuer for this client, is within its time and at most ten minutes old, and carries nonce. It accepts each nonce once. An email_verified: false is refused; a provider that does not send the claim is taken at its word. Then the access rules are asked what the person may do.

The person's name — identity.name, the actor in the audit trail, by on a deployment — is the email claim in lowercase, or, since 0.7, the value of the claim the agent is configured with (SHIPWICK_OIDC_NAME_CLAIM; sign_in.name_claim in GET /server), which is kept as the provider wrote it: at most 254 characters of letters, digits and . _ % + ' @ | : = # ~ -. With another claim than email, email_verified is not looked at.

With Microsoft Entra's issuer for several tenants (https://login.microsoftonline.com/organizations/v2.0, or common), whose discovery document names https://login.microsoftonline.com/{tenantid}/v2.0 as its issuer, "issued by the configured issuer" reads, since 0.7: the token's iss is that template with the token's own tid in the placeholder's place, tid is a tenant id, a key that names the issuer it signs for names that one, and tid is among SHIPWICK_OIDC_TENANTS. No other provider's discovery document may name an issuer other than the configured one.

details.reason of SIGN_IN_FAILEDMeaning
code_rejectedThe provider refused the code: used before, expired, issued to another client or for another verifier
invalid_id_tokenSignature, issuer, audience or times
nonce_mismatchThe ID token answers another sign-in
nonce_reusedThis sign-in was completed before
email_missingThe ID token names no usable address
email_not_verifiedThe provider says the address is not verified
name_missingPeople are named by another claim than email, and the ID token lacks it or holds something that cannot be a name; details.claim says which claim. Since 0.7
tenant_not_allowedThe account's tenant is not among SHIPWICK_OIDC_TENANTS. Since 0.7

A session lasts ten hours from the sign-in, whatever its use. It rests on what the rules gave the person then: every request asks the rules again, and a session whose answer has changed is ended with that request, not at its expiry. A session that no longer works says why, to its holder only, like an expired token, and like it not counted by the rate limit:

json
{
  "error": {
    "code": "SESSION_ENDED",
    "message": "no rule on this server gives [email protected] a role any more. An admin grants one with: shipwick access grant [email protected] --role read",
    "details": { "name": "[email protected]", "reason": "rule_removed" }
  }
}

reason is rule_removed, access_changed (the rules give the person something else now: sign in again to get it), signed_out (an admin ended it) or, since 0.7, sign_in_changed (the agent now names people by another claim than when the session began, or no longer accepts the tenant it came from). A session past its time is 401 SESSION_EXPIRED with details: {name, expired_at}. A session nobody issued is a wrong token: 401 UNAUTHORIZED, counted.

A sign-in is recorded in the audit trail as signin: the actor is the person, and the outcome is ok with what they got in detail, or refused with ACCESS_NOT_GRANTED. A signin from a provider with tenants has tenant <id> at the end of its detail. A sign-in the provider did not vouch for has no actor and is not recorded. See Sign in with your company's accounts.

DELETE /auth/session ​

Forgets the session the request is made with. No body.

StatusBody
204None
400 INVALID_REQUESTThe request was made with a token: a token is revoked, not signed out

Recorded in the audit trail as signout.

GET /access/rules ​

Who may sign in, and as what.

StatusBody
200Array of AccessRule
json
{ "data": [
  { "id": 1, "kind": "email",  "subject": "[email protected]", "role": "admin",  "applications": [],
    "created_at": "2026-10-03T09:00:00Z", "created_by": "root" },
  { "id": 2, "kind": "group",  "subject": "backend",         "role": "deploy", "applications": ["my-api", "worker"],
    "created_at": "2026-10-03T09:01:00Z", "created_by": "[email protected]" },
  { "id": 3, "kind": "domain", "subject": "example.com",     "role": "read",   "applications": [],
    "created_at": "2026-10-03T09:02:00Z", "created_by": "root" }
] }
kindsubjectMatches
emailAn address, lowercaseThe person whose name is that address, in any case
groupA group's name as the provider sends it, case and allA person whose groups claim (SHIPWICK_OIDC_GROUPS_CLAIM, groups by default) lists it. Not read where every tenant may sign in (SHIPWICK_OIDC_TENANTS=*)
domainThe part after the @Every name that is an address at exactly that domain; a subdomain is another domain
nameA name as the provider's claim holds it, case and allThe person whose name is exactly that: for names that are not addresses (SHIPWICK_OIDC_NAME_CLAIM). Since 0.7

The name is the email claim unless the agent is configured otherwise; a name that does not read as an address is matched by name and group rules only.

The most specific kind that matches decides, and the others are not looked at: the rule for the name, else the rule for the address, else the rules for the person's groups, else the rule for the domain. A rule for an address can therefore give one person less than their group has. Of several groups the highest role counts; where that is deploy, a group without applications lifts the limit, and the lists of the others add up. Nobody without a matching rule gets in.

POST /access/rules ​

Gives an address, a group, a domain or a name a role: creates the rule, or replaces the one with the same kind and subject.

json
{ "kind": "group", "subject": "backend", "role": "deploy", "applications": ["my-api", "worker"] }
FieldType
kindstringRequired. email, group, domain or, since 0.7, name.
subjectstringRequired. The address, the group's name, the domain or the name; see GET /access/rules.
rolestringRequired. read, deploy or admin.
applicationsarray of stringsOptional. For deploy only, as on a token.
StatusBody
201AccessRule, when the rule was created
200AccessRule, when it replaced the one with the same kind and subject
400 INVALID_REQUESTA missing or invalid kind, subject or role; applications with a role other than deploy; invalid JSON; the 201st rule

At most 200 rules are stored. Rules can be written before a provider is configured. Recorded in the audit trail as access.grant: the target is the subject as the CLI writes it ([email protected], group:backend, *@example.com, name:svc-deploy), the detail the role and applications.

DELETE /access/rules/:id ​

Removes a rule. Sessions that rested on it end with their next request.

StatusBody
204None
400 INVALID_REQUEST:id is not a positive number
404 NOT_FOUNDNo rule with that id

Recorded in the audit trail as access.revoke.

GET /access/sessions ​

Who is signed in right now.

StatusBody
200Array of Session
json
{ "data": [ { "id": 7, "email": "[email protected]", "role": "deploy", "applications": ["my-api"],
              "created_at": "2026-10-03T09:00:00Z", "expires_at": "2026-10-03T19:00:00Z",
              "last_used_at": "2026-10-03T09:41:00Z" } ] }

email is the person's name: the address, or with another name claim what that claim holds. The field keeps its name from when there was only one.

DELETE /access/sessions/:email ​

Ends every session of that person. The path takes the name as GET /access/sessions shows it; an address is brought to lowercase where people are named by email, and any other name must match exactly. It signs out and does not keep out: while a rule covers the person, they can sign in again.

StatusBody
200SignedOut: the number of sessions ended
400 INVALID_REQUEST:email is not an e-mail address, or, where people are named by another claim, not a name
json
{ "data": { "sessions": 2 } }

Recorded in the audit trail as access.signout, with the name as the target.

GET /secrets ​

The secrets stored on the server, by name, without values. A secret is a value for ${NAME} in the env values of a deploy.yaml and in the passwords of its proxy.basic_auth, kept on the server so that no client has to hold it; the agent fills it in when a deployment is recorded. Since 0.9 it belongs to one application or to the whole server. See Placeholders and Keep secrets on the server.

StatusBody
200Array of Secret, by name, the server's before the applications' of the same name
json
{ "data": [
  { "name": "DATABASE_PASSWORD", "application": "", "created_at": "2026-03-01T10:00:00Z",
    "updated_at": "2026-03-01T10:42:00Z" },
  { "name": "DATABASE_PASSWORD", "application": "api", "created_at": "2026-10-11T08:00:00Z",
    "updated_at": "2026-10-11T08:00:00Z" }
] }

application, since 0.9, is always present: "" for the server's. An agent before 0.9 lists no application at all; everything it has is the server's.

PUT /secrets/:name ​

Stores a secret, creating or replacing it.

bash
curl -X PUT …/secrets/DATABASE_PASSWORD -d '{"value": "hunter2"}'
curl -X PUT …/secrets/DATABASE_PASSWORD -d '{"value": "hunter3", "application": "api"}'
FieldType
valuestringRequired. At most 64 KB, not empty, without NUL bytes.
applicationstringSince 0.9. Optional. An application name: the secret is that application's own, and its ${NAME} is answered by it before a server-wide secret of the same name; no other application sees it. The application need not exist. Absent or "": the secret is the server's, which every application without one of its own falls back to, as every secret was before 0.9. The two are different secrets, and (application, name) is what names one.

:name matches ^[A-Za-z_][A-Za-z0-9_]*$ and is at most 64 characters: names are environment variable names. The body is at most 257 KB; unknown fields are rejected. At most 500 secrets are stored, both kinds together.

StatusBody
204None, whether the secret was created or replaced
400 INVALID_REQUESTInvalid name or value, invalid JSON, unknown field, an application that is not an application name, or the 501st secret
413 INVALID_REQUESTBody over 257 KB; the message names the limit. Since 0.10 (400 before)

The value is written encrypted (AES-256-GCM, with the name as additional data for a server-wide secret and applications/<application>/secrets/<name> for an application's, like an env value) and is never returned, logged or repeated in an error. An agent before 0.9 answers a body with application with 400 INVALID_REQUEST (invalid JSON body …) and stores nothing, which is how a client finds out; a query parameter it would have ignored.

DELETE /secrets/:name ​

Removes a secret: the server's, or with ?application=api, since 0.9, the application's own; each leaves the other where it is. Deployments already made keep the value they were started with; the next deploy whose env refers to a name that neither the application nor the server has is refused:

json
{ "error": { "code": "INVALID_CONFIG", "message": "invalid deploy.yaml",
             "details": { "fields": [ {
               "field": "env.DATABASE_URL",
               "message": "refers to ${DATABASE_PASSWORD}, which is not set where shipwick runs and not stored on the server",
               "expected": "shipwick secret set DATABASE_PASSWORD" } ] } } }

expected is the server-wide form of the command, which answers whichever scope the application's other secrets have; --app <application> stores the secret for the application alone.

ParameterDefault
applicationSince 0.9. The application whose own secret is removed; without it, the server's
StatusBody
204None
400 INVALID_REQUESTAn application that is not an application name
404 NOT_FOUNDNo secret by that name in that scope

An agent before 0.9 ignores the parameter and removes the server's secret, so a client that means an application's checks the listing for it first.

GET /registries ​

The registries the agent holds a credential for, by name, without passwords. A credential is what the agent sends when it pulls an image from a private registry.

StatusBody
200Array of Registry
json
{ "data": [
  { "registry": "ghcr.io", "username": "octocat",
    "created_at": "2026-03-01T10:00:00Z", "updated_at": "2026-03-01T10:42:00Z" }
] }

Every pull (a deployment, a rollback, a job, a replica whose image is gone) looks the credential up by the image's registry. Without one, the Docker configuration file on the server is consulted, as before. A pull the registry refuses for authentication fails the deployment with an error that names the command: pull access denied for ghcr.io/company/api: run shipwick registry login ghcr.io (or check the image name). See Pull from private registries.

PUT /registries/:registry ​

Checks a credential against its registry and stores it, creating or replacing it.

bash
curl -X PUT …/registries/ghcr.io -d '{"username": "octocat", "password": "ghp_…"}'
FieldType
usernamestringRequired. At most 255 characters, without a colon or control characters.
passwordstringRequired. At most 16 KB, not empty, without NUL bytes.

:registry is a hostname with an optional port, as image references name it (ghcr.io, registry.example.com:5000), compared in lower case; index.docker.io and registry-1.docker.io are docker.io. Unknown fields are rejected. At most 50 registries are stored.

StatusBody
204None, whether the credential was created or replaced
400 INVALID_REQUESTA scheme or a path in :registry; invalid username or password, invalid JSON, unknown field, or the 51st registry
413 INVALID_REQUESTBody over its limit, 66 KB; the message names the limit. Since 0.10 (400 before)
400 REGISTRY_LOGIN_FAILEDThe registry refused the credential, or could not be asked. Nothing was stored.

Before anything is stored the agent has the Docker daemon check the credential against the registry (the Engine API's login, which keeps nothing). A registry that says no, or that cannot be reached within 30 seconds, is 400:

json
{ "error": { "code": "REGISTRY_LOGIN_FAILED",
             "message": "ghcr.io refused the login: denied: denied",
             "details": { "registry": "ghcr.io", "refused": true } } }

message ends with the registry's own answer. refused is false when the registry could not be asked (a name that does not resolve, a registry that is down), and the message then says why.

The password is written encrypted (AES-256-GCM, bound to the registry's name) and is never returned, logged or repeated in an error.

DELETE /registries/:registry ​

Removes a registry's credential.

StatusBody
204None
400 INVALID_REQUEST:registry is not a registry name
404 NOT_FOUNDNo credential is stored for it

GET /certificates ​

The certificates you supplied, in hostname order: what each says about itself, never the key or the PEM. Such a certificate is for hostnames whose certificate does not come from the proxy's authority. It belongs to the server: every hostname it covers, of any application, is served with it, is not asked of any authority and does not wait for DNS.

StatusBody
200Array of Certificate

An expired certificate stays listed, and served, until it is replaced or removed. The certificate the proxy actually presents for each hostname of an application is in the application detail.

PUT /certificates/:hostname ​

Stores a certificate and its key under a hostname, creating or replacing it.

bash
curl -X PUT …/certificates/example.com \
  -d '{"certificate": "-----BEGIN CERTIFICATE-----\n…", "key": "-----BEGIN PRIVATE KEY-----\n…"}'
FieldType
certificatestringRequired. The chain in PEM, the hostname's own certificate first. At most 64 KB.
keystringRequired. Its private key in PEM, without a passphrase. At most 64 KB.

:hostname is a hostname as in deploy.yaml, lower-cased; a wildcard certificate is stored under the wildcard, /certificates/*.example.com. The body is at most 513 KB; unknown fields are rejected. At most 50 certificates are stored.

StatusBody
200Certificate, as stored
400 INVALID_REQUEST:hostname is not a hostname; a missing or oversized certificate or key, invalid JSON, unknown field, or the 51st certificate
413 INVALID_REQUESTBody over 513 KB; the message names the limit. Since 0.10 (400 before)
400 INVALID_CERTIFICATEThe certificate or key cannot serve the hostname; message says why
json
{ "data": {
  "hostname": "example.com",
  "subjects": ["example.com", "*.example.com"],
  "issuer": "Corp Issuing CA",
  "not_before": "2026-09-01T00:00:00Z",
  "not_after": "2027-09-01T00:00:00Z",
  "created_at": "2026-10-03T10:00:00Z",
  "updated_at": "2026-10-03T10:00:00Z"
} }

The agent checks before it stores, and answers 400 INVALID_CERTIFICATE with the reason as message: the chain is not PEM or holds something other than certificates; a certificate in it cannot be read; the key is not PEM, is protected by a passphrase, or does not belong to the first certificate; the certificate has no DNS names, does not cover the hostname (the certificate does not cover example.org: it is for example.com, *.example.com), has expired (the certificate expired on 2026-09-01) or is not valid yet. A wildcard name covers exactly one label, and a wildcard hostname is covered only by the same wildcard. Whether the chain leads to an authority browsers trust is not checked: a private authority's certificate is a use of this.

subjects are the DNS names of the chain's first certificate, issuer its issuer's common name (the organization, when it has none). The key is written encrypted (AES-256-GCM, the hostname as additional data) and is never returned, logged or repeated in an error; the PEM is not returned either. The proxy is updated before the request is answered. See Certificates.

DELETE /certificates/:hostname ​

Removes a certificate. The hostnames it covered go back to certificates the proxy obtains, and to waiting for DNS.

StatusBody
204None
400 INVALID_REQUEST:hostname is not a hostname
404 NOT_FOUNDNothing is stored under that hostname

A deployed wildcard hostname that loses its certificate this way is no longer served while the agent has no DNS challenge; a new deployment that names one is refused:

json
{ "error": { "code": "INVALID_CONFIG", "message": "invalid deploy.yaml",
             "details": { "fields": [ {
               "field": "domain",
               "message": "a certificate for a wildcard is issued only through a DNS record, and the agent is not set up for that",
               "expected": "SHIPWICK_CLOUDFLARE_API_TOKEN on the agent, or a certificate of your own: shipwick cert set '*.example.com' --cert fullchain.pem --key privkey.pem" } ] } } }

GET /volumes ​

Every volume Shipwick created on the server, by its Docker name, with the application it was created for and whether that application still exists. DELETE /applications/:name keeps the application's volumes; this is where they turn up afterwards.

StatusBody
200Array of ServerVolume
json
{ "data": [
  { "name": "shipwick_pgtest_data", "application": "pgtest", "volume": "data",
    "size_bytes": 13631488, "orphan": true },
  { "name": "shipwick_postgres_data", "application": "postgres", "volume": "data",
    "size_bytes": 2684354560, "orphan": false }
] }

size_bytes is what the daemon's disk-usage report says, -1 when it reports nothing for the volume.

DELETE /volumes/:name ​

Removes a volume of a deleted application, with everything in it. :name is the Docker name, shipwick_<application>_<volume>.

StatusBody
204None
400 INVALID_REQUEST:name is not of the form shipwick_<application>_<volume>
404 NOT_FOUNDNo volume by that name
409 VOLUME_IN_USEThe application still exists; details.application names it. Its data belongs to it, and a restore is the way to replace it.

POST /export ​

Streams an export: everything the server would need to be built again elsewhere. That is every application's active configuration with its values in clear, the stored secrets, registry credentials and certificates, the images that exist only on the server, the folders of static applications and an archive of every volume. It exists only encrypted, in the format backups use.

json
{ "passphrase": "at least twelve characters", "applications": ["db", "api"] }
FieldType
passphrasestringRequired. At least 12 characters. It encrypts the file; the agent keeps nothing of it.
applicationsarray of stringsOptional. Limits the export to those applications.

Unknown fields are rejected.

StatusBody
200The export, Content-Type: application/octet-stream, with Content-Disposition: attachment; filename="shipwick-export-<UTC yyyymmdd-hhmmss>.swexport", sent chunked: the length is not known beforehand
400 INVALID_REQUESTInvalid JSON or an unknown field; a passphrase shorter than 12 characters; an invalid application name
404 NOT_FOUNDapplications names an unknown application
409 DEPLOYMENT_IN_PROGRESSAn application is being deployed when the export begins; the message names it

What fails before the first byte is an ordinary error. What fails later ends the body without the file's last chunk, so that it does not decrypt, and says why in the trailer X-Shipwick-Export-Error. A client should read what it received to its end with the passphrase before calling it an export. Nothing is written on the server. See Move to a new server.

POST /import ​

Takes an export as the body, with Content-Type: application/octet-stream, and its passphrase in the header X-Shipwick-Passphrase, base64-encoded. The agent imports the file as it arrives, storing nothing of it, and answers when every application in it has been dealt with, which takes as long as their deployments; a client must not time the request out.

ParameterDefault
stoppedfalsetrue deploys every application without starting it, and then replaces only applications that are stopped
overwritefalsetrue replaces what exists under the same name, applications with their volumes
StatusBody
200Import, also when applications in it failed
400 INVALID_REQUESTThe body is not sent as application/octet-stream; an invalid stopped or overwrite; no passphrase header, or one that is not base64
400 INVALID_EXPORTThe body is not an export, the passphrase does not match, or the file breaks off. What had been imported until then stays, and GET /import shows it. Also, since 0.9, when the export, written by a newer agent, names a key of the configuration this agent does not know (requires in its manifest): it is refused before anything is taken in, and the message names the key and the version that wrote the export — the export was written by Shipwick v1.2.0 and uses the key spec.hoverboard, which this agent (Shipwick v1.1.0) does not know and would drop. Import it with an agent of that version or newer, or export without the applications that use it. GET /import then shows the record as failed with that error and no applications. Exports written before 0.9 carry no list and import as before.
409 IMPORT_IN_PROGRESSAn import is running; a server takes one at a time
409 PROMOTION_IN_PROGRESSNothing is imported into a server while it is being promoted
503 RUNTIME_UNAVAILABLEThe agent is shutting down
json
{
  "status": "failed",
  "source": "upload",
  "stopped": false,
  "overwrite": false,
  "started_at": "2026-03-01T04:10:00Z",
  "completed_at": "2026-03-01T04:11:32Z",
  "exported_at": "2026-03-01T04:00:00Z",
  "secrets": 2,
  "registries": 1,
  "certificates": 0,
  "applications": [
    { "name": "postgres", "status": "imported", "version": "17", "deployment_id": 1,
      "volumes": ["data"], "message": "" },
    { "name": "my-api", "status": "skipped", "version": "1.4.2", "deployment_id": null,
      "volumes": [], "message": "it exists on this server and was left as it is; import with --overwrite to replace it and its volumes" }
  ],
  "warnings": ["DB_PASSWORD: a secret by that name exists on this server and was kept; --overwrite replaces it"],
  "error": ""
}

status is running, succeeded or failed: failed when an application failed or the import could not go on, which error then explains. An application's status is pending, importing, imported, skipped (it exists, or runs, and was left alone) or failed; message says why and what to do. volumes are the volumes that were filled before the application first started. A deployment made by an import has the kind import, or standby when it was deployed stopped for a standby.

The configuration of every application in an export is validated by the rules a deploy.yaml is held to, all of them, before anything of the application is touched; one that does not pass is failed with the fields and what is wrong with each in message, and the import goes on with the next.

GET /import ​

The import that is running, or ran last, in the same shape: poll it from a second connection to follow an upload.

StatusBody
200Import
404 NOT_FOUNDThe server has run no import

The record outlives the agent that wrote it. An import does not: it ends with the upload or the download that feeds it, so an import the agent was restarted under is failed, and says so. A deployment it had begun is resumed like any other, and an application that was being deployed stopped stays stopped.

GET /exports ​

The exports written to where backups go, newest first. Each is a record shaped like a backup whose one "volume" is export.tar. With SHIPWICK_EXPORT_SCHEDULE the agent writes one on a schedule, with the trigger schedule.

ParameterDefault
limit501 to 500
StatusBody
200Array of BackupRun
400 INVALID_REQUESTInvalid limit

GET /exports/:id ​

StatusBody
200BackupRun
400 INVALID_REQUEST:id is not a positive number
404 NOT_FOUNDNo such export

POST /exports ​

Writes an export of the whole server to where backups go, encrypted with the agent's SHIPWICK_BACKUP_PASSPHRASE. No body.

StatusBody
202BackupRun, and a Location header: /api/v1/exports/<id>. Poll it until completed_at is set.
409 BACKUPS_NOT_ENCRYPTEDSHIPWICK_BACKUP_PASSPHRASE is not set: an export is only ever written encrypted
409 EXPORT_IN_PROGRESSAn export is being written already
409 BACKUP_NOT_USABLEThe agent was started without anywhere to keep backups

GET /standby ​

What the server holds for the day it has to take over.

StatusBody
200Standby
json
{
  "applications": [
    { "name": "postgres", "version": "17", "hostnames": [], "imported_at": "2026-03-01T04:15:02Z" },
    { "name": "my-api", "version": "1.4.2", "hostnames": ["api.example.com"], "imported_at": "2026-03-01T04:15:09Z" }
  ],
  "records": [{ "hostname": "api.example.com", "type": "A", "value": "203.0.113.77" }],
  "pull": { "schedule": "15 * * * *", "last_at": "2026-03-01T04:15:11Z", "last_export_id": 42, "last_error": "" },
  "promotion": null
}

applications were imported stopped and are still stopped, in the order a promotion starts them. records are the DNS records a promotion will ask for; value is empty when the agent does not know its own address. pull is null unless SHIPWICK_STANDBY_SCHEDULE is set; last_export_id is the id of the export imported last, 0 if none; both survive a restart of the agent, so an export is imported once. promotion is the promotion that is running or ran last, as GET /standby/promotion returns it, and null on a server that was never promoted (an agent before 0.6 leaves the field out).

POST /standby/pull ​

Imports the newest export in the bucket now, stopped and overwriting. No body.

StatusBody
202Import as it begins, and Location: /api/v1/import to poll until completed_at is set
404 NOT_FOUNDThe bucket holds no export
409 STANDBY_NOT_CONFIGUREDThe agent has no bucket to read exports from
409 IMPORT_IN_PROGRESSAn import is running

POST /standby/promote ​

Begins a promotion: the applications that were imported stopped are started in order, each waited for until it is ready or has spent its startup budget. The promotion runs on the server, whatever becomes of the request, and has a record. No body.

ParameterDefault
waittruefalse answers as the promotion begins. Without it the request is held until the promotion has ended.
StatusBody
202With wait=false: Promotion as it begins, and Location: /api/v1/standby/promotion to poll until completed_at is set
200Without wait=false: the completed Promotion. Either way, when there is nothing to promote: a record that has completed, with "id": 0 and no applications
400 INVALID_REQUESTwait is neither true nor false
409 PROMOTION_IN_PROGRESSA promotion is running: there is one at a time, and the record of the one that runs is the one to follow
409 IMPORT_IN_PROGRESSAn import is running
503 RUNTIME_UNAVAILABLEThe agent is stopped while the request is held
json
{
  "id": 1,
  "status": "running",
  "started_at": "2026-03-01T09:30:00Z",
  "completed_at": null,
  "applications": [
    { "name": "postgres", "status": "pending", "message": "" },
    { "name": "my-api", "status": "pending", "message": "" }
  ],
  "records": [{ "hostname": "api.example.com", "type": "A", "value": "203.0.113.77" }]
}

With nothing to promote, no promotion begins, and the record of the last promotion stays.

A promotion outlives the agent. One that an agent was restarted under is resumed by the agent that starts next, from its record: applications it had finished with keep their outcome, the one it was at is started if it is not running and waited for again, the rest follow. While the agent is away the proxy answers 502, 503 or 504 in its place, and an agent that is shutting down answers 503; a client keeps polling.

Without wait=false the request is held until the promotion has ended and answered 200 with the completed record, as agents before 0.6 answered. Those have no record: no id, status or times in the answer, and 404 ENDPOINT_NOT_FOUND for GET /standby/promotion. The promotion is the same one either way; a held request that loses its connection loses only the answer, which GET /standby/promotion still has. A held answer carries nothing until it is complete, and a proxy that closes an idle response — Cloudflare's does after 100 seconds — ends it: through one, use wait=false and poll. See Keep a second server ready.

GET /standby/promotion ​

The promotion that is running, or ran last. It returns the record while the promotion runs and after it has ended; poll it until completed_at is set.

StatusBody
200Promotion
404 NOT_FOUNDThe server was never promoted
  • status is running, then succeeded, or failed when at least one application could not be started.
  • An application's status is pending (not reached yet), starting (being started, or waited for), running (ready), started (not ready within its startup budget; the supervisor has it, and message says what it last answered) or failed (it could not be started; message says why). One application that fails does not stop the promotion.
  • records are the DNS records to change, fixed when the promotion begins.
  • id counts the promotions of the server. A client that lost the answer to its POST reads the record: an id it has not seen means the request arrived.

An agent before 0.6 answers 404 ENDPOINT_NOT_FOUND.

GET /metrics ​

The Prometheus text exposition format, for a scraper. The path is /metrics, not under /api/v1. It takes Authorization: Bearer <token> like every other endpoint, with the read role.

StatusBody
200Content-Type: text/plain; version=0.0.4; charset=utf-8, without the envelope

Errors (401, 403, 429) are the JSON envelope as everywhere else.

SeriesType
shipwick_agent_info{version}gaugeAlways 1
shipwick_application_status{application, status}gauge1 for the current status, in lower case: healthy, degraded, down, crash_loop, stopped, deploying, failed
shipwick_application_replicas{application, state}gaugestate is desired, running or healthy
shipwick_replica_cpu_ratio{application, replica}gaugeCPU in cores, from the last sample: 1 is one core kept busy
shipwick_replica_memory_bytes{application, replica}gaugeWorking set, from the last sample
shipwick_replica_memory_limit_bytes{application, replica}gaugeAbsent for a replica without a limit
shipwick_replica_restarts_total{application, replica}counterRestarts by the supervisor; starts again at 0 with each deployment
shipwick_deployments_total{application, status}counterFinished deployments; status is succeeded, failed or rolled_back
shipwick_deployment_last_duration_seconds{application}gaugeFrom start to completion of the most recently completed deployment
shipwick_disk_bytes{state}gaugestate is total or used, as disk in GET /server; absent where it cannot be measured
shipwick_alerts{kind, severity}gaugeNumber of active alerts; kind is disk, docker (since 0.8), memory, restarts or unhealthy, severity warning or critical; every combination is present, 0 when none
  • Every family has its # HELP and # TYPE lines, families come in the order above and series sorted by application and label: two scrapes of the same state are the same bytes.
  • A scrape reads the database in one transaction and never asks Docker. It is therefore answered while the Docker daemon is not, when GET /server is 503: shipwick_alerts{kind="docker", severity="critical"} is where a scraper reads that the daemon has been silent for 30 seconds. Status and the running and healthy counts are as the supervisor saw them at its last pass, a second ago at most; during a deployment they are those from before it began. CPU and memory are the last 30-second sample of each replica; a replica without a sample in the last 75 seconds, stopped or started less than a minute ago, has no CPU and memory series.
  • In the first second after the agent starts, an application the supervisor has not looked at yet has only its desired replicas and no status.
  • rate(shipwick_deployments_total{status="failed"}[1d]) behaves: the three outcomes only ever grow, and are present from an application's first deployment. Deleting an application removes its series.

See Alerts and metrics.

Asynchronous deployments ​

deploy, redeploy and rollback answer 202 Accepted as soon as the PENDING record exists, with Location: /api/v1/deployments/7:

json
{
  "data": {
    "id": 7, "application": "my-api", "sequence": 3,
    "version": "1.4.2", "image": "ghcr.io/company/my-api:1.4.2",
    "status": "PENDING", "error": "",
    "started_at": "2026-03-01T10:00:00Z", "completed_at": null,
    "kind": "deploy", "source_deployment_id": null, "by": "ci"
  }
}

The deployment runs in the background. Poll GET /deployments/7 until completed_at is non-null, then read status and error:

Final statusMeaning
ACTIVEThe only success.
FAILEDThe deployment failed and nothing of the previous version was lost. error says why. If an automatic rollback also failed, error holds both causes.
ROLLED_BACKThe deployment failed after part of the previous version had been replaced, and the previous version was restored. error says why the deployment failed.

Do not stop at the first settled status:

  • After ACTIVE, the engine may still be cleaning up, and a new operation would get 409 until completed_at appears.
  • FAILED may be followed by ROLLBACK, RESTORING and ROLLED_BACK.
  • A deployment that ended while the agent's database could not be written — its disk is full — keeps the status of its last successful write and no completed_at until the database takes writes again. It is completed then, and if its status was still one of work, it becomes FAILED with the error it failed with at the time. Keep polling; see The disk is full. An agent before 0.8 leaves such a deployment in flight, and runs it again when it is next started.

completed_at is stamped after cleanup and after the application's lock is released. From that moment a new operation on the application is guaranteed not to be rejected as busy.

completed_at does not wait for the replicas that were replaced to exit. They are out of rotation and have been sent SIGTERM; each then has the application's deploy.stop_timeout (10s unless set) before it is killed, and is removed after that. Until then it is listed among the application's containers with stopping: true. One that had to be killed is reported in the application's events, at level warn. A deployment that starts while one is still stopping waits for it before it starts a replica, and says how long it waited: Waited 8s for a replaced container to stop.

A deployment that is in flight when the agent stops, as an upgrade of Shipwick makes it do, is neither failed nor completed: the agent resumes it when it starts, and its events then include the step Resumed after the agent restarted. To a client that polls, the agent is unreachable for a moment and the deployment then goes on; keep polling. One that cannot be resumed ends FAILED with an error that begins agent restarted during deployment, or that says its pre-deploy command was interrupted: a pre-deploy command is not run a second time.

The deployments an import makes are ordinary deployments with the kind import or standby; the import request waits for them itself.

shipwick polls every 500 milliseconds. While a deployment is in flight, the application's deploying is true and in_flight_deployment_id names it, which lets a client follow a deployment that was started elsewhere.

Deployment events ​

events in the deployment detail narrate progress. Entries with type: "step" are meant to be shown to users; entries with type: "state" carry the new status as their message:

text
state  BUILDING
step   Pulled image ghcr.io/company/my-api:1.4.2     (or: "Using image shipwick.local/…, sent from a developer's machine")
step   Running pre-deploy command                    (only with pre_deploy)
step   Pre-deploy command finished (12s)             (only with pre_deploy)
state  STARTING
step   Started 1 container
state  HEALTH_CHECKING
step   Replica 1 passed health checks        (or: "running and stable" without a health block)
step   Replica 1/2 is serving 1.4.2; its 1.4.1 predecessor is retired
step   Replica 2 passed health checks
step   Replica 2/2 is serving 1.4.2; its 1.4.1 predecessor is retired
state  HEALTHY
step   Routed https://api.example.com to 2 replicas   (only with a domain)
state  ACTIVE
step   Deployment successful
probe  https://api.example.com/ answers HTTP 200 through the proxy   (only with a routed domain; after completed_at)

The probe event, since 0.9, is the agent asking the application its own hostname once through the proxy — GET https://<domain><path>/, following no redirect, five seconds at most — after the deployment is complete; completed_at never waits for it, and it is the one event that appears after it, at most one per deployment. An agent before 0.9 records none. Since 1.0 the answer counts only under a certificate that names the hostname; the chain behind it is not checked, since on a development machine the issuer is Caddy's own authority and nothing is sent over the connection. At level info it says what the application answered: https://example.com/ answers HTTP 200 through the proxy, https://example.com/ answers HTTP 302 through the proxy to https://example.com/login. At level warn it is a redirect loop — the answer sends visitors to a hostname of redirects, which the proxy sends back — or a proxy that could not be asked (https://example.com/ could not be asked through the proxy: <cause>), and the message says what to do: https://example.com/ sends its visitors to www.example.com, which redirectssends back: every request loops. Make www.example.com thedomain and example.com a redirect, or stop the application redirecting. While the proxy cannot answer — no certificate for a new hostname yet — the agent asks again every ten seconds for up to three minutes, so the event may follow completed_at by minutes; a client that stops polling at completion fetches the deployment once more, or follows GET /applications/:name for the active deployment's events. A folder, an application deployed stopped, a wildcard and a hostname still waiting for DNS get no probe event. See A redirect loop is caught.

A step event with level: "warn" is a warning, for example when the image could not be pulled and a local copy was used, when a domain is configured but no reverse proxy is, or when a hostname does not point at the server yet: the warning names the record to create, add an A record: api.example.com → 203.0.113.10 (DNS only, not proxied). Since 0.8 a deployment that asks for a limit the server's Docker does not apply says so in one: Docker on this server does not enforce resources.memory and resources.cpu: the replicas run without a limit. shipwick doctor says what the server lacks. A static deployment's steps read Received 42 files (3.1 MB), Copied 42 files into the proxy, Found index.html and Routed https://example.com to the uploaded files instead of the pull and the replicas.

On failure there is a state event FAILED: <reason> with level: "error" and, if a replica crashed or never became healthy, a log event holding its last 20 lines of output. A pre-deploy command that exits non-zero or outlives its timeout fails the deployment before any replica of the new version was started, with the reason pre-deploy command exited 1 or pre-deploy command timed out after 10m, and a log event Last output of the pre-deploy command: followed by its last 20 lines, at most 4096 bytes. A rollback adds the state events ROLLBACK, RESTORING and ROLLED_BACK, and steps narrating it. A deployment that ends FAILED or ROLLED_BACK removes the image it named unless something else needs it, and says so in a step. Deployment events never change afterwards, but for the one probe event an agent of 0.9 or later adds after completed_at.

Following logs ​

GET /applications/:name/logs?follow=true answers with Content-Type: application/x-ndjson: one LogLine object per line, without the data envelope, flushed as lines arrive.

json
{"replica":1,"container":"shipwick_my-api_7_1","stream":"stdout","time":"2026-03-01T10:00:00.12Z","message":"listening on :8080"}
{"replica":2,"container":"shipwick_my-api_7_2","stream":"stderr","time":"2026-03-01T10:00:00.31Z","message":"cache warm"}
{"heartbeat":true,"time":"2026-03-01T10:00:20.31Z"}
{"end":"containers"}
  • Each replica starts with its last tail lines, so two replicas and tail=100 begin with up to 200 lines. tail=0 means "only what is logged from now on" and is valid only when following.
  • since=<RFC 3339>, since 0.9, starts with every line logged at or after that time instead, tail not applied — inclusive, so the line at that instant comes again: how a client that lost the stream takes it up where it left off, from the time of the last line it has. The answer then carries X-Shipwick-Log-Since with the time as the agent read it (RFC 3339, nanoseconds, UTC); an agent before 0.9 does not know since, answers without the header and starts with the last tail lines. Without follow=true, since is 400 INVALID_REQUEST — lines of a time are what logs/search finds.
  • While the application prints nothing, the stream carries a heartbeat every 20 seconds, since 0.9 — {"heartbeat":true,"time":"2026-03-01T10:00:20.31Z"}, the agent's clock — so that nothing between the agent and the client takes a quiet stream for a dead one: Cloudflare's proxy closes a response that has carried no bytes for 100 seconds. It is not a log line: a reader tells it from one by the field (it has no message), and may take its time as where to resume from. Every line sent starts the 20 seconds over, so a busy stream carries none. Agents before 0.9 send none; see LogHeartbeat.
  • Lines of one replica arrive in order. Replicas interleave as output arrives.
  • Problems found before streaming starts (unknown application, nothing deployed, bad parameters) are regular JSON errors with a non-200 status.
  • The stream ends when the client disconnects, when the agent shuts down, or when every followed container is gone, which is what a new deployment does. Since 0.9 a stream the agent ends carries a last line that says which: {"end":"containers"} — reconnect to follow the new containers — or {"end":"shutdown"}, the agent is stopping for a restart or an upgrade and is back in a moment; a client that wants to go on reconnects then, with since. Not a log line either (no message); see LogEnd. Agents before 0.9 end a stream without one.

When the API is served through Caddy at SHIPWICK_AGENT_DOMAIN, the route is configured without response buffering, so lines still arrive one by one. The proxy compresses the API's other responses; a followed log is not compressed, since the encoder would hold its response header back until the application printed something.

Types ​

All types are defined in pkg/api/types.go; those of signing in and the access rules are in pkg/api/signin.go.

Health ​

FieldType
statusstringok
versionstringThe agent's version

Server ​

FieldType
agent_versionstring
hostnamestring
osstringOperating system, as Docker reports it
kernelstring
architecturestring
docker_versionstring
cpusinteger
memory_bytesintegerMemory of the host
swap_bytesintegerHow much swap the server has; 0 is a server without swap. Absent where the agent cannot tell, and from agents before 0.8.
unlimited_memoryarray of stringsThe running applications that have no memory limit: each may use whatever the server has. [] when there are none (left out before 0.10); absent from agents before 0.8.
applicationsintegerNumber of applications
containersintegerRunning Shipwick-managed containers
proxyobjectenabled: a proxy is configured; false means domains are not served. reachable: the last configuration sync succeeded. error: why it did not. routes: hostnames being served. dns_challenge: certificates are obtained through a DNS record, so hostnames may stand behind Cloudflare's proxy and may be wildcards. plain_lookups, since 0.8: present and true when the proxy is not Shipwick's image of this version, and finds replicas without keeping the last answer of a name lookup; absent otherwise. networks_missing, since 0.9: the installation's networks the proxy's container is not attached to, looked at every 30 seconds; [] when it is on all of them (left out before 0.10).
tokenTokenIdentityThe token, or the session, this request was made with
sign_inSignInStatusWhether people can sign in with an OpenID Connect provider. Absent from agents before 0.6.
notificationsNotificationStatusWhere the agent reports outcomes
dashboard_urlstringWhere the dashboard is served; "" when it has no hostname
alertsarray of AlertThe conditions that hold right now, oldest first; [] when there are none
diskDiskUsage or nullNull where the agent cannot measure it
backupsBackupStatusWhere backups go, and how the agent's own state is backed up
networkNetworkStatusHow the agent and the Docker daemon reach what is outside the server. Absent from agents before 0.6.
log_archiveLogArchiveStatusWhat the agent keeps of ended containers' output. Absent from agents before 0.7.
updateUpdateStatusWhat the agent knows about newer releases. Absent from agents before 0.7.
open_to_applicationsbooleanPresent and true when the containers of applications can reach the API over the network: the agent shares a network with them and listens on it. Absent otherwise, and from agents before 0.8, which never say.
dockerDockerStatusWhat the Docker daemon says about itself. Absent from agents before 0.8.
kernel_limitsKernelLimitsWhat the agent could read of the kernel's limits. Present only where it could, an agent that runs as a process of the host; absent from agents before 0.9.
cloudflareCloudflareStatusWhat the agent found out about its Cloudflare token when it last checked it. Absent without a token, before the first check has finished, and from agents before 0.9.

KernelLimits ​

The kernel_limits object of GET /server. Since 0.9.

FieldType
neighbour_tableintegernet.ipv4.neigh.default.gc_thresh3: how many neighbours the kernel keeps before containers stop reaching each other, 1024 in a stock kernel. See Prepare a server

CloudflareStatus ​

The answer of POST /server/cloudflare/verify, and cloudflare in GET /server. Since 0.9.

FieldType
checked_attimestampWhen the check was made
okbooleanThe token is valid and active, sees at least one zone and can edit the DNS records of every zone it sees; problems is then empty
addressstringThe address Cloudflare saw the check come from, which an IP filter on the token has to name; "" when it could not be learned
zonesarray of CloudflareZoneThe zones the token sees, up to 50; [] when it sees none or could not list them
problemsarray of stringsOne sentence per thing that is wrong, for a person to act on; [] when ok

CloudflareZone ​

FieldType
namestringThe zone, example.com
dns_editbooleanThe token could create a DNS record in it

DockerStatus ​

The docker object of GET /server: what the daemon says about itself that changes what a deployment gets. Since 0.8.

FieldType
rootlessbooleanThe daemon runs as an ordinary user of the server and not as root
unenforced_limitsarray of stringsThe limits of resources the daemon accepts and does not apply, memory and cpu: it has no cgroup controller for them. [] when both are enforced. A rootless daemon that enforces neither has no cgroups at all, and what it reports as a container's memory and CPU is then not that container's either.
socketstringHow the agent reaches the daemon: proxy through the filtered socket of the installation's socket proxy, direct on the daemon's own socket (compose.direct-socket.yml, or an agent installed from a package). Read off the address the agent was given. Absent from an agent older than 1.1. See The Docker socket. Since 1.1.

LogArchiveStatus ​

What the log archive holds and may hold. Since 0.7.

FieldType
enabledbooleanfalse when SHIPWICK_LOG_RETENTION_SIZE is 0: nothing is kept
entriesintegerHow many entries are kept
bytesintegerWhat they take on the disk
max_bytesintegerWhat they may take
retention_daysintegerHow long an entry is kept after its container ended

UpdateStatus ​

What the agent knows about newer releases. Since 0.7.

FieldType
enabledbooleanfalse when the agent was told not to ask (SHIPWICK_UPDATE_CHECK=off)
latest_versionstringThe latest release, v1.1.0; "" until the agent has been able to ask
checked_attimestamp or nullWhen GitHub last answered; null until then
availablebooleanlatest_version is newer than the agent itself

Alert ​

A condition that holds right now and that somebody should look at. It is raised once, when the condition becomes true, and is gone once it stops being true.

FieldType
kindstringmemory (a replica close to its memory limit), disk (the disk that holds the agent's data is filling up), restarts (a replica that keeps being restarted), unhealthy (an application that has not been healthy for a while) or, since 0.8, docker (the Docker daemon has not answered for 30 seconds)
severitystringwarning or critical; docker is always critical
applicationstringEmpty for disk and docker
replicaintegerSet for memory and restarts; 0 otherwise
messagestring
sincetimestampWhen the alert was raised

While the docker alert stands, nothing is supervised, deployed or routed, and GET /server, which carries the alerts, is itself 503 RUNTIME_UNAVAILABLE. The alert is read from the webhook, as alert.raised and alert.cleared, and from GET /metrics. See Docker does not answer.

DiskUsage ​

The filesystem that holds the agent's data directory.

FieldType
total_bytesintegerWithout the blocks the filesystem reserves for root
used_bytesinteger

BackupStatus ​

FieldType
destinationstringnone, local or s3
encryptedbooleanSHIPWICK_BACKUP_PASSPHRASE is set
state_last_attimestamp or nullWhen the agent's state was last backed up; null if never
state_errorstringWhy the state is not backed up, or why the last attempt failed; empty when the last attempt succeeded

KeyRotation ​

The answer to POST /server/rotate-key.

FieldType
valuesintegerThe re-encrypted values outside deployments: secrets, registry passwords, the keys of supplied certificates and, since 0.7, the references kept for deployments
deploymentsintegerThe deployment records whose environment values were re-encrypted
key_sourcestringfile when the agent keeps its key in the data directory and has replaced it there; environment when the key is set in the agent's environment, which the agent cannot change
key_filestringThe file on the server that holds the new key: the key file, or, for environment, the file the agent keeps it in until it has been started with it
keystringThe new key. Present for environment only: this response is the one time the API shows it.

TokenIdentity ​

Who a request was made as. An agent before 0.6 sends name and role only.

FieldType
namestringThe token's name; root for the token the agent is configured with; the name of a person who signed in: the e-mail address, or what the agent names people by
rolestringread, deploy or admin
kindstringtoken, or user for a person who signed in
applicationsarray of stringsThe applications a deploy token or session is limited to; empty when it is not limited
expires_attimestamp or nullNull for a token that does not expire

SignInStatus ​

The sign_in object of GET /server.

FieldType
configuredbooleanThe agent has an OpenID Connect provider
issuerstringThe provider's issuer; empty when none is configured
name_claimstringThe ID token claim people are named by: email unless the operator chose another. "" on an agent without sign-in, and absent from agents before 0.7, which knew only email

NetworkStatus ​

The network object of GET /server: how the agent and the Docker daemon reach what is outside the server.

FieldType
proxystringThe proxy the agent's own requests go through, as host:port; "" when it has none
docker_proxybooleanThe Docker daemon has a proxy configured. Images are pulled by the daemon: the agent's proxy does nothing for them.
ca_filebooleanCertificate authorities of your own are trusted in addition to the system's (SHIPWICK_CA_FILE)
dns_resolversarray of stringsThe name servers asked whether a hostname points at the server: addresses, or system. Empty: the public ones.
acme_directorystringThe certificate authority the proxy obtains certificates from; "" is Let's Encrypt

NotificationStatus ​

FieldType
webhookbooleanSHIPWICK_WEBHOOK_URL is set on the agent

Application ​

FieldType
namestring
statusstringSee Application status
desired_statestringrunning or stopped
image, version, domainstringOf the active deployment. Empty until the first deployment succeeds.
aliasesarray of stringsHostnames served like domain. [] when there are none (omitted before 0.10).
redirectsarray of stringsHostnames redirected to domain. [] when there are none (omitted before 0.10).
pathstringThe part of domain and aliases the application serves. Omitted when it serves all of it.
replicasobject{desired, running, healthy}. All zero for a static application.
staticbooleanThe proxy serves this application from a folder; it has no containers
deployingbooleanA deployment is in flight
in_flight_deployment_idinteger or nullThe deployment to follow while deploying is true
created_at, updated_attimestamp
certificate_problemCertificateProblem or nullNull while no certificate of the application is known to be out of order. Absent from agents before 0.6.
alert_countintegerHow many alerts about the application are active. Absent from agents before 0.6.
alert_severitystringThe highest severity among them: warning, critical, or "" for none. Absent from agents before 0.6.

A replica is healthy when it runs and is not failing its health check. Without a health block, healthy equals running. During a rollout the numbers describe the replicas that are serving right now, a mix of the old and the new version, and desired is the capacity the rollout maintains: the smaller of the two replica counts. For a static application all three are zero: the proxy serves it, and there is nothing to count.

ApplicationDetail ​

All fields of Application, plus:

FieldType
specSpec or nullThe active configuration, environment values and basic-auth passwords masked
active_deploymentDeployment or null
containersarray of ContainerEvery container of the application, of both versions during a rollout
certificatesarray of HostnameCertificateThe certificate status of every hostname the application answers to; empty for an application without a domain

HostnameCertificate ​

The certificate the proxy presents for one of an application's hostnames.

FieldType
hostnamestring
statusstringok, expiring, obtaining, waiting_for_dns or unknown. See GET /applications/:name.
issuerstringSet when there is a certificate
not_aftertimestamp or nullSet when there is a certificate
messagestringFor every status but ok, what is going on
failureCertificateFailureSince 0.9. The last failure the proxy logged while obtaining or renewing the certificate; with ok or expiring it means the renewal is failing. Absent while the proxy logged nothing since the certificate last arrived, and from agents before 0.9.

CertificateFailure ​

Why the proxy could not obtain or renew a hostname's certificate, from the last failure it logged. Since 0.9. See GET /applications/:name.

FieldType
attimestampWhen the proxy logged it
challengestringThe ACME challenge that failed: tls-alpn-01, http-01, dns-01, or "" when the failure came before one was tried
reasonstringA sentence: the cause, and what to look at
detailstringWhat the proxy logged, as it logged it, trimmed

CertificateProblem ​

The hostname of an application whose certificate is furthest from in order; carried by Application as certificate_problem.

FieldType
hostnamestringThe domain, an alias or a redirect
statusstringwaiting_for_dns, expiring or obtaining, the worst first; unknown is not a problem
messagestringWhat HostnameCertificate carries for the hostname

Container ​

FieldType
idstringDocker container id
namestringshipwick_<app>_<deployment sequence>_<replica>
deployment_idintegerThe deployment the container belongs to
replicaintegerReplica number, from 1
imagestring
statestringDocker state: created, running, exited, and so on
exit_codeinteger
oom_killedbooleanKilled for exceeding its memory limit
ipstringAddress on the application network. Empty unless running.
started_attimestamp or null
healthstring"" no health check configured; unknown not probed yet, for example right after an agent restart (counts as healthy); starting started or restarted, within its startup budget; healthy; unhealthy
restartsintegerRestarts performed by the supervisor over the container's lifetime
crash_loopbooleanRestarts of this replica are currently rate-limited
stoppingbooleantrue for a container the agent is retiring in the background: replaced by a deployment, or left over. It is out of rotation, has been sent SIGTERM, and is gone once its process exits or its deploy.stop_timeout is over. It is not a replica any more (replicas never counted it), and its health and restarts are not kept up. Absent from agents older than 0.6.

Deployment ​

FieldType
idintegerUnique on the server
applicationstring
sequenceintegerPer-application counter: #1, #2, and so on
versionstringDerived from the image reference; for a static deployment, the first twelve hex characters of the folder's digest
imagestringEmpty for a static deployment
staticStaticFilesThe folder a static deployment serves. Absent for a container deployment.
statusstringPENDING, BUILDING, STARTING, HEALTH_CHECKING, HEALTHY, ACTIVE, SUPERSEDED, FAILED, ROLLBACK, RESTORING, ROLLED_BACK. See Deployments.
errorstringEmpty unless the deployment failed
started_attimestamp
completed_attimestamp or nullSet when the agent is done with the deployment
kindstringdeploy, redeploy or rollback; import for the configuration an export carried, deployed by an import, and standby for the same deployed stopped on a standby
source_deployment_idinteger or nullFor a redeploy or rollback, the deployment whose configuration it re-used
bystringThe name of the token that started the deployment; root for the agent's own token; the e-mail address of a person who signed in. Omitted on deployments recorded before tokens had names.

DeploymentDetail ​

All fields of Deployment, plus:

FieldType
specSpecThe deployment's configuration, environment values and basic-auth passwords masked
eventsarray of Event

Spec ​

The JSON form of a validated deploy.yaml, with defaults applied. It is what the agent stores with each deployment. Durations are strings in Go's form: "10s", "10m0s", "1h0m0s".

FieldType
name, imagestringimage is the reference that was deployed; for a build application, the shipwick.local/<name>:<tag> the client loaded; empty for a static application
buildobjectOmitted when not set. {context, dockerfile}, as written in deploy.yaml, relative to it.
staticobjectOmitted when not set. {dir, fallback}: the folder, relative to deploy.yaml, on the machine that uploaded it, and the file of it that is answered for a path that names no file. fallback is omitted when not set.
portintegerOmitted when not set
domainstringOmitted when not set
pathstringOmitted when the application serves the whole domain. path: / is stored as no path.
proxyobjectOmitted when not set. {strip_prefix, headers, basic_auth, redirects}, each omitted when not set. basic_auth is [{path, username, password}]: path is omitted for an account of the whole application, and password is always "********". redirects is [{from, to, status}]; status is 308 when the document named none. See Paths and the proxy block.
aliasesarray of strings[] when empty (omitted before 0.10)
redirectsarray of strings[] when empty (omitted before 0.10)
replicasinteger
envobjectOmitted when empty. Names are kept; every value is "********".
healthobjectOmitted without a health check. Exactly one of path (string), tcp (integer) or command (array of strings) is present, then interval, timeout and retries, and start_period when it is set.
resourcesobject{cpu, memory_bytes}. A field is omitted when unlimited. Memory is in bytes.
volumesarrayOmitted when empty. [{name, path}]
publisharrayOmitted when empty. [{port, host, address, protocol}]: the container port, the server port, the server address to bind (omitted when every address), and tcp or udp.
entrypointarray of stringsOmitted when not set
commandarray of stringsOmitted when not set
userstringOmitted when not set
pre_deployobjectOmitted when not set. {command, timeout}; the default timeout is "10m0s".
jobsarrayOmitted when empty. [{name, schedule, command, timeout}]; schedule is five cron fields, read in UTC; the default timeout is "1h0m0s".
loggingobjectOmitted when not set. {driver, options}; options is omitted when empty.
backupsobjectOmitted when not set. {schedule, keep, before, before_timeout, before_in, stop}: schedule is five cron fields, read in UTC; keep is how many successful backups are kept, 7 unless set; before (the command run first) and stop are omitted when not set; before_timeout is how long before may run, "1h0m0s" unless set, and absent from a deployment recorded before the field existed, which means an hour; before_in, since 0.7, is "container" when before runs in a container of its own beside the replica, and omitted when it runs inside the replica.
restartobject{policy}
deployobject{strategy, stop_timeout}. stop_timeout is omitted when not set, which means 10 seconds.
initbooleantrue when init: true is set in deploy.yaml. Omitted when it is not set or false.
securitySecurityWhat the application's containers go without. Omitted for an application without the block, and for a block that asks for nothing. Absent from agents before 0.8.

Security ​

The security object of a Spec. Every field takes away; none adds. Since 0.8. See The security block.

FieldType
read_onlybooleanThe root filesystem is read-only; volumes and the paths of tmpfs stay writable. Omitted when false.
tmpfsarrayDirectories kept in memory. Omitted when empty. [{path, size_bytes}]: an absolute path inside the container, and its size in bytes, always present, 67108864 when the document named none.
capabilitiesarray of stringsThe Linux capabilities the containers keep, out of Docker's default set, in upper case without CAP_, sorted. Omitted: they keep the whole set. []: they keep none.
non_rootbooleanA container that would run as root is refused. Omitted when false.

Event ​

FieldType
idintegerIncreasing. Clients use it to tell new events from ones already seen.
deployment_idinteger or nullNull for application events
levelstringinfo, warn or error
typestringDeployment events: step, state, log, and since 0.9 probe, the agent's one look at the deployed application through the proxy, recorded after completed_at — at most one per deployment, warn for something to fix (a redirect loop, a proxy that could not be asked), info for what the hostname answered; see Deployment events. Application events: supervisor, app (stop, start, restored volume, a replaced container that had to be killed, a certificate being obtained or running out, since 0.9 why one could not be obtained or renewed), job (a scheduled job or one-off command that failed or timed out), alert (an alert about the application raised or cleared), backup (a backup that failed, a verification).
messagestring
created_attimestamp

LogLine ​

FieldType
replicainteger
containerstringContainer name
streamstringstdout or stderr
timetimestamp
messagestring

LogHeartbeat ​

A line of a followed log that is not a log line, since 0.9: sent after 20 seconds without a line, so that a proxy between the agent and the client does not close a quiet stream as idle. A reader tells it from a LogLine by its field; it has no message. See Following logs.

FieldType
heartbeatbooleanAlways true
timetimestampThe agent's clock when it was sent: where to take the stream up from with since

LogEnd ​

The last line of a followed log the agent ends on purpose, since 0.9. Agents before 0.9 end a stream without one. See Following logs.

FieldType
endstringcontainers: every followed container is gone, which is what a deployment does; reconnect to follow the new ones. shutdown: the agent is stopping for a restart or an upgrade and is back in a moment; reconnect with since.

LogArchiveEntry ​

The kept output of one run of a container, as GET /applications/:name/logs/archive lists it. Since 0.7.

FieldType
idinteger
applicationstring
kindstringreplica: one run of a replica's container, from a start to the stop after it. run: a run of a job, a pre-deploy command or a one-off command
deployment_idinteger or nullThe deployment the container belonged to; null once the deployment is gone
sequenceintegerIts number in the application's history, the sequence of a deployment and the #N of shipwick status; 0 once it is gone. Named deployment before 0.10
versionstringIts version; "" once it is gone
replicaintegerThe replica's index; 0 for a run
jobstringThe job's name for a run, pre-deploy and run included; "" for a replica
run_idinteger or nullThe run, for a run; null for a replica
containerstringContainer name
reasonstringWhy the run ended, see GET /applications/:name/logs/archive
exit_codeinteger or nullThe process's exit code; null when it was still running as its container was removed, or when the agent did not see it exit
oom_killedbooleanThe process was killed for exceeding its memory limit
ended_attimestampWhen the run ended
first_line_at, last_line_attimestamp or nullThe times of the first and the last line kept; null when lines is 0
linesintegerHow many lines are kept
bytesintegerThe size of their text
stored_bytesintegerWhat they take on the server's disk, compressed
truncatedbooleanThe run printed more than is kept; these are its last lines. A replica's run keeps 2,000 lines and 1 MB, a job's 10,000 lines and 4 MB; a line longer than 16 KB is cut

LogArchiveDetail ​

A LogArchiveEntry with its lines.

FieldType
…Every field of LogArchiveEntry
outputarray of LogLineThe lines kept, oldest first

LogMatch ​

One line found by GET /applications/:name/logs/search: a LogLine with where it comes from. Since 0.7.

FieldType
…Every field of LogLine
archive_idinteger or nullThe entry the line is kept in; null for a line read from a container that exists
deployment_idinteger or nullThe deployment the container belongs to
sequenceintegerIts number in the application's history. Named deployment before 0.10
jobstringThe job's name, for a line of a run; "" otherwise
run_idinteger or nullThe run, for a line of a run

LogSearchResult ​

One page of a search, newest source first and within a source the newest line first.

FieldType
linesarray of LogMatchMay hold fewer lines than asked for, none included, and still have a next: a request reads a bounded amount
nextstringContinues the search as cursor; "" when everything that matches the question has been looked at
sourcesintegerHow many containers' output this request read
bytesintegerHow much of it

ApplicationConfig ​

The answer to GET /applications/:name/config: the deploy.yaml that describes the application's active deployment. Since 0.7.

FieldType
applicationstring
deployment_idintegerThe deployment the document describes: the active one
sequenceintegerIts number in the application's history
versionstringIts version
documentstringThe deploy.yaml. A secret value that was written as a reference to a secret stored on the server is that reference again; an env value its deployment said was plain is the value; any other secret value is the mask, "********"
maskedarray of stringsThe fields whose value is the mask: env.API_KEY, proxy.basic_auth[0].password. A deployment of the document is refused until each has a value or a reference. []: it deploys as it is
static_digeststringFor a static application: the folder the active deployment serves, which a deployment of the document names in ?static=. Omitted otherwise
plainarray of stringsThe env values the document holds as they are, because the deployment named them in ?plain=: env.LOG_LEVEL. Sorted. A deployment of the document that names them again keeps them so. [] when there are none; absent from agents before 0.8, which mask every such value

Metrics ​

FieldType
applicationstring
collected_attimestamp
cpu_percentnumberPercent of one core: two busy cores read 200. Sum over replicas.
cpu_limit_percentnumberSame unit. 0 means unlimited.
memory_bytesintegerWorking set. Sum over replicas.
memory_limit_bytesinteger0 means unlimited
replicasarrayOne object per replica: replica, container, cpu_percent, cpu_limit_percent, memory_bytes, memory_limit_bytes
unenforced_limitsarray of stringsThe limits the server's Docker does not apply, memory and cpu, as in DockerStatus: the limits above are then what deploy.yaml asks for and nothing holds the replicas to. [] when Docker applies them (left out before 0.10); absent from agents before 0.8.

MetricsHistory ​

FieldType
applicationstring
sincetimestampStart of the window
step_secondsintegerWidth of one point: 30, 300 or 3600. Since 0.10; an agent before 0.10 sends step as "30s", "5m" or "1h"
seriesarray of MetricsSeriesOne per replica that has samples in the window
limitsMetricsLimitsThe active deployment's per-replica limits

MetricsSeries ​

FieldType
replicainteger
pointsarray of MetricsPointIn time order; steps without a sample are absent

MetricsPoint ​

FieldType
attimestampStart of the step
cpu_percentnumberAverage over the step, in percent of one core
memory_bytesintegerPeak working set in the step

MetricsLimits ​

FieldType
cpunumberCores, as in deploy.yaml. 0 means unlimited.
memory_bytesintegerBytes. 0 means unlimited.

Traffic ​

The answer to GET /applications/:name/traffic.

FieldType
applicationstring
sincetimestampStart of the window
step_secondsintegerWidth of one point: 60, 300 or 3600
totalsTrafficCountsThe whole window
pointsarray of TrafficPointIn time order; steps without a request are left out

TrafficCounts ​

The requests of one stretch of time.

FieldType
requestsinteger
status_2xx, status_3xx, status_4xx, status_5xxintegerRequests by status class
bytesintegerResponse bodies, as sent
p50_ms, p95_ms, p99_msnumberEstimated from a histogram of the proxy's durations; 0 when there were no requests

TrafficPoint ​

All fields of TrafficCounts, plus:

FieldType
attimestampStart of the step. Named t before 0.10

Request ​

One line of the proxy's access log.

FieldType
timetimestamp
methodstring
pathstringWithout the query string
statusinteger
duration_msnumber
bytesinteger
clientstringThe address the proxy saw

Volume ​

FieldType
namestringThe volume's name in deploy.yaml; on the server it is shipwick_<app>_<name>
pathstringWhere it is mounted inside the container

ServerVolume ​

One entry of GET /volumes.

FieldType
namestringThe Docker name, shipwick_<application>_<volume>
applicationstringThe application the volume was created for
volumestringIts name in that application's deploy.yaml
size_bytesintegerWhat the daemon's disk-usage report says; -1 when it reports nothing
orphanbooleanThe application has been deleted; the volume can be removed

BackupRun ​

One backup of an application's volumes, of the agent's state, or one export written to where backups go. Poll it until completed_at is set; a verification or a restore of it until activity is empty again.

FieldType
idinteger
triggerstringschedule (backups.schedule in deploy.yaml; daily for the agent's state), manual, or adopted for a backup that POST /server/backups/adopt recorded from its files
statusstringrunning, succeeded or failed; nothing is kept of a failed one
started_attimestamp
completed_attimestamp or null
volumesarray of BackupVolume
destinationsarray of stringsOf local and s3
encryptedbooleanWritten with the agent's passphrase
errorstringEmpty unless the backup failed
activitystringverify or restore while one is in progress, else ""
verified_attimestamp or nullWhen the backup last proved to restore into a container that came up
verify_errorstringWhy the last verification failed. At most one of verified_at and verify_error is set.
restored_attimestamp or nullThe same of the last restore
restore_errorstring

BackupRunDetail ​

All fields of BackupRun, plus:

FieldType
verify_outputstringThe last output of the container its verification started

BackupVolume ​

One archive of a backup: a volume of the application, for the agent's state one of its two files, for an export export.tar.

FieldType
volumestring
size_bytesintegerOf the archive, before encryption

BackupAdoption ​

The answer to POST /server/backups/adopt: the backups that are recorded now and were not before, and the ones that were found and left alone.

FieldType
adoptedarray of AdoptedBackup
skippedarray of SkippedBackup

AdoptedBackup ​

A backup the database knows from now on.

FieldType
kindstringapplication, state (the agent's database and encryption key) or export
applicationstringEmpty unless kind is application
backupBackupRunWith the trigger adopted

SkippedBackup ​

A run whose files were found and are not a backup that can be recorded.

FieldType
kindstringapplication, state or export
applicationstringEmpty unless kind is application
idintegerThe id the files carry
reasonstringWhy it was not recorded

LoadedImage ​

The answer to POST /applications/:name/images.

FieldType
imagestringThe reference that was loaded, shipwick.local/<name>:<tag>
size_bytesintegerThe size of the archive

MissingLayers ​

The answer to POST /applications/:name/images/missing.

FieldType
missingarray of stringsThe layers of the request the server's Docker does not have, in the request's order. The others can be left out of the archive.

Validation ​

The answer to POST /applications/:name/validate for a document that a deployment would accept. One that it would refuse is answered with the error the deployment would get.

FieldType
validbooleantrue

StaticUpload ​

The answer to PUT /applications/:name/static.

FieldType
digeststringsha256: and the digest of the archive; what ?static= takes
size_bytesintegerThe files' sizes added up
filesintegerHow many files the folder holds

StaticFiles ​

What a static deployment serves; carried by Deployment as static, with the same numbers as its upload.

FieldType
digeststring
size_bytesinteger
filesinteger

Secret ​

FieldType
namestringAn environment variable name
applicationstringSince 0.9. The application the secret belongs to, or "" for the server's. Absent from agents before 0.9, whose secrets are all the server's.
created_attimestamp
updated_attimestampWhen the value was last replaced

The value is never part of any response. (application, name) is what names a secret: the server's and an application's of the same name are two.

Registry ​

A stored registry credential. The password is never returned.

FieldType
registrystringA hostname with an optional port, as image references name it
usernamestring
created_attimestamp
updated_attimestampWhen the credential was last replaced

Certificate ​

A certificate you supplied for a hostname: what the chain says about itself. Neither the key nor the PEM is ever returned.

FieldType
hostnamestringThe name it is stored under
subjectsarray of stringsThe DNS names of the certificate; the hostnames it covers are served with it, and no authority is asked for those
issuerstring
not_beforetimestamp
not_aftertimestamp
created_attimestamp
updated_attimestamp

Job ​

FieldType
namestring
schedulestringFive cron fields, UTC
commandarray of strings
timeoutstringA duration, such as "1h0m0s"
last_runRun or nullNull until the job has run
next_run_attimestamp or nullThe next time the schedule fires, UTC. Null while the application is stopped.

Run ​

FieldType
idintegerUnique on the server
applicationstring
jobstringThe job's name; pre-deploy for the hook, run for a one-off command
kindstringhook, scheduled or manual
commandarray of strings
statusstringrunning; succeeded (exit code 0); failed (any other exit code, or the container could not be started); timed_out (stopped when its timeout ran out); interrupted (the agent was restarted while it ran)
exit_codeinteger or nullNull until the process has exited, and when it could not be started
deployment_idinteger or nullThe deployment whose image and environment the run used; null once that deployment is gone from the history
started_attimestamp
finished_attimestamp or nullSet when the run is over

RunDetail ​

All fields of Run, plus:

FieldType
outputstringThe last 200 lines the container wrote, at most 64 KB, joined with newlines. Empty while the run has just started.

RunRequest ​

The body of POST /applications/:name/run.

FieldType
commandarray of stringsRequired. See POST /applications/:name/run.

Token ​

FieldType
idinteger
namestring
rolestringread, deploy or admin
created_attimestamp
last_used_attimestamp or nullTo the minute; null until first used
applicationsarray of stringsThe applications a deploy token is limited to; empty when it is not limited. Absent from agents before 0.6.
expires_attimestamp or nullNull for a token that does not expire. A token whose time has passed stays listed until it is revoked. Absent from agents before 0.6.

UpdateTokenRequest ​

The body of PUT /tokens/:name. What it leaves out stays as it is. Since 0.7.

FieldType
applicationsarray of stringsReplaces the applications a deploy token is limited to; an empty list lifts the limit
expires_attimestampMoves the token's end. A token that has expired works again when its end is moved into the future
never_expiresbooleanTakes the end away. It cannot stand next to expires_at

CreatedToken ​

The answer to POST /tokens, the one time the token value itself is shown.

FieldType
idinteger
namestring
rolestring
created_attimestamp
tokenstringThe value: swk_ and 32 random bytes in unpadded base64url
applicationsarray of stringsAs asked for, sorted, each once; empty for a token that is not limited
expires_attimestamp or nullNull for a token that does not expire

AuditEntry ​

One action that changed something, or tried to, as GET /audit lists it. Nothing in it comes from a request body except names.

FieldType
idinteger
attimestamp
actorActorWho made the request
addressstringWhere the connection came from; behind the proxy that is the proxy
forwarded_forstringThe client address the proxy reported; "" without one
actionstringSee GET /audit
applicationstring"" for what is not about one application
targetstringWhat was acted on besides the application: a token, a secret, a registry, a hostname, a volume, a job, a backup's id
outcomestringok, refused or failed
statusintegerThe HTTP status the request was answered with
codestringThe error code of a request that was not answered 2xx
detailstring

Actor ​

Who did something: what kind of caller, and its name.

FieldType
kindstringtoken or user
namestringThe token's name, or the name of a person who signed in: the e-mail address, or what the claim of the operator's choice says

SignInConfig ​

The answer to GET /auth: what it takes to send a browser to the provider. All of it is public; the client secret stays in the agent.

FieldType
configuredbooleanThe agent has a provider. When false, the other fields are empty.
issuerstring
authorization_endpointstring
client_idstring
scopesarray of strings
redirect_uristringhttps://<SHIPWICK_DASHBOARD_DOMAIN>/auth/callback

SignInRequest ​

The body of POST /auth/exchange.

FieldType
codestringRequired
code_verifierstringRequired. 43 to 128 characters.
noncestringRequired. At least 22 characters of base64url.
redirect_uristringRequired. The configured one.

SignedIn ​

The answer to POST /auth/exchange.

FieldType
sessionstringThe session, presented like a token: sws_…. This is the only copy; the agent keeps its hash.
identityTokenIdentityWith kind: "user" and the e-mail address as name

AccessRule ​

Gives a role to an address, a group, a domain or a name.

FieldType
idinteger
kindstringemail, group, domain or, since 0.7, name
subjectstringThe address or the domain, in lowercase; a group as the provider sends it; a name as the provider's claim holds it
rolestringread, deploy or admin
applicationsarray of stringsLimits a deploy rule as it limits a deploy token; empty when not limited
created_attimestamp
created_bystringThe name of the token, or the address of the person, that wrote the rule

Session ​

A person signed in right now, as GET /access/sessions lists it.

FieldType
idinteger
emailstringThe person's name: the address, or with another name claim what that claim holds
rolestring
applicationsarray of strings
created_attimestamp
expires_attimestampTen hours after the sign-in
last_used_attimestamp or nullTo the minute; null until first used

SignedOut ​

The answer to DELETE /access/sessions/:email.

FieldType
sessionsintegerHow many sessions were ended

Import ​

The import a server is running, or ran last. An agent that restarts still knows it; an import it cut off by restarting has failed.

FieldType
statusstringrunning, succeeded or failed
sourcestringWhere the export came from: upload, or the export in the bucket a standby fetched
stopped, overwritebooleanAs the import was asked for
started_attimestamp
completed_attimestamp or null
exported_attimestamp or nullWhen the export was written; null until it has been read
secrets, registries, certificatesinteger
applicationsarray of ImportedApplicationIn the order they are deployed
warningsarray of stringsWhat was kept as it was, or could not be taken over
errorstring

ImportedApplication ​

FieldType
namestring
statusstringpending, importing, imported, skipped or failed
versionstring
deployment_idinteger or null
volumesarray of stringsThe volumes restored before the application first started
messagestringWhy it was skipped or failed, and what to do about it

Standby ​

What a server holds for the day it has to take over.

FieldType
applicationsarray of StandbyApplicationImported stopped, waiting for a promotion
recordsarray of DNSRecordWhat a promotion will ask for
pullStandbyPull or nullNull when the agent does not fetch exports on a schedule
promotionPromotion or nullThe promotion that runs or ran last; null when the server was never promoted. Absent from agents before 0.6.

StandbyApplication ​

FieldType
namestring
versionstring
hostnamesarray of strings
imported_attimestamp

StandbyPull ​

How the scheduled import from the bucket is doing.

FieldType
schedulestring
last_attimestamp or null
last_export_idintegerThe export imported last; 0 when none yet. Named last_export before 0.10
last_errorstring

DNSRecord ​

A record to create or change so that a hostname reaches this server.

FieldType
hostnamestring
typestringA or AAAA
valuestringEmpty when the agent does not know its own address

Promotion ​

The promotion a standby is running, or ran last: the answer to POST /standby/promote and to GET /standby/promotion. It is done when completed_at is set. An agent before 0.6 sends applications and records only.

FieldType
idintegerCounts the promotions of the server; 0 in the answer to a promotion that had nothing to start
statusstringrunning, succeeded or failed (at least one application could not be started). One that started every application has succeeded, whether or not each was ready in time.
started_attimestamp
completed_attimestamp or null
applicationsarray of PromotedApplicationIn the order they are started
recordsarray of DNSRecordThe DNS records to change, fixed when the promotion begins

PromotedApplication ​

FieldType
namestring
statusstringpending (not reached yet), starting (being started, or waited for), running (started and ready), started (not ready within its startup budget) or failed (could not be started)
messagestring

Application status ​

statusMeaning
HEALTHYAll desired replicas of the active deployment are healthy
DEGRADEDSome are
DOWNNone are: not running, or running but failing their health check
CRASH_LOOPA replica keeps dying or never turns healthy; its restarts are now rate-limited to one every 5 minutes. Outranks DEGRADED and DOWN: it says restarting is not helping.
STOPPEDStopped on request (desired_state: "stopped")
DEPLOYINGFirst deployment in flight, nothing active yet
FAILEDNo deployment has ever succeeded

deploying: true is set whenever a deployment is in flight. An application can be HEALTHY, with the old version serving, and deploying at once. A static application is HEALTHY while its deployment is active and STOPPED after stop; it has no replicas to be degraded or crash-looping.