Services API

List an environment's services

Create a service

Creating a service stages its configuration; nothing runs until it is deployed. Managed databases are created with POST /environments/{environmentId}/databases. A Compose stack is kind: stack, sourceType: compose with config.stack.compose; the server derives config.stack.components. 422 invalid_compose (details.violations) when the compose file does not parse, uses something stacks do not support, or breaks the safe allow-list while the service's server does not have Unrestricted Compose.

Get the Docker option catalog

What the Docker options accept: capability lists, the curated sysctls, reserved label prefixes, stop signals and which options work only on an unrestricted server.

Get a service

Update a service's configuration (staged until deployed)

Requires If-Match: "<generation>". A stale value returns 412 generation_conflict. Every effective change increments the generation; the change takes effect on the next deployment.

Delete a service

Requires confirm=<slug>. A deployed service's container is removed from its server; volumes are kept unless deleteVolumes=true.

Clone a service

Creates a staged copy of a service in the same or another environment of the team; nothing runs until it is deployed. The clone gets the source's configuration (Docker options included), variables, volume definitions and, in the same environment, its outgoing links. Secrets are copied sealed and generated values are generated again. Volumes are new and empty (the data is not copied). A managed database is created new and empty with new credentials: restore a dump into it. Domains are dropped (default) or cloned with a suffix; 409 domain_conflict when a suffixed hostname is taken. Needs write access to the source and the target environment. Route services, Compose stacks and read replicas are not cloned (422 not_applicable). dryRun returns the plan and changes nothing; the response lists variable references that do not resolve in the target environment.

Get a service's deploy hook

Whether the hook is on, when its secret was created, and what the last call did. The secret and the URL are never returned here; urlPattern shows the URL with a placeholder.

Turn a service's deploy hook on or off

Turning the hook on creates a secret (at least 256 bits, stored only as a hash) and returns the complete url once; POST /hooks/deploy/<serviceId>/<secret> then deploys the service like a manual deploy, with trigger deploy_hook. Turning it off deletes the secret, so enabling again gives a new URL. Needs deployments:write.

Rotate a service's deploy hook secret

Replaces the secret of an enabled hook; the old URL stops working at once. The new url is returned once. 409 deploy_hook_disabled when the hook is off. Needs deployments:write.

Get a service's repository link

linked: false when the service has no link.

Link a service to a repository and set auto-deploy

Points the service's clone URL and branch at the repository (a staged change when they differ) and stores the auto-deploy settings, which are operational: they are applied immediately, never staged and never rolled back. A push to the branch deploys the service (trigger git_push) when a changed file matches the watch paths; a push during a running deployment is queued and the newest one deploys next. Webhooks are registered for GitLab, Gitea and Forgejo; GitHub uses the App's webhook and Bitbucket a webhook you create (see the connection). The webhook field reports the state.

Unlink a service from its repository

Stops auto-deploy. The clone URL and branch stay in the service's config.

List a service's health incidents

Stretches of time in which the service crashed, was unhealthy or restart-looped, newest first. An open incident has no resolvedAt.

Switch a service's maintenance mode

While enabled, the proxy answers every domain of the service with HTTP 503, a Retry-After header and the maintenance page (the same animated page as the automatic error pages), instead of reaching the service. It takes effect immediately, without a deployment, and keeps working through deployments of the service. It is an operational setting: never staged and never rolled back. A deployed service's server is sent the new route table; an undeployed service applies the setting with its first deployment. Idempotent: repeating the same request changes nothing. Switching off keeps the stored text for the next time. tcp/udp route services cannot be put into maintenance (422 maintenance_unsupported).

Preview a service's maintenance page

Returns the self-contained HTML page exactly as the proxy serves it (status 200 here; the proxy answers 503). Optional query parameters preview unsaved text.

Move a service to another environment

Stages a move of the service to another environment (of any project of the team): it keeps running where it is until its next deployment, which joins the new environment's network and resolves its variables there. Domains, volumes and data stay with the service. References are checked first: variables of the service that point at services staying behind, and variables of other services that point at the moved one, break. The move is refused with 409 move_blocked (details.plan) unless force is set; links on the canvas are removed, and the services that referenced the moved one are marked as having staged changes. A service in a replica group or with a cross-server link cannot be moved (409 move_blocked); route services and Compose stacks are not movable (422 not_applicable). dryRun returns the plan and changes nothing. Moving a service out of or into a production environment needs approval for guarded clients.

Staged changes not yet deployed

Field-level differences between the service's configuration and its current release. Secret values are masked.

Discard one staged change

Reverts a single field listed by pending-changes (config.<path>, server, variables.<KEY>, domains.<host>, volumes.<name>) to the state of the current release and advances the generation. 404 when the field is not pending. Returns the updated service.

Restart the running container

Queues a restart on the service's server. It completes when the agent acknowledges it.

Set a service's replica count and autoscaling

Runs the service on N replicas on its server (1-10) and/or turns CPU autoscaling on. Only stateless services qualify: no volumes, an HTTP port and kind other than database (422 replicas_require_stateless). A manual replicas value while autoscaling is enabled returns 409 autoscaling_enabled. The change applies immediately, without a deployment and without rebuilding: a deployed service is scaled through the agent, an undeployed one only stores the setting. It is never a staged change.

Stop the running container

Re-provision the service's tailnet node

Deletes the service's device from the tailnet and re-creates it with a fresh single-use key and a fresh state volume. Use it when the node needs attention (the device was removed in the admin console or its key was rejected). The device gets a new tailnet IP.