Skip to content

Agent configuration ​

The agent is configured through environment variables only: its own SHIPWICK_* variables and a few standard ones. It has no configuration file and no flags. This page lists every variable, describes the data directory, the encryption key and how it is rotated, the webhook that notifications go to, the Cloudflare token, the alert thresholds, the variables that say where backups go, the scheduled export and the standby, the variables for a server behind a corporate proxy, the provider people sign in to the dashboard with, the token resolution order and the roles of tokens, the agent's subcommands, the variables that the production compose file adds, and the variables the dashboard reads itself.

Environment variables ​

VariableDefaultMeaning
SHIPWICK_AGENT_TOKENgeneratedThe root API token, admin. At least 16 characters.
SHIPWICK_LISTEN_ADDR127.0.0.1:9000Address the API listens on. Loopback by default, on purpose. The agent image sets it to 0.0.0.0:9000, which since 0.8 the agent narrows to its address on the shipwick-control network and loopback. An address set here is used as it is.
SHIPWICK_DATA_DIR/var/lib/shipwick on LinuxDirectory for the SQLite database, the token hash, the encryption key, the backups the agent takes, and the uploaded folders of static applications until they are deployed.
SHIPWICK_ENCRYPTION_KEYgeneratedThe key that encrypts env values, stored secrets, registry passwords and certificate keys in the database: 64 hexadecimal characters. Unset: encryption.key in the data directory, created on the first start and replaced by shipwick server rotate-key.
SHIPWICK_DOCKER_NETWORKshipwickDocker bridge network that application containers join. The other two are named after it. <network>-services: application containers join it too and carry their application's names on it while they are ready, and Caddy finds them there. <network>-control, since 0.8: the agent, Caddy and the dashboard, and no application; the API is reached there. All three are created if they do not exist.
SHIPWICK_CADDY_ADMINnoneCaddy's admin endpoint. Unset: domains are recorded but not served.
SHIPWICK_AGENT_DOMAINnoneServe the agent's API over HTTPS at this hostname, through Caddy. Requires SHIPWICK_CADDY_ADMIN.
SHIPWICK_DASHBOARD_DOMAINnoneServe the dashboard over HTTPS at this hostname, through Caddy. Requires SHIPWICK_CADDY_ADMIN. Must differ from SHIPWICK_AGENT_DOMAIN.
SHIPWICK_DASHBOARD_UPSTREAMdashboard:3000Where Caddy reaches the dashboard, as host:port. The host is a hostname or an IP address; the port is 1 to 65535. Validated only when SHIPWICK_DASHBOARD_DOMAIN is set.
SHIPWICK_WEBHOOK_URLnoneWhere notifications are posted: a Slack or Discord webhook, or any HTTPS endpoint (http only for localhost and private addresses). Unset: no notifications.
SHIPWICK_WEBHOOK_SECRETnoneSigns every notification, so that the endpoint can tell it came from the agent. Requires SHIPWICK_WEBHOOK_URL.
SHIPWICK_CLOUDFLARE_API_TOKENnoneA Cloudflare API token. Certificates are then obtained through a DNS record, so hostnames can stay behind Cloudflare's proxy and can be wildcards. Requires SHIPWICK_CADDY_ADMIN. Since 0.5.
SHIPWICK_PROXY_TLS_ADDRcaddy:443Where the agent reaches the proxy's TLS port, as host:port, to report each hostname's certificate. Since 0.5.
SHIPWICK_ALERT_MEMORY_PERCENT90A replica at or above this share of its resources.memory raises an alert. A whole number from 50 to 100. Since 0.5.
SHIPWICK_ALERT_DISK_PERCENT85The disk that holds the data directory raises an alert when it is this full. A whole number from 50 to 94. Since 0.5.
SHIPWICK_LOG_RETENTION_DAYS14How long the last output of an ended container stays in the log archive, in days after it ended. A number from 1 to 365. Since 0.7.
SHIPWICK_LOG_RETENTION_SIZE1gbWhat the log archive may take on the disk, as 500mb or 2gb, at least 6mb. 0 keeps nothing. Since 0.7.
SHIPWICK_BACKUP_DIR<data dir>/backupsWhere the backups the agent takes are kept on the server, a path inside the agent's container. Since 0.5; carried into .env by the installer and accepted by shipwick server configure since 0.10.
SHIPWICK_BACKUP_PASSPHRASEnoneEncrypts every backup, and is what allows the agent's own database and encryption key to be backed up at all. At least 12 characters. Since 0.5.
SHIPWICK_BACKUP_S3_ENDPOINTnoneAn S3-compatible service the backups are also sent to, as a URL. Needs the next three as well. Since 0.5.
SHIPWICK_BACKUP_S3_BUCKETnoneThe bucket. It must exist.
SHIPWICK_BACKUP_S3_ACCESS_KEY_ID, SHIPWICK_BACKUP_S3_SECRET_ACCESS_KEYnoneCredentials that may put, get, list and delete objects in the bucket.
SHIPWICK_BACKUP_S3_REGIONautoThe region requests are signed for.
SHIPWICK_BACKUP_S3_PREFIXnonePut in front of every object's key, so that one bucket serves several servers.
SHIPWICK_EXPORT_SCHEDULEnoneA five-field cron expression, UTC: when an export of the whole server is written to where backups go. Requires SHIPWICK_BACKUP_PASSPHRASE. Since 0.5.
SHIPWICK_EXPORT_KEEP3How many of those exports are kept. A number from 1 to 100.
SHIPWICK_STANDBY_SCHEDULEnoneA five-field cron expression, UTC. Makes the server a standby: when it imports the newest export from the bucket, with every application stopped. Since 0.5.
HTTPS_PROXY, HTTP_PROXY, NO_PROXYnoneThe proxy the agent's own requests go through, to the webhook and the bucket, and Caddy's. Not the Docker daemon's, which pulls the images. Since 0.6.
SHIPWICK_CA_FILEnoneA PEM file of certificate authorities trusted in addition to the system's, as the agent sees the path, absolute. The agent does not start with a file it cannot use. Since 0.6.
SHIPWICK_DNS_RESOLVERSpublic resolversWho is asked whether a hostname points at the server: system, the server's own resolver, or name servers by address. Since 0.6.
SHIPWICK_ACME_DIRECTORYLet's EncryptThe directory URL of an ACME server of your own: Caddy obtains every certificate there. Requires SHIPWICK_CADDY_ADMIN. Since 0.6.
SHIPWICK_OIDC_ISSUERnoneThe issuer URL of an OpenID Connect provider: people then sign in to the dashboard with its accounts. Needs the next two and SHIPWICK_DASHBOARD_DOMAIN. Since 0.6.
SHIPWICK_OIDC_CLIENT_ID, SHIPWICK_OIDC_CLIENT_SECRETnoneThe client the provider registered for Shipwick. The secret is sent to the provider's token endpoint only.
SHIPWICK_OIDC_SCOPESopenid email profileWhat is asked of the provider, separated by spaces. Must contain openid.
SHIPWICK_OIDC_GROUPS_CLAIMgroupsThe claim of the ID token that lists a person's groups.
SHIPWICK_OIDC_NAME_CLAIMemailThe claim of the ID token people are named by, for accounts without an address: preferred_username, upn, sub. Rules, the audit trail and by use that name. Since 0.7.
SHIPWICK_OIDC_TENANTSnoneWith Microsoft Entra's issuer for several tenants (…/organizations/v2.0, …/common/v2.0), which is not used without it: the tenant ids whose accounts may sign in, separated by commas. * for every tenant, only with SHIPWICK_OIDC_NAME_CLAIM=sub. Since 0.7.
SHIPWICK_OIDC_REDIRECT_URLhttps://<SHIPWICK_DASHBOARD_DOMAIN>/auth/callbackDevelopment only: where the provider sends the browser back to when the dashboard runs on the developer's machine. Anything but a localhost URL is refused.
SHIPWICK_UPDATE_CHECKonoff stops the agent's daily question to GitHub about a newer release; GET /server then says so, and the dashboard shows no notice. Since 0.7.
SHIPWICK_LOG_LEVELinfodebug, info, warn or error.
SHIPWICK_LOG_FORMATtexttext or json. Logs go to standard error. The installer's compose file sets json.
SHIPWICK_HTTP_PORT, SHIPWICK_HTTPS_PORT80, 443Read by Compose, not the agent: the server ports Caddy is published on (443 over UDP as well). Only when something else owns 80 and 443; certificates need the real ones reachable from the internet.
SHIPWICK_AGENT_IMAGE, SHIPWICK_DASHBOARD_IMAGE, SHIPWICK_CADDY_IMAGEthe release'sRead by Compose: images of your own in place of the release's. The installer keeps them across upgrades; with a bundle, docker load them first. See The production compose file.
DOCKER_HOST, DOCKER_CONFIGDocker defaultsThe standard Docker variables are honored. Since 1.1 the compose files set DOCKER_HOST to the socket proxy's socket, unix:///run/docker-proxy/docker.sock, and the agent reads how it reaches Docker off that address: docker.socket in GET /server, see The Docker socket. DOCKER_CONFIG is the directory that holds config.json, which the agent reads for the credentials of a registry it holds no stored credential for.

The agent refuses to start with an invalid value: an unknown log level or format, a token shorter than 16 characters, a domain that is not a valid hostname, a domain without SHIPWICK_CADDY_ADMIN, identical agent and dashboard hostnames, a malformed dashboard upstream or proxy TLS address, an encryption key that is not 64 hexadecimal characters, a webhook URL that is not an absolute https URL (or http towards the server itself or a private address), a webhook secret without a webhook URL, a Cloudflare token of another form or without SHIPWICK_CADDY_ADMIN, an alert threshold out of its range, a backup passphrase shorter than 12 characters, a bucket with some of its four variables missing, a schedule that is not a cron expression, a combination of schedules that the sections below rule out, a proxy variable that is not a proxy address, a certificate authority file it cannot use, a name server that is not an IP address, an ACME directory that is not a plain https URL or is set without SHIPWICK_CADDY_ADMIN, a sign-in provider that is configured in part, a log retention out of its range, or an update check that is neither on nor off. Where the value is a credential, the error names the variable and the rule, never the value: a token, a key, a passphrase, a webhook URL, a proxy's URL and a client secret are credentials.

Both hostnames are trimmed, converted to lowercase and validated by the same rule as domain in deploy.yaml. Applications cannot claim either of them.

SHIPWICK_LISTEN_ADDR ​

The API speaks plain HTTP. The default binds it to loopback so that exposing it is an explicit choice. The agent image sets SHIPWICK_LISTEN_ADDR=0.0.0.0:9000, so that Caddy and the dashboard can reach the API over the container network. The production compose file publishes no host port for it: the only ways in are Caddy, over HTTPS, and the server itself.

Since 0.8 an agent in a container does not listen on every address under that default. It listens on the address it has on the shipwick-control network, where the proxy and the dashboard reach it, and on loopback; applications are on neither. A request that comes from an application's container all the same is answered 403 APPLICATION_CALLER.

  • An address set here is used as it is. Set for the agent's container, it leaves the API open to the containers of applications, protected by the token alone: the agent then refuses the containers it manages by their address only, warns in its log when it starts, and shipwick doctor and open_to_applications in GET /server report it. Leave it unset in the container.
  • A published port on Docker before 28 has the same effect: Docker forwards the port over the network the applications are on, and the agent keeps listening there so that the port works. There is no third way on Docker 27 — the port follows the agent onto shipwick the moment it joins it for its health checks, measured on 27.5.1 — which is why the installer and the production compose file publish no port, and why the development compose file, which does, says that it is open on Docker before 28 by design.
  • As a service of the host, the agent listens where this variable says, and with SHIPWICK_AGENT_DOMAIN set also on the address the server has on the control network; it refuses every address of the two application networks.

See Who can reach the API.

The port of this address is one of the server ports an application cannot publish: publish[].host in deploy.yaml refuses it, together with 80, 443, 8080 and 8443. See publish.

WARNING

Never expose port 9000 directly to the internet. Serve the API through Caddy with SHIPWICK_AGENT_DOMAIN, or reach it over an SSH tunnel or a private network. See Security.

SHIPWICK_CADDY_ADMIN ​

Two forms are accepted:

FormExample
Unix socketunix//run/caddy/admin.sockRecommended. Only processes that share the socket can reconfigure the proxy. The path must be absolute.
TCPhttp://127.0.0.1:2019For a Caddy whose admin endpoint is reached over TCP. http://host:port without a path.

The agent echoes this address into the configuration it loads, so that Caddy's admin endpoint stays where it is.

When the variable is unset, routing is disabled: the agent warns at startup, domains are recorded but nothing serves them, and shipwick server status reports the proxy as not configured. See Routing and HTTPS.

SHIPWICK_AGENT_DOMAIN and SHIPWICK_DASHBOARD_DOMAIN ​

With SHIPWICK_AGENT_DOMAIN set, the agent adds a route for its own API. When the agent runs in a container on the application network, Caddy reaches it at the container's hostname and the port of SHIPWICK_LISTEN_ADDR. As a host process, Caddy is assumed to be a host process too, and reaches the agent at the listen address (127.0.0.1 if the address is unspecified).

With SHIPWICK_DASHBOARD_DOMAIN set, the agent adds a route to SHIPWICK_DASHBOARD_UPSTREAM.

Both routes have response buffering disabled, so that followed logs arrive line by line.

An application that claims either hostname, as its domain, an alias or a redirect, is refused with already served by Shipwick itself (the agent or the dashboard).

SHIPWICK_ENCRYPTION_KEY ​

The key the agent encrypts secret values with before it writes them to the database. Every env value and every basic-auth password of every deployment, since 0.10 its logging.options.splunk-token, every secret stored with shipwick secret set, every registry password stored with shipwick registry login, the key of every certificate supplied with shipwick cert set and the secret values a deployment's document referred to with ${NAME} is stored as AES-256-GCM ciphertext; the variable names, and everything else in the record, stay readable. A copy of shipwick.db without the key reveals no secrets.

Format64 hexadecimal characters: 32 random bytes. Generate one with openssl rand -hex 32.
NormalizationLeading and trailing whitespace is trimmed.
InvalidThe agent refuses to start: SHIPWICK_ENCRYPTION_KEY: expected 64 hexadecimal characters. The value itself is never repeated.

The key is determined at startup, in this order:

  1. SHIPWICK_ENCRYPTION_KEY, when set, always wins. Nothing is written to disk.
  2. Otherwise, the key file in the data directory, encryption.key, written by a previous run.
  3. Otherwise, a key is generated and written to encryption.key, mode 0600, as 64 hexadecimal characters and a newline. The agent logs created the key that encrypts env values in the database; back it up together with shipwick.db with the file's path.

With the installer's setup the variable is unset and the key is the file in the agent-data volume. Setting it, in /opt/shipwick/.env or from wherever the agent's environment comes from, is for keeping the key somewhere other than next to the database, in a secrets manager for instance; see Keep the encryption key off the server's disk.

Back up the key together with the database

Without the key the database cannot be read. The agent proves the key against the stored values on every start and refuses to start with a key that does not match: the encryption key does not match the database (deployment 12, variable DATABASE_URL): restore /var/lib/shipwick/encryption.key from your backup or set SHIPWICK_ENCRYPTION_KEY. A key file that is not 64 hexadecimal characters is reported as corrupt, with the same two ways out. With SHIPWICK_BACKUP_PASSPHRASE set, the agent takes that backup itself, once a day and encrypted; see Backups.

Rotation. Since 0.5, shipwick server rotate-key, or Rotate encryption key on the dashboard's server page, has the running agent generate a new key and re-encrypt every stored value under it, in one transaction, without a deployment or a restart. It needs the admin role. What happens to the key afterwards depends on where it is kept:

The key isAfter a rotation
encryption.key in the data directoryThe agent replaces the file. The new key is written next to it as encryption.key.new before the database is touched and moved into place afterwards, so a crash or a power cut at any point leaves a database and a key that fit; the next start finishes or discards what was interrupted.
SHIPWICK_ENCRYPTION_KEYThe agent cannot change its own environment. The command prints the new key once, for you to put where the variable is set, which the command takes to be /opt/shipwick/.env, before the agent restarts. Until it has been started with the new key, the agent keeps a copy in encryption.key.new in the data directory and refuses a second rotation; started with the old key, it refuses to start and says where the new one is; started with the new one, it removes the copy.

Backups of the database made before a rotation still need the old key. See Rotate the encryption key for the procedure.

A database written by a release before 0.3.0 is migrated on the first start after upgrading: its environment values are encrypted in place, once, and the agent logs encrypted the environment values of deployments written before encryption existed with the number of deployments.

What this does and does not protect: a copy of the database file that left the server, a backup, a snapshot, is unreadable without the key. Root on the server can read the key file and the agent's memory, and the values inside a running container are shown by docker inspect to anyone with the Docker socket. See Security.

SHIPWICK_WEBHOOK_URL ​

Where the agent posts notifications: every deployment's outcome, every application that goes down or recovers, a failed job or scheduled backup, a certificate that is running out, and the alerts. Unset, nothing is sent. See Get notified.

FormatAn absolute URL with a host. https, or http only when the host is localhost, a loopback address, a private address (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, fc00::/7) or a link-local address. Any other scheme is refused.
NormalizationLeading and trailing whitespace is trimmed.
InvalidThe agent refuses to start with one of must be an absolute URL such as https://hooks.example.com/shipwick, must use https; http is allowed only for localhost and private addresses or must use https, prefixed with the variable's name. The URL itself is never repeated: a Slack or Discord URL carries its token in the path.

The events, and nothing else. A single replica restarting is in shipwick status, not in your chat.

EventWhen
deployment.succeededA deployment became active.
deployment.failedA deployment failed before it changed anything.
deployment.rolled_backA deployment was undone, automatically or by shipwick rollback.
application.downEvery replica of an application stopped serving.
application.recoveredAn application that was down serves again.
job.failedA run of a scheduled job, or a shipwick run command, exited non-zero, timed out or could not be started.
backup.failedA scheduled backup of an application failed, or the daily backup of the agent's own state did. A backup taken by hand tells the person who asked. Since 0.5.
certificate.expiringA hostname's certificate has 14 days left, and again at 3: the proxy has not renewed it. Since 0.5.
alert.raisedA condition that lasts became true: a replica near its memory limit, the server's disk filling up, a replica restarted three times within ten minutes, an application that has not been healthy for five minutes. Sent once, and once more when a warning turns critical. Since 0.5.
alert.clearedThat condition no longer holds. Sent once.

The alerts and their thresholds are described in Alerts and metrics.

The body depends on the host of the URL:

HostBody
hooks.slack.com{"text": "<message>"}
discord.com or discordapp.com, path under /api/webhooks/{"content": "<message>"}
Anything elseThe full event as JSON, below
json
{
  "event": "deployment.succeeded",
  "application": "my-api",
  "deployment_id": 42,
  "version": "1.4.2",
  "message": "my-api is running 1.4.2, replacing 1.4.1",
  "at": "2026-03-01T10:00:00Z",
  "server": "vps-1"
}

message is the same complete sentence the chat formats get. deployment_id is null for an event that is not about one deployment, such as application.down. at is UTC, in whole seconds. server is the hostname of the server the agent runs on, as Docker reports it. An alert.raised or alert.cleared event carries one more field, which the other events leave out: "alert": {"kind": "memory", "severity": "warning", "replica": 1}, where kind is memory, disk, restarts or unhealthy, severity is warning or critical, and replica is 0 when the condition is not about one replica.

Every request is a POST with Content-Type: application/json and User-Agent: shipwick-agent/<version>, and, with SHIPWICK_WEBHOOK_SECRET set, an X-Shipwick-Signature header.

Delivery. Events are queued and sent by one sender, in order, so that a slow or dead endpoint never holds up a deployment. Each attempt has 10 seconds. A 2xx response is a delivery. A 5xx or 429 response, or a connection error, is retried after 1, 5 and 25 seconds, four attempts in all, then given up. Any other response is a rejection and is not retried. The queue holds 256 events; when it is full, the event is dropped. At shutdown the agent gives the queue 5 seconds to drain, then abandons what is left.

What is logged. At startup, notifications go to a webhook with the webhook's host and nothing more. A dropped, rejected or undelivered notification is a warning that names the event kind, the application and the host. The URL never appears in a log line or an error message, and a connection error is logged without the URL that Go's HTTP client would otherwise repeat.

GET /server reports notifications: {"webhook": true} when the variable is set, and shipwick server status shows it.

SHIPWICK_WEBHOOK_SECRET ​

A shared secret that signs every notification. With it set, each request carries

http
X-Shipwick-Signature: sha256=<hex HMAC-SHA256 of the request body>

The HMAC is computed over the raw body with the secret as the key and written as lowercase hexadecimal after sha256=. To verify, compute the same over the body exactly as received and compare the two in constant time.

There is no rule on the value; use something long and random, openssl rand -hex 32 for instance. The variable is not trimmed. Setting it without SHIPWICK_WEBHOOK_URL is an error: SHIPWICK_WEBHOOK_SECRET is set but SHIPWICK_WEBHOOK_URL is not. Slack and Discord ignore the header; it is for an endpoint of your own.

SHIPWICK_CLOUDFLARE_API_TOKEN ​

A Cloudflare API token with two permissions on the zones your hostnames are in, those two exactly: Zone → Zone → Read and Zone → DNS → Edit. DNS Settings, DNS Firewall and DNS Views are other permissions, with which the proxy lists the zones and cannot create a record. Not the Global API Key. With it, Caddy obtains every certificate through a DNS record (the ACME DNS-01 challenge) instead of from the server itself, so a hostname's record can stay proxied by Cloudflare, and domain and aliases may be wildcards. A hostname that resolves to Cloudflare's addresses is then served instead of held back, and Cloudflare's address ranges become trusted proxies of Caddy, so applications find the visitor's address in X-Forwarded-For. An IP filter on the token must name every address the server calls from, its IPv6 address included. See Put Cloudflare in front.

FormatLetters, digits, - and _, at least 35 characters.
NormalizationLeading and trailing whitespace is trimmed.
InvalidThe agent refuses to start: SHIPWICK_CLOUDFLARE_API_TOKEN: not a Cloudflare API token (letters, digits, - and _, at least 35 characters); create one at dash.cloudflare.com → My Profile → API Tokens, not a Global API Key. The value itself is never repeated.
RequiresSHIPWICK_CADDY_ADMIN: SHIPWICK_CLOUDFLARE_API_TOKEN needs a reverse proxy to obtain certificates with it: set SHIPWICK_CADDY_ADMIN as well.

At startup the agent logs certificates are obtained through Cloudflare DNS; hostnames may be proxied by Cloudflare, and may be wildcards, and GET /server reports proxy.dns_challenge: true, which shipwick doctor reads.

Since 0.9 the agent also checks what the token can do when it starts, and whenever shipwick doctor asks with an admin token (POST /server/cloudflare/verify, at most once a minute): whether Cloudflare accepts the token from the address the server really calls from, which zones it sees, and whether it can create a DNS record in each — a TXT record of its own, _shipwick-check.<zone>, removed at once. The result is one line in the agent's log, cloudflare in GET /server, and lines in doctor that say what to change. Nothing of the token is in any of it. See Check it and POST /server/cloudflare/verify.

The variable is set on a running server with shipwick server configure root@203.0.113.10 SHIPWICK_CLOUDFLARE_API_TOKEN=…, which checks the value's form as the installer does and names shipwick doctor as the next step; see Change a setting later.

The token can edit the DNS of your zones. The agent keeps it in memory, hands it to Caddy inside the configuration it loads, and removes it from Caddy's errors before they are logged or shown. It is never logged and never returned by the API. Caddy's autosaved copy of the configuration, on the caddy-config volume, contains it. See Security.

Without the variable nothing changes: records must point straight at the server, and a deployment that names a wildcard is refused unless a certificate of your own covers it.

SHIPWICK_PROXY_TLS_ADDR ​

Where the agent reaches the proxy's TLS port, as host:port. The agent opens a TLS handshake there with each hostname as the server name and reads the certificate a visitor would be handed: its issuer and its expiry. That is what shipwick status and the dashboard show for a hostname, and what certificate.expiring is decided from. Nothing is sent over the connection, and the chain is not verified: the agent reports what is served.

The default, caddy:443, is the Caddy service of the production compose file as the agent sees it on the shipwick network. Set the variable when the proxy's TLS port is somewhere else for the agent, as it is for an agent that runs as a service of the host: the package sets it to 127.0.0.1:443; the production compose file does not pass it. A value that is not host:port is an error: SHIPWICK_PROXY_TLS_ADDR: invalid value "caddy" (expected host:port). See Certificates.

SHIPWICK_ALERT_MEMORY_PERCENT and SHIPWICK_ALERT_DISK_PERCENT ​

The two thresholds of the alerts that have one.

VariableDefaultRange
SHIPWICK_ALERT_MEMORY_PERCENT9050 to 100A replica at or above this share of its resources.memory for three samples in a row raises the memory alert. It is cleared ten points below the threshold.
SHIPWICK_ALERT_DISK_PERCENT8550 to 94The disk that holds the data directory raises the disk alert, as a warning, when it is this full. It is cleared five points below the threshold. At 95% the alert turns critical, whatever is set here.

The value is a whole number, with or without a trailing %. Anything else, or a number out of range, is an error that names the range: SHIPWICK_ALERT_DISK_PERCENT: invalid value "99" (expected a whole number from 50 to 94).

The production compose file passes both from /opt/shipwick/.env.

SHIPWICK_LOG_RETENTION_DAYS and SHIPWICK_LOG_RETENTION_SIZE ​

Since 0.7 the agent keeps the last output of every container whose run ends — a replica that crashed, was restarted, stopped or replaced, the replicas of a deployment that failed, the runs of jobs and commands — in a log archive under logs/ in the data directory. These two variables bound it. See Find out why it died.

VariableDefaultRange
SHIPWICK_LOG_RETENTION_DAYS141 to 365How long an entry is kept, in days after its container ended.
SHIPWICK_LOG_RETENTION_SIZE1gba size of at least 6mb, or 0What the archive may take on the disk, written like resources.memory: 500mb, 2gb. Over it, the application that holds the most loses its oldest entries first. 0 keeps nothing.
  • The lines are stored compressed, about a fifth of their size; the limit is on what they take on the disk.
  • While the disk is as full as its alert's threshold, SHIPWICK_ALERT_DISK_PERCENT, the archive does not grow: a new entry makes room for itself by removing at least as much.
  • The output of a job's runs follows the job's history, its last 50 runs.
  • What a single entry holds is not configurable: a replica's run keeps its last 2,000 lines and at most 1 MB, a run of a job its last 10,000 lines and at most 4 MB, and a line longer than 16 KB is cut.

An invalid value is an error that names the rule: SHIPWICK_LOG_RETENTION_DAYS: invalid value "0" (expected a number of days from 1 to 365); for the size, the reason followed by (expected a size such as 500mb or 2gb, or 0 to keep nothing).

GET /server reports the archive as log_archive, and shipwick server status shows it as Log archive. The production compose file passes both variables from /opt/shipwick/.env.

Backups ​

Since 0.5 the agent takes backups itself: of an application's volumes, on the schedule its backups block gives, and of its own state, daily. These variables say where the backups are kept and whether they are encrypted. See Back up and restore volumes.

VariableDefault
SHIPWICK_BACKUP_DIR<data dir>/backupsThe directory on the server, a path inside the agent's container. Every backup is written there, as <application>/<id>/<volume>.tar. Whitespace is trimmed. Since 0.10 the installer carries it into .env when it is set, install.sh --help lists it, and shipwick server configure accepts it; before, it had to be set in .env by hand.
SHIPWICK_BACKUP_PASSPHRASEnoneEncrypts every backup before it is written, in the directory and in the bucket; the files are then named <volume>.tar.enc. At least 12 characters; the variable is not trimmed.
SHIPWICK_BACKUP_S3_ENDPOINTnoneThe URL of an S3-compatible service, such as https://s3.eu-central-1.amazonaws.com or https://<account>.r2.cloudflarestorage.com. A plain URL, without credentials or a query.
SHIPWICK_BACKUP_S3_BUCKETnoneThe bucket's name. It must exist; the agent does not create it.
SHIPWICK_BACKUP_S3_ACCESS_KEY_IDnoneWith the next one: credentials that may put, get, list and delete objects in the bucket.
SHIPWICK_BACKUP_S3_SECRET_ACCESS_KEYnone
SHIPWICK_BACKUP_S3_REGIONautoThe region requests are signed for. AWS wants the bucket's own.
SHIPWICK_BACKUP_S3_PREFIXnonePut in front of every object's key: one bucket for several servers, each under its own prefix. Leading and trailing slashes are dropped.

The directory. With the installer's setup the default is inside the agent-data volume. A backup on the same disk protects against a bad deployment, a dropped table, a mistake; it does not protect against losing the server. To move the directory, to a mount of another disk for instance, add the mount to the agent in /opt/shipwick/compose.override.yml and set SHIPWICK_BACKUP_DIR in /opt/shipwick/.env to where it is mounted.

The bucket. The endpoint, the bucket and the two keys belong together. With all four set, every backup goes to the directory and to the bucket, under <prefix>/<application>/<id>/, and one that did not reach both has failed. With only some of them set, the agent refuses to start and names what is missing: SHIPWICK_BACKUP_S3_ENDPOINT is set but SHIPWICK_BACKUP_S3_BUCKET, SHIPWICK_BACKUP_S3_ACCESS_KEY_ID, SHIPWICK_BACKUP_S3_SECRET_ACCESS_KEY is not: a bucket needs all four. The endpoint and the bucket's name are checked at startup as well, so that a mistake stops the agent then rather than failing the first backup; the errors never repeat a value. The values of all six S3 variables are trimmed.

A bucket belongs to one server. The agent marks the bucket, under its prefix, the first time it writes there, and refuses a bucket marked by another installation. Two servers share a bucket by giving each a SHIPWICK_BACKUP_S3_PREFIX.

Large archives. Since 0.6 an archive of more than 64 MiB goes to the bucket as a multipart upload: in parts of that size, read from the file on the server one after the other, so that its size costs no memory, and a part that fails is sent again, up to three times in all. The limit is the service's own for one object, 5 TiB on S3; the server's disk has to hold the archive first. Before 0.6 an archive larger than 5 GB did not fit one upload and failed. An upload that fails or is interrupted is aborted, so that no parts are left in the bucket to be paid for. For the upload an agent did not live to abort, the agent leaves a note next to the file for as long as it is being sent, <file>.upload, and the next agent aborts what the notes name before its own first upload. If the disk went with the agent, it asks the bucket for the unfinished uploads under its prefix and aborts those named like a backup's files. Not every service answers that question: MinIO lists unfinished uploads only under an exact key, and removes stale ones by itself. A lifecycle rule on the bucket that aborts incomplete multipart uploads after a few days costs nothing and is the last line.

The passphrase. With SHIPWICK_BACKUP_PASSPHRASE set, everything is encrypted before it is written anywhere: AES-256-GCM with a key derived from the passphrase. Backups written before the passphrase was set stay readable; if the passphrase changes, the ones written with the old one are not. Keep a copy somewhere that is not this server: without it the backups cannot be read. A passphrase shorter than 12 characters is an error: SHIPWICK_BACKUP_PASSPHRASE must be at least 12 characters long.

The passphrase is also what allows the agent's own state to be backed up at all. shipwick.db and encryption.key are backed up once a day, kept seven deep under _agent/ where application backups go, and only ever written encrypted: without a passphrase the key is written nowhere. The agent then warns at startup, the agent's own state is not backed up: the encryption key exists only on this server, and losing it loses every secret, and shipwick doctor and GET /server say so.

What is logged. At startup, either backups go to a bucket as well as to the server with the directory, the endpoint's host and the bucket's name, or backups stay on the server: they survive a bad deployment, not the loss of the server with the directory. The passphrase and the bucket's two keys are never logged and never returned by the API.

The installer writes the passphrase and the six S3 variables to /opt/shipwick/.env when they are set in the environment of the first run. To add them later, edit that file and run cd /opt/shipwick && docker compose up -d.

SHIPWICK_EXPORT_SCHEDULE and SHIPWICK_EXPORT_KEEP ​

SHIPWICK_EXPORT_SCHEDULE has the server write an export of itself, the file shipwick export produces, to where its backups go: to the backup directory and, when one is configured, to the bucket, as <prefix>/_export/<id>/export.tar.enc. It is encrypted with SHIPWICK_BACKUP_PASSPHRASE. This is the first half of a second server kept ready.

VariableDefault
SHIPWICK_EXPORT_SCHEDULEnoneA cron expression of five fields, in UTC, such as 0 * * * *. Unset: an export is written only on request, with shipwick export --to-backups.
SHIPWICK_EXPORT_KEEP3How many exports are kept. A number from 1 to 100; anything else is an error, SHIPWICK_EXPORT_KEEP must be a number from 1 to 100.

An export holds every secret of the server, so it is only ever written encrypted. Without a passphrase the agent refuses to start: SHIPWICK_EXPORT_SCHEDULE needs SHIPWICK_BACKUP_PASSPHRASE: an export is only ever written encrypted. A schedule that does not parse is an error that ends with (five fields, UTC, for example "0 4 * * *").

Like every backup, a large export goes to the bucket in parts; see Backups. At startup the agent logs an export of the server is written on a schedule, to where backups go with the schedule and the number kept.

SHIPWICK_STANDBY_SCHEDULE ​

Makes the server a standby for another one. At the times the cron expression names, five fields in UTC, the agent fetches the newest export from the bucket and imports it with every application deployed and not started: images pulled or loaded, volumes filled, containers created, nothing running and nothing routed. shipwick standby promote starts them. See Move to a new server.

The standby needs the bucket and the passphrase of the server it stands by for: the SHIPWICK_BACKUP_S3_* variables and SHIPWICK_BACKUP_PASSPHRASE, set to the values that server has. Without them the agent refuses to start and says so. It also refuses both schedules at once: SHIPWICK_EXPORT_SCHEDULE and SHIPWICK_STANDBY_SCHEDULE are both set: a server writes exports or stands by for one that does.

A standby only reads the bucket. For as long as the variable is set, its own backups stay on its disk, so that the two servers never write to the same place. The agent logs this server is a standby: it imports the newest export from the bucket on a schedule, with every application stopped, and keeps its own backups on its disk with the schedule, the endpoint's host and the bucket's name. After a promotion, remove the variable, and give the server's backups a bucket prefix of their own before you point SHIPWICK_BACKUP_S3_* at a bucket again.

HTTPS_PROXY, HTTP_PROXY and NO_PROXY ​

Since 0.6. The proxy of a server whose way to the internet is one. The agent's own requests go through it: the notifications to the webhook and the backups to the bucket. Caddy, which is given the same three variables, uses it for the certificate authority and for Cloudflare's API. Nothing is needed on a server with a plain connection. See Run behind a corporate proxy or without internet.

FormatA URL such as http://proxy.example.com:3128, with the scheme http, https, socks5 or socks5h. A bare host:port is taken as http. A user name and a password go into the URL, http://user:password@proxy.example.com:3128, with characters that are special in a URL percent-encoded.
NO_PROXYThe hosts that are reached without the proxy.
NormalizationLeading and trailing whitespace is trimmed. The lowercase names, https_proxy and http_proxy, are read too; the uppercase ones come first.
InvalidThe agent refuses to start: HTTPS_PROXY: not a proxy address; expected a URL such as http://proxy.example.com:3128, or HTTPS_PROXY: the proxy's scheme must be http, https or socks5; expected a URL such as http://proxy.example.com:3128. The value itself is never repeated: it may hold a password.

What never goes through a proxy, whatever the variables say: health checks, requests from Caddy to replicas, the Docker socket and Caddy's admin socket. Neither does a request to a name without a dot, a container or an application on the server's own networks, so those need no entry in NO_PROXY.

Images are not pulled by the agent. The Docker daemon pulls them, and it reads neither these variables nor /opt/shipwick/.env: it needs the proxy in /etc/docker/daemon.json. GET /server reports the agent's proxy next to the daemon's under network, and shipwick doctor warns when the agent has one and the daemon has none.

What is logged. At startup, requests that leave the server go through a proxy; images are pulled by the Docker daemon, which has a proxy setting of its own with the proxy's host and port and nothing else of its URL. A proxy that refuses a destination is named with the destination and its answer, so that the refusal is not mistaken for the destination's: the proxy proxy.example.com:3128 refused to connect to hooks.example.com:443 (403 Forbidden): check that the proxy allows this destination. For a 407 the advice is that the proxy wants a user and a password it accepts, given in HTTPS_PROXY.

SHIPWICK_CA_FILE ​

Since 0.6. A PEM file of certificate authorities, one or several, that the agent trusts in addition to the system's, for the webhook, the bucket and the sign-in provider: an endpoint, a bucket or a provider inside the company, or a proxy that opens TLS, presents a certificate that no public authority issued. See Run behind a corporate proxy or without internet.

FormatThe absolute path of the file as the agent sees it. For an agent in a container, the file is mounted there in compose.override.yml.
NormalizationLeading and trailing whitespace is trimmed.
InvalidThe agent refuses to start, and the message, prefixed with SHIPWICK_CA_FILE:, says what is wrong with the file.

The agent checks the file when it starts, before it makes any request:

The fileThe agent says
Is named by a relative path"ca.pem" is not an absolute path; give the file's full path as the agent sees it, such as /etc/shipwick/ca.pem
Does not exist/etc/shipwick/ca.pem does not exist; for an agent in a container, mount the file there in compose.override.yml
Is a directory/etc/shipwick/ca.pem is a directory, not a file; Docker creates one when the file it is told to mount does not exist on the server, so check the path left of the colon in compose.override.yml
Is larger than 4 MB/etc/shipwick/ca.pem is larger than 4 MB, which no bundle of certificate authorities is
Holds a server's certificate instead of its authority's/etc/shipwick/ca.pem: certificate 1 (hooks.example.internal) is a server's certificate, not an authority's; the file must hold the certificate of the authority that issued it (Example Internal CA)
Holds only certificates that have expired/etc/shipwick/ca.pem: every certificate in it has expired, the last on 2026-01-31
Holds a key and no certificate/etc/shipwick/ca.pem holds a private key and no certificate; the file must hold the authority's certificate only
Holds no certificate/etc/shipwick/ca.pem holds no certificate; expected PEM, one or more blocks that begin with -----BEGIN CERTIFICATE-----

An expired certificate next to one that is still valid is skipped, and so is a key next to a certificate. With a usable file the agent logs certificate authorities added to the system's with the file's path.

The variable is the agent's. Caddy needs the authority only to reach an ACME server of your own, and reads every certificate in /etc/ssl/certs: that is a second mount, shown under the production compose file. The Docker daemon has its own trust, /etc/docker/certs.d/<registry>/ca.crt. On a laptop, SHIPWICK_CA_FILE in the environment does the same for shipwick, for an agent whose certificate that authority issued; see the CLI reference.

SHIPWICK_DNS_RESOLVERS ​

Since 0.6. Who the agent asks whether a hostname points at the server, before it routes the hostname. See Routing and HTTPS.

Value
unsetPublic name servers. When none of them can be reached, the server's own resolver is asked, and the public ones are left alone for five minutes.
systemThe server's own resolver, from the start. Upper or lower case.
Addresses, 10.0.0.2,10.0.0.3Those name servers, separated by commas. Each is an IP address, with port 53 unless another is given: 10.0.0.2:5353. Not a hostname.

Leading and trailing whitespace is trimmed, around the value and around each address. Anything else is an error that names the entry: SHIPWICK_DNS_RESOLVERS: "ns1.example.internal" is not an IP address (expected "system", or name servers by address such as "10.0.0.2,10.0.0.3"); for a port that is none, "10.0.0.2:0" has no valid port.

Behind a firewall that lets no DNS out the default works by itself, since the server's resolver is asked when the public ones do not answer; hostnames that exist only inside the company are found that way too. system skips the public ones. At startup the agent logs hostnames are looked up with the server's own resolver, or hostnames are looked up with the name servers given with their addresses. See Run behind a corporate proxy or without internet.

SHIPWICK_ACME_DIRECTORY ​

Since 0.6. The directory URL of an ACME server of your own. Caddy then obtains and renews every certificate there and asks no public authority. For a server that Let's Encrypt cannot reach on ports 80 and 443 and that has no SHIPWICK_CLOUDFLARE_API_TOKEN; the other way is certificates you supply with shipwick cert set. See Run behind a corporate proxy or without internet.

FormatAn https URL with a host, such as https://ca.example.internal/acme/acme/directory. No credentials, query or fragment; no braces, quotes, backslashes or whitespace.
NormalizationLeading and trailing whitespace is trimmed.
InvalidThe agent refuses to start with one of expected the https URL of an ACME directory, such as https://ca.example.internal/acme/acme/directory, the directory must be a plain URL, without credentials or a query or the directory's URL must not contain braces, quotes or spaces, prefixed with the variable's name.
RequiresSHIPWICK_CADDY_ADMIN: SHIPWICK_ACME_DIRECTORY needs a reverse proxy to obtain certificates from it: set SHIPWICK_CADDY_ADMIN as well.

The ACME server's own certificate has to be trusted by Caddy, which is the mount into /etc/ssl/certs under the production compose file. At startup the agent logs certificates are obtained from an ACME server of your own, not from Let's Encrypt with the directory.

Sign-in ​

Since 0.6 the agent can leave the question of who someone is to an OpenID Connect provider: Google Workspace, Microsoft Entra, Okta, Keycloak, or any other. People then sign in to the dashboard there, and the rules made with shipwick access grant say what each of them may do. Tokens keep working as before. These variables name the provider and the client it registered for Shipwick; what to set at the provider and how the rules work is in Sign in with your company's accounts.

VariableDefault
SHIPWICK_OIDC_ISSUERnoneThe issuer URL: the URL under which the provider publishes /.well-known/openid-configuration, written exactly as the provider writes it there. https; plain http only for localhost and for loopback, private and link-local addresses. No credentials, query or fragment. Unset: tokens only.
SHIPWICK_OIDC_CLIENT_IDnoneThe client id the provider issued. Required with the issuer. Visible ASCII characters, at most 256.
SHIPWICK_OIDC_CLIENT_SECRETnoneThe client secret the provider issued. Required with the issuer: Shipwick is registered as a confidential (web) client. No control characters.
SHIPWICK_OIDC_SCOPESopenid email profileWhat is asked of the provider: names separated by spaces or commas. Must contain openid. Okta wants groups added for group rules.
SHIPWICK_OIDC_GROUPS_CLAIMgroupsThe claim of the ID token that lists a person's groups. Letters, digits and _ : . / -, at most 128 characters, so a namespaced claim such as https://example.com/groups is a name too.
SHIPWICK_OIDC_NAME_CLAIMemailThe claim of the ID token people are named by: email, preferred_username, upn, sub, or any other claim that holds one string. Rules, the audit trail and a deployment's by use that name. Since 0.7. See Accounts without an address.
SHIPWICK_OIDC_TENANTSnoneWith Microsoft Entra's issuer for several tenants, https://login.microsoftonline.com/organizations/v2.0 or …/common/v2.0: the tenant ids whose accounts may sign in, separated by commas, at most 100. * accepts every tenant and stands alone. Since 0.7. See Accounts of several Microsoft Entra tenants.
SHIPWICK_OIDC_REDIRECT_URLhttps://<SHIPWICK_DASHBOARD_DOMAIN>/auth/callbackDevelopment only: for a dashboard that runs on the developer's machine, http://localhost:3000/auth/callback. Only a URL on localhost or a loopback address, with the path /auth/callback, is accepted. On a server, leave it unset.

The values are trimmed. The provider sends people back to the dashboard, so the issuer needs SHIPWICK_DASHBOARD_DOMAIN, and the redirect URI to register at the provider is that hostname followed by /auth/callback.

The agent refuses to start with a provider that is configured in part or wrongly:

ProblemThe agent says
Another SHIPWICK_OIDC_* variable without the issuerSHIPWICK_OIDC_CLIENT_ID is set but SHIPWICK_OIDC_ISSUER is not
An issuer that is not a URLSHIPWICK_OIDC_ISSUER: must be an absolute URL such as https://accounts.example.com
An issuer over plain http on a public host, or with another schemeSHIPWICK_OIDC_ISSUER: must use https; http is allowed only for localhost and private addresses; SHIPWICK_OIDC_ISSUER: must use https
An issuer with a query or a fragmentSHIPWICK_OIDC_ISSUER: must be the issuer URL itself, without a query or a fragment
No client idSHIPWICK_OIDC_CLIENT_ID: the client id the provider issued for Shipwick is needed next to SHIPWICK_OIDC_ISSUER
No client secret, or one with control charactersSHIPWICK_OIDC_CLIENT_SECRET: the client secret the provider issued for Shipwick is needed next to SHIPWICK_OIDC_ISSUER; register Shipwick there as a confidential (web) client. The value itself is never repeated.
An invalid scopeSHIPWICK_OIDC_SCOPES: invalid scope "…" (expected names separated by spaces, e.g. "openid email profile")
Scopes without openidSHIPWICK_OIDC_SCOPES must contain openid: without it the provider issues no ID token
An invalid claim nameSHIPWICK_OIDC_GROUPS_CLAIM: invalid value "my groups" (expected the name of the ID token claim that lists groups, e.g. groups)
An invalid name claimSHIPWICK_OIDC_NAME_CLAIM: invalid value "user name" (expected the name of the ID token claim people are known by: email, preferred_username, upn or sub)
A tenant that is not a tenant idSHIPWICK_OIDC_TENANTS: invalid tenant "contoso" (expected tenant ids separated by commas, e.g. 8f0d4c2e-6a1b-4c3d-9e5f-0a1b2c3d4e5f, or * for any tenant)
* next to tenant idsSHIPWICK_OIDC_TENANTS: * accepts every tenant and stands alone; list tenant ids, or *, not both
Entra's issuer for several tenants without a listSHIPWICK_OIDC_ISSUER is Microsoft Entra's address for the accounts of every tenant: say which tenants may sign in with SHIPWICK_OIDC_TENANTS (their tenant ids, separated by commas), or use the issuer of your own tenant, https://login.microsoftonline.com/<tenant id>/v2.0
* with another name claim than subSHIPWICK_OIDC_TENANTS=* accepts the accounts of every tenant, whose administrators choose the addresses and user names in them: set SHIPWICK_OIDC_NAME_CLAIM=sub as well, so that people are named by what no tenant can choose, or list the tenants you trust
A redirect URL that is not on the developer's machineSHIPWICK_OIDC_REDIRECT_URL: only for a dashboard on the developer's machine, e.g. http://localhost:3000/auth/callback; on a server set SHIPWICK_DASHBOARD_DOMAIN and leave this unset
No dashboard hostnameSHIPWICK_OIDC_ISSUER needs the dashboard people sign in to: set SHIPWICK_DASHBOARD_DOMAIN as well

The agent reads the provider's endpoints and signing keys from the issuer and reads them again every hour, so a key the provider rotates needs nothing done here. A provider that is down stops sign-ins, not the agent: it is not asked at startup, and tokens and sessions that exist are not affected. A provider whose configuration names another issuer than the one set is refused at sign-in: the sign-in provider calls itself "…", and the agent is configured with "…": set SHIPWICK_OIDC_ISSUER to the issuer exactly as the provider states it. The one exception, since 0.7, is Entra's issuer for several tenants: there a token is believed only if its issuer is that address with the token's own tenant id in the placeholder's place, and the tenant is among SHIPWICK_OIDC_TENANTS.

Changing the name claim changes what everyone is called. Sessions that were named by the old claim end with their next request, as do the sessions of a tenant that was taken off the list; rules written for the old names match nobody until they are rewritten; the audit trail keeps the old names for what was done under them.

What is logged. At startup, people sign in to the dashboard with an OpenID Connect provider with the issuer and the redirect URL. The client secret is sent to the provider's token endpoint and nowhere else, and is never logged or returned by the API; the dashboard and the browser never see it. GET /server reports the issuer and the name claim under sign_in, and shipwick server status shows them as Sign-in.

The production compose file passes all of them from /opt/shipwick/.env except SHIPWICK_OIDC_REDIRECT_URL.

SHIPWICK_UPDATE_CHECK ​

Since 0.7 the agent asks GitHub once a day which release is the latest, and GET /server carries the answer as update: the dashboard and shipwick server status say when the server is behind, without a connection of their own.

Valueson, the default, or off. true and 1, false and 0 are read as the same.
InvalidSHIPWICK_UPDATE_CHECK: invalid value "never" (expected on or off)
The requestA HEAD request to https://github.com/shipwick/shipwick/releases/latest, without a body, a query or a cookie, with the User-Agent shipwick-agent: no version, no identifier of the server. The answer is a redirect whose target names the release; it is not followed.
ThroughThe proxy and the certificate authorities the agent was given: HTTPS_PROXY, SHIPWICK_CA_FILE.
When it failsThe request gives up after 15 seconds, nothing is logged above debug level, and the next attempt is a day later like any other.
Kept inupdate-check.json in the data directory, so that a restart asks nothing.

At startup the agent logs, once, the agent asks github.com once a day whether a newer release exists, and sends nothing about this server, with how to stop it. With off, GET /server says "enabled": false and the dashboard shows no notice. See What leaves the server unasked and Upgrade Shipwick.

The production compose file passes it from /opt/shipwick/.env.

Data directory ​

SHIPWICK_DATA_DIR defaults to:

PlatformDefault
Linux/var/lib/shipwick
Other<user config dir>/shipwick, or shipwick-data in the working directory if the user config directory cannot be determined

The agent image sets SHIPWICK_DATA_DIR=/var/lib/shipwick and declares it a volume. The production compose file mounts the agent-data volume there.

The directory is created with mode 0700 if it does not exist. It contains:

FileContent
shipwick.dbThe SQLite database: applications, deployments with their full configuration, replicas, events, job runs, metrics and traffic samples, the secrets stored with shipwick secret set, the registry credentials stored with shipwick registry login, the certificates supplied with shipwick cert set, the record of every backup, and the hashes of the tokens created with shipwick token create. Since 0.6 also the audit trail (the table audit_log), the rules that say who may sign in and as what (access_rules), the sessions of the people who signed in, by their hashes (sessions), and what the agent remembers across its own restarts about imports and a promotion (transfer_state). Since 0.7 also the index of the log archive (log_archives) and the references to stored secrets that are remembered with each deployment (deployment_references), encrypted like a secret. Environment values, basic-auth passwords, secrets, registry passwords and certificate keys are encrypted. It runs in WAL mode, so SQLite keeps its -wal and -shm files next to it.
encryption.keyThe key those values are encrypted with: 64 hexadecimal characters. Mode 0600. Created on the first start, unless SHIPWICK_ENCRYPTION_KEY is set, and replaced by a rotation. See SHIPWICK_ENCRYPTION_KEY.
encryption.key.newThe new key of a rotation. With the key in the file it exists only for the moment the rotation takes; with the key in SHIPWICK_ENCRYPTION_KEY it stays until the agent has been started with the new key.
agent-token.sha256The hex-encoded SHA-256 hash of a token the agent generated itself. Mode 0600. Present only if the agent ever generated its token.
backups/The backups the agent takes, unless SHIPWICK_BACKUP_DIR names another directory: <application>/<id>/<volume>.tar for an application's volumes, _agent/ for the agent's own state, _export/ for exports written to where backups go. With SHIPWICK_BACKUP_PASSPHRASE the files end in .enc. While a large file is being sent to the bucket, a note named <file>.upload lies next to it; an agent that finds one at its start aborts the upload it names. See Backups.
logs/The log archive, since 0.7: one gzip file for each kept run of a container, readable on the server with zcat; the database holds one row for each, not the output. Not encrypted, like the logs Docker keeps. Not in the backup of the agent's state, and not in an export. See SHIPWICK_LOG_RETENTION_DAYS and SHIPWICK_LOG_RETENTION_SIZE.
update-check.jsonWhat the agent last learned about releases, since 0.7, so that a restart does not ask again. See SHIPWICK_UPDATE_CHECK.
uploads/The folders of static applications uploaded with shipwick deploy, kept until they are deployed. Nothing here needs a backup: the next shipwick deploy uploads the folder again.

Protect this directory, and back it up as a whole

shipwick.db and encryption.key belong together: the database is only readable with the key, and the key is only useful with the database. Anyone who can read both can read every application's secrets, so the directory stays 0700. A backup of one without the other is worthless. The agent backs up both itself, encrypted, once SHIPWICK_BACKUP_PASSPHRASE is set; a copy that stays in backups/ on the same disk does not survive the loss of the server, which is what the bucket is for.

The database schema is migrated automatically at startup. An agent refuses to open a database whose schema is newer than it supports, and asks to be upgraded.

API token ​

The agent authenticates every API request, except GET /api/v1/health, against the SHA-256 hash of a token. Every token has a role, and every endpoint requires one; a role includes the ones below it:

RoleMay
readSee everything: the server, the applications, deployments, logs, events, metrics, traffic, the backups taken, the names of the secrets, the registries a credential is stored for, the supplied certificates without their keys, the volumes. GET /metrics for a Prometheus scraper needs no more.
deployAnd change what runs: deploy, redeploy, roll back, stop, start, run commands, upload images and static folders, take a backup and verify one. Since 0.7: get an application's deploy.yaml back.
adminAnd everything else: delete applications, manage tokens, secrets, registry credentials and certificates, rotate the encryption key, download, restore and remove backups and volumes, back up the agent's state, export and import, pull and promote on a standby. Since 0.6: read the audit trail, manage the rules that say who may sign in, and adopt backups.

There are two kinds of token. The root token is the one this section is about: the token the agent is configured with, through SHIPWICK_AGENT_TOKEN or generated on the first start. It has the admin role and the name root, it is not stored in the database, and it cannot be revoked through the API. It is the one the installer prints, and the one to keep for yourself.

Every other token is created with shipwick token create <name> --role read|deploy|admin, is shown exactly once, and is stored as a hash in shipwick.db with its name and role. shipwick token ls shows when each was last used; shipwick token revoke <name> ends it. Give CI a deploy token and people admin ones. A wrong or revoked token is 401 UNAUTHORIZED; a valid token whose role does not cover the request is 403 FORBIDDEN, and the answer says which role it has and which it needs. After 20 failed authentications within a minute from one client address, the agent answers wrong tokens from that address with 429 RATE_LIMITED and a Retry-After header for the next minute; a valid token is never refused, and GET /api/v1/health is not limited. Deployments record which token made them. See Create tokens for CI and teammates.

Since 0.6 a deploy token can be limited to the applications named with --app, and any created token can be given an end with --expires. A limited token that asks for something else is refused with 403 TOKEN_LIMITED and a message that names its applications; an expired one with 401 TOKEN_EXPIRED and when it expired. The root token is neither limited nor does it expire. Since 0.7 shipwick token update changes a token's applications and its end; its value and its role stay. Every request that changes something is written to the audit trail. With a sign-in provider configured, a person who signed in to the dashboard is the same kind of caller a token is, with a role and perhaps a list of applications, for a session of ten hours.

The root token's hash is determined at startup, in this order:

  1. SHIPWICK_AGENT_TOKEN, when set, always wins. Its hash is kept in memory. Nothing is written to disk.
  2. Otherwise, the hash persisted in the data directory by a previous run (agent-token.sha256).
  3. Otherwise, a token is generated: swk_ followed by 64 hexadecimal characters, from 32 random bytes. Only its hash is persisted. The token itself is printed once to standard output.

The agent only ever keeps the hash, in memory and on disk. A generated token cannot be recovered afterwards. If the hash file is corrupt, the agent refuses to start and says so: delete the file to generate a new token, or set SHIPWICK_AGENT_TOKEN.

A generated token is printed directly to standard output, never through the logger, so it does not end up in log aggregation by way of the log stream. Under Docker, however, "printed" means it is in the container's log (docker logs) for as long as that container exists. The installer avoids this by generating the token itself and passing it in as SHIPWICK_AGENT_TOKEN. Do the same when setting things up by hand, for example with openssl rand -hex 32.

To change the root token, set a new SHIPWICK_AGENT_TOKEN and restart the agent. Tokens created with shipwick token create are not affected; they live in the database. Running applications are not affected by an agent restart.

Subcommands ​

text
shipwick-agent [healthcheck|version]
Invocation
shipwick-agentRun the agent.
shipwick-agent versionPrint the version and exit.
shipwick-agent healthcheckProbe the agent configured by the same environment: GET /api/v1/health on the port of SHIPWICK_LISTEN_ADDR, on 127.0.0.1 if the listen host is unspecified, with a 3 second timeout. Exits 0 on HTTP 200 and 1 otherwise.

healthcheck exists for container health checks: the agent image ships no shell, curl or wget. The image declares it as its HEALTHCHECK, with an interval of 10 seconds, a timeout of 5 seconds, a start period of 5 seconds and 3 retries.

Any other arguments are an error. The agent has no flags.

Startup and shutdown ​

At startup the agent reads its environment, loads the certificate authorities of SHIPWICK_CA_FILE when it is set, resolves the root token and the encryption key, opens the database and encrypts any values an earlier release left in plain text, connects to Docker, ensures the two application networks exist and joins the first if the agent runs in a container, resumes the deployments it finds mid-flight and removes leftover containers, syncs the proxy, starts the supervisor, the webhook sender, the backup scheduler and the scheduled export or standby import, and then serves the API. Opening the database also settles a key rotation that was interrupted: the pending key is promoted or discarded, whichever fits the data. Startup work is bounded by 30 seconds. If Docker is unreachable, the agent exits with an error. If Caddy is unreachable, it logs the error and keeps retrying in the background. If the backup scheduler cannot be started, the agent logs could not start the backup scheduler; no backups are taken until the agent is restarted and carries on.

On SIGINT or SIGTERM the agent shuts down gracefully within 30 seconds; a deployment that is running is left as it is and resumed at the next start, and queued notifications get 5 more seconds to be delivered. A second signal kills it immediately. See Architecture.

The production compose file ​

configs/compose.production.yml runs the agent, Caddy and the dashboard as one Compose project, which the file names shipwick. The installer writes it to /opt/shipwick/compose.yml. Since 0.6 the agent finds the proxy's container in the compose project it runs in itself, whatever that project is called; before, an installation started under another project name (docker compose -p, COMPOSE_PROJECT_NAME) had no traffic figures, and its static applications failed to deploy. The file reads these variables from a .env file next to it:

VariableDefault
SHIPWICK_AGENT_TOKENrequiredPassed to the agent. Compose refuses to start without it.
SHIPWICK_AGENT_DOMAINemptyPassed to the agent. Leave empty to not expose the API through Caddy.
SHIPWICK_DASHBOARD_DOMAINemptyPassed to the agent. Leave empty to not expose the dashboard.
SHIPWICK_WEBHOOK_URLemptyPassed to the agent. Leave empty for no notifications.
SHIPWICK_WEBHOOK_SECRETemptyPassed to the agent.
SHIPWICK_CLOUDFLARE_API_TOKENemptyPassed to the agent. Leave empty to obtain certificates from the server itself.
SHIPWICK_ALERT_MEMORY_PERCENT, SHIPWICK_ALERT_DISK_PERCENTemptyPassed to the agent. Empty means the defaults, 90 and 85.
SHIPWICK_LOG_RETENTION_DAYS, SHIPWICK_LOG_RETENTION_SIZEemptyPassed to the agent. Empty means the defaults, 14 days and 1gb; a size of 0 keeps nothing. Since 0.7.
SHIPWICK_BACKUP_PASSPHRASEemptyPassed to the agent. Leave empty for backups that are not encrypted, and no backup of the agent's own state.
SHIPWICK_BACKUP_S3_ENDPOINT, SHIPWICK_BACKUP_S3_BUCKET, SHIPWICK_BACKUP_S3_ACCESS_KEY_ID, SHIPWICK_BACKUP_S3_SECRET_ACCESS_KEY, SHIPWICK_BACKUP_S3_REGION, SHIPWICK_BACKUP_S3_PREFIXemptyPassed to the agent. Leave empty for backups that stay on the server.
SHIPWICK_EXPORT_SCHEDULE, SHIPWICK_EXPORT_KEEP, SHIPWICK_STANDBY_SCHEDULEemptyPassed to the agent.
HTTPS_PROXY, HTTP_PROXY, NO_PROXYemptyPassed to the agent and to Caddy. Leave empty on a server with a plain connection. Since 0.6.
SHIPWICK_CA_FILEemptyPassed to the agent: the path as its container sees it. The file itself is mounted in compose.override.yml, below. Since 0.6.
SHIPWICK_DNS_RESOLVERS, SHIPWICK_ACME_DIRECTORYemptyPassed to the agent. Empty means the public resolvers and Let's Encrypt. Since 0.6.
SHIPWICK_OIDC_ISSUER, SHIPWICK_OIDC_CLIENT_ID, SHIPWICK_OIDC_CLIENT_SECRET, SHIPWICK_OIDC_SCOPES, SHIPWICK_OIDC_GROUPS_CLAIMemptyPassed to the agent. Leave empty for tokens only. Needs SHIPWICK_DASHBOARD_DOMAIN. Since 0.6.
SHIPWICK_OIDC_NAME_CLAIM, SHIPWICK_OIDC_TENANTSemptyPassed to the agent. Empty means people are named by email, and no issuer for several tenants. Since 0.7.
SHIPWICK_UPDATE_CHECKemptyPassed to the agent. off stops its daily question to github.com about a newer release. Since 0.7.
SHIPWICK_AGENTSemptyPassed to the dashboard: several servers in this one dashboard, as name=URL pairs. Set, it replaces the SHIPWICK_AGENT_URL the file fixes. Since 0.6.
SHIPWICK_HTTP_PORT80Host port published for Caddy's port 80.
SHIPWICK_HTTPS_PORT443Host port published for Caddy's port 443, TCP and UDP.
SHIPWICK_AGENT_IMAGEghcr.io/shipwick/agent:latestAgent image.
SHIPWICK_DASHBOARD_IMAGEghcr.io/shipwick/dashboard:latestDashboard image.
SHIPWICK_CADDY_IMAGEghcr.io/shipwick/caddy:latestProxy image. Since 0.5.
SHIPWICK_SOCKET_PROXY_IMAGEwollomatic/socket-proxy:1.13.1The image of the socket proxy the agent reaches Docker through, when another than the one the release pins. The installer keeps it across upgrades, and shipwick server configure writes it. Since 1.1.
SHIPWICK_DOCKER_SOCKET/var/run/docker.sockThe daemon's socket on the server, which the socket proxy mounts. A rootless daemon's is /run/user/<uid>/docker.sock, which compose.rootless.yml sets. Since 1.1.
SHIPWICK_SOCKET_PROXY_LOG_LEVELINFODEBUG makes the socket proxy log every request it lets through, next to the ones it refuses. Since 1.1.

The image defaults above are those of the file in the repository. In the copy that belongs to a release, which is what the installer fetches, the three Shipwick images are pinned to that release's version, and the socket proxy's to a version of its own.

Every row of the agent's table is read by the agent from its environment, but on a server the installer set up only the rows this file reads reach it from .env: the ones install.sh --help lists, and the two hostnames. The rest the file decides itself — the listen address, the data directory, SHIPWICK_CADDY_ADMIN, SHIPWICK_LOG_FORMAT=json — so SHIPWICK_LOG_LEVEL=debug in .env changes nothing; a change to one of those is a compose.override.yml. The package reads every row from /etc/shipwick/agent.env.

The installer writes .env once, on the first install, with the token and the two hostnames. A port, an image, a webhook variable, the Cloudflare token, the backup passphrase, an S3 variable or one of the three schedule variables that is set in the environment of that first run is written too, and so are the two alert thresholds. Since 0.6 the same holds for the three proxy variables, which the installer also uses for its own downloads, for SHIPWICK_CA_FILE, SHIPWICK_DNS_RESOLVERS, SHIPWICK_ACME_DIRECTORY, the five SHIPWICK_OIDC_* variables the file passes, and SHIPWICK_AGENTS; and since 0.7 for SHIPWICK_OIDC_NAME_CLAIM, SHIPWICK_OIDC_TENANTS, the two log retention variables and SHIPWICK_UPDATE_CHECK; and since 1.1 for SHIPWICK_SOCKET_PROXY_IMAGE, which shipwick server configure writes as well. An existing .env is never rewritten, so to add or change any of them later, edit /opt/shipwick/.env and run cd /opt/shipwick && docker compose up -d. SHIPWICK_PROXY_TLS_ADDR is not among the file's variables: the agent finds the proxy at caddy:443. To set it, give it to the agent under environment in compose.override.yml.

Override the ports only if something else owns 80 and 443. Automatic HTTPS needs the real ones to be reachable from the internet.

SHIPWICK_CADDY_IMAGE ​

Since 0.5 the proxy is Shipwick's own build of Caddy, ghcr.io/shipwick/caddy: Caddy 2.11.6 with the Cloudflare DNS module and, since 0.8, Shipwick's own way of finding replicas, and nothing else added. The official image has no DNS providers, and a certificate for a hostname behind Cloudflare's proxy, or for a wildcard, can only be obtained through a DNS record. Every installation runs this image, whether or not SHIPWICK_CLOUDFLARE_API_TOKEN is set, and it is pinned to the release like the agent and the dashboard: the agent generates this Caddy's configuration, so a newer Caddy arrives with a release of Shipwick, not on its own. Since 1.0 the image is built with golang.org/x/net 0.60.0, which closes five HTTP/2 server vulnerabilities of 0.59.0 (GO-2026-6603, -6610, -6611, -6612 and -6617); Caddy 2.11.6 itself still names 0.59.0, and it is the module Shipwick adds that raises the version.

SHIPWICK_CADDY_IMAGE in .env names another image, one you built from Dockerfile.caddy for instance. The installer removes the images of earlier releases from the ghcr.io/shipwick/caddy repository, as it does for the agent and the dashboard, and keeps the one the compose file names.

Since 0.8 an image of your own has to be built from that Dockerfile to have Shipwick's part. The agent also works with a Caddy that lacks it — the official image, or the proxy of a release before 0.8 — the way it did before: a name lookup that Docker leaves unanswered then holds the requests to every application for five seconds, and applications deployed together wait for each other. shipwick doctor, the dashboard and proxy.plain_lookups in GET /server say so, and the agent offers the proxy its own way again once a minute. See A proxy image of your own.

The file fixes the rest of the agent's configuration:

SettingValue
SHIPWICK_CADDY_ADMINunix//run/caddy/admin.sock, a socket in the caddy-admin volume that only the agent and Caddy mount
SHIPWICK_LOG_FORMATjson
Dashboard's SHIPWICK_AGENT_URLhttp://agent:9000, on the control network. SHIPWICK_AGENTS in .env replaces it.
Agent portNot published. The only ways in are Caddy and the server itself.
Caddyghcr.io/shipwick/caddy, started with a bootstrap configuration that contains only the admin socket. The agent loads the real configuration, which also compresses responses with zstd or gzip when the client asks for it.
NetworksThree. shipwick: application containers and Caddy; the agent joins it by itself, for health checks, and does not listen there. shipwick-services: Caddy and application containers, where Caddy finds an application's replicas by its name. shipwick-control, since 0.8: the agent, Caddy and the dashboard, and nothing else; the API is reached there. Before 0.8 all three services shared shipwick with the applications
DOCKER_HOSTunix:///run/docker-proxy/docker.sock, since 1.1: the filtered socket the socket proxy makes, in the docker-proxy volume that only the two mount. The agent is given no other way to the daemon.
LogsEach of the four containers keeps at most 3 files of 10 MB, like application replicas
Restart policyunless-stopped for all four services

Volumes:

VolumeMounted inContent
agent-dataagent, at /var/lib/shipwickThe data directory: the database, the encryption key and the backups the agent takes. Back this volume up, or let the agent do it: see Backups.
caddy-dataCaddy, at /dataCertificates. Back this volume up, and do not delete it casually.
caddy-configCaddy, at /configThe configuration the agent loaded last; Caddy is started with --resume. With SHIPWICK_CLOUDFLARE_API_TOKEN set it contains that token, and it contains the keys of supplied certificates. Mounted by Caddy alone.
caddy-staticCaddy, at /srv/shipwickThe folders of static applications: the agent puts them there and Caddy serves them itself, with no container in between. Nothing here needs a backup.
caddy-adminagent and Caddy, at /run/caddyThe admin socket
docker-proxyagent and the socket proxy, at /run/docker-proxyThe filtered Docker socket the proxy makes and the agent uses. Since 1.1

Since 1.1 the agent mounts no Docker socket. The socket proxy mounts /var/run/docker.sock (SHIPWICK_DOCKER_SOCKET), which is root-equivalent access to the server, and the agent has only the socket in docker-proxy; before 1.1 the agent mounted the daemon's socket itself. See The Docker socket.

The installer replaces /opt/shipwick/compose.yml on every upgrade, and removes the agent, dashboard and proxy images of earlier releases once the upgraded agent is healthy. Your own changes belong in /opt/shipwick/compose.override.yml, which Compose merges with it and the installer never touches. The most common ones:

  • Private images, with docker login. Since 0.5 the agent keeps registry credentials itself, stored with shipwick registry login, and needs no mount for them. A mount of the server's docker login credentials into the agent, /root/.docker/config.json:/root/.docker/config.json:ro, keeps working for registries without a stored credential. See Pull from private registries.
  • Backups on another disk. Mount the disk into the agent and set SHIPWICK_BACKUP_DIR to the mount point. See Backups.
  • No hostname for the API. Leave SHIPWICK_AGENT_DOMAIN empty and publish the API on the server's loopback only, with ports: ["127.0.0.1:9000:9000"] on the agent, then reach it through an SSH tunnel. A published port wants Docker 28 or later; before that it leaves the API open to the containers of applications. See Reach the API without a hostname.
  • Certificate authorities of your own. Since 0.6. Put the authority's certificate on the server, set SHIPWICK_CA_FILE in .env to the path the agent's container sees, and mount the file. The first mount is for the agent, which trusts the authorities for the webhook and the bucket. The second is for Caddy, which needs the authority only to reach an ACME server of your own and reads every certificate in /etc/ssl/certs. See SHIPWICK_CA_FILE.
bash
SHIPWICK_CA_FILE=/etc/shipwick/ca.pem          # in /opt/shipwick/.env
yaml
services:
  agent:
    volumes:
      - /etc/shipwick/ca.pem:/etc/shipwick/ca.pem:ro
  caddy:
    volumes:
      - /etc/shipwick/ca.pem:/etc/ssl/certs/shipwick-ca.pem:ro

Overlays: the socket itself, and rootless Docker ​

Two files of the repository are overlays on the production compose file; neither is what the installer sets up. A third arrangement, since 0.9, is not an overlay: Docker's authorization plugin with configs/docker-authz.rego, installed into the daemon, which leaves the compose file as it is, the socket proxy included. See The Docker socket.

FileVariableDefault
compose.direct-socket.ymlSHIPWICK_DOCKER_SOCKET/var/run/docker.sockSince 1.1. Takes the socket proxy out and gives the agent the daemon's socket itself, the way every installation before 1.1 had it: it replaces the agent's list of mounts (!override) and removes the proxy's service (!reset), which takes Docker Compose 2.24.4 or newer. The agent then says so, in GET /server, shipwick server status and shipwick doctor. See The socket itself.
compose.rootless.ymlSHIPWICK_DOCKER_SOCKET$XDG_RUNTIME_DIR/docker.sockThe rootless daemon's socket, handed to the socket proxy in place of /var/run/docker.sock; the agent is behind the proxy as on any server. Setting the variable in .env makes the overlay unnecessary. See Rootless Docker.

compose.socket-proxy.yml, the overlay of 0.8 to 1.0 that put the proxy in by hand, is gone from the repository: since 1.1 the production compose file has the proxy. A server that kept that overlay as its compose.override.yml keeps running, and the installer says to take the socket-proxy service and the docker-proxy volume out of it; see Upgrading from 1.0 to 1.1.

Dashboard variables ​

The dashboard is a separate program with a server of its own, and reads its own environment. It has no token variable on purpose: it does not know a token until someone signs in with it, and then keeps it only in that browser's cookie. See The dashboard.

VariableDefaultMeaning
SHIPWICK_AGENT_URLhttp://127.0.0.1:9000Base URL of the agent, as the dashboard's server reaches it. The production compose file sets it to http://agent:9000.
SHIPWICK_AGENTSnoneSeveral servers in one dashboard: name=URL pairs separated by commas or spaces. Set, it replaces SHIPWICK_AGENT_URL. Since 0.6.
SHIPWICK_COOKIE_SECUREautotrue or false forces the Secure flag of the session cookie. Auto: on when the request is https, directly or by X-Forwarded-Proto.
HOST, PORT0.0.0.0, 3000The address the dashboard's server listens on.

SHIPWICK_AGENTS ​

Since 0.6. The servers one dashboard shows:

bash
# /opt/shipwick/.env on the server whose dashboard you use
SHIPWICK_AGENTS=production=http://agent:9000,staging=https://agent.staging.example.com
Formatname=URL pairs separated by commas or spaces. At most 20.
NameLowercase letters, digits and dashes, starting and ending with a letter or digit, at most 40 characters. Each name once.
URLThe agent as the dashboard's server reaches it, http or https: the same address shipwick login --url takes. Another server's agent needs a hostname (SHIPWICK_AGENT_DOMAIN) or a private network between the two.
InvalidSHIPWICK_AGENTS: "…" is not a name=URL pair, e.g. production=http://agent:9000; SHIPWICK_AGENTS: invalid server name "Prod": use lowercase letters, digits and dashes (max 40 characters), e.g. production; SHIPWICK_AGENTS: the name "staging" is used twice; SHIPWICK_AGENTS lists 21 servers; at most 20 are supported.

Each server has its own sign-in, kept in a cookie of its own, and every address carries its server, /applications/web?server=staging. With SHIPWICK_AGENT_URL alone nothing changes. See Several servers in one dashboard.

Running the agent as a service of the host ​

Since 0.7 the agent is published as a Debian and an RPM package, which install it as /usr/bin/shipwick-agent with a systemd unit. Its variables are then in /etc/shipwick/agent.env, one NAME=value a line without quotes, and a change takes systemctl restart shipwick-agent. As the package writes the file:

VariableValue
SHIPWICK_AGENT_TOKENgenerated64 hexadecimal characters, generated when the package was first installed.
SHIPWICK_LISTEN_ADDR127.0.0.1:9000For the dashboard, the address of Docker's bridge instead: 172.17.0.1:9000 unless Docker was configured otherwise. Since 0.8 a hostname for the API needs no change here: with SHIPWICK_AGENT_DOMAIN set the agent also listens on the address the server has on the shipwick-control network, where the proxy reaches it.
SHIPWICK_CADDY_ADMINunix//run/shipwick/admin.sockThe admin socket of the proxy the package's compose file starts.
SHIPWICK_PROXY_TLS_ADDR127.0.0.1:443Where the agent reads the certificates the proxy serves.
SHIPWICK_LOG_FORMATtext

The unit sets SHIPWICK_DATA_DIR=/var/lib/shipwick and HOME=/root, where docker login as root keeps credentials for private images. The proxy and the dashboard stay containers: Caddy finds the replicas of an application by name on a Docker network, which a Caddy installed on the host cannot do. See Install from a package.

As a host process on Linux the agent reaches container addresses directly. With Docker Desktop on macOS or Windows it cannot, and warns at startup: applications with a health block cannot be deployed by a host-process agent there.