Deploy a container service

This page walks creating and deploying a container service. For the concept overview see Container services. The Containers entry must appear in your sidebar — if not, the container services aren’t enabled on this deployment — contact your team admin.

​

Before you start

• An OCI/Docker image reachable from the agent. Public registries work; private registries need credentials configured on the agent.
• The in-container port your service listens on.
• A team you belong to with admin rights to manage services.

​

Create the service

1. Open Containers in the sidebar.
2. Click Create service.
3. Fill in the form:

   Field	Notes
   Slug	Lowercase, 3–100 chars, letters/digits/hyphens. Used in API paths. Immutable.
   Display name	Human-readable label.
   Description	Optional notes for teammates.
   Docker image	repo/image:tag or image@sha256:....
   Exposed port	Port the container listens on (1–65535). Defaults to 8080.
   Health path	HTTP path Cloud probes for health. Defaults to /health.
   Env vars	Key/value pairs passed into the container.
   Volumes	Host-path → container-path mounts (for shared models, persistent state).
   Required labels	Agent labels required to host this service.
   GPU count	0 (none, default), a positive integer for a specific count, or -1 for “all GPUs on the host”.
   Replica count	How many instances to keep running (1–10).

4. Click Create. The service appears in the list as created (definition saved, no replicas scheduled yet).

​

Deploy

From the service detail page, click Deploy. The state moves through deploying → running as agents pull the image and the health probe starts succeeding. If no replica becomes healthy, the service moves to failed. Replicas are placed across eligible agents. If you ask for more replicas than you have eligible agents, the extras stay pending until more agents come online with matching labels.

​

Update

• Edit — change definition fields. Image, exposed port, and volume changes generally need a redeploy to take effect on running replicas.
• Undeploy — stop replicas. The definition is preserved; you can redeploy later without re-entering anything.
• Delete — remove the definition. Replicas are stopped first.

​

Observability

The detail page shows:

• Per-instance status and health probe result.
• Logs from running replicas.

​

Troubleshooting

Stuck in deploying — agents are pulling the image or the health probe is failing. Check the agent’s logs; common causes are private-registry credentials missing on the agent, or the health path returning non-2xx. Crash-looping — the container’s main process is exiting. Read the replica’s logs from the detail page. Not picked up — the service’s required labels don’t match any agent’s. Compare labels in the service form and on the Agents page.

​

Related

• Container services — concept.
• Agents — what hosts the containers and how labels work.