Published Services

Published services are Quilt’s HTTP and WebSocket ingress surface for containers.

Use them when a container is already running and you want a stable externally reachable URL without inventing your own proxy layer.

Primary Routes

POST   /api/containers/<container_id>/services
GET    /api/containers/<container_id>/services
GET    /api/services/<service_id>
DELETE /api/services/<service_id>
GET    /linx/<service_id>/...
POST   /linx/<service_id>/...
PUT    /linx/<service_id>/...
PATCH  /linx/<service_id>/...
DELETE /linx/<service_id>/...
HEAD   /linx/<service_id>/...
OPTIONS /linx/<service_id>/...

Create a Published Service

{
  "name": "amp",
  "target_port": 7001,
  "protocol": "http",
  "enable_websockets": true,
  "auth_mode": "service_token",
  "ttl_secs": 3600
}

Example response:

{
  "service_id": "lnx_123",
  "container_id": "ctr_123",
  "name": "amp",
  "target_port": 7001,
  "protocol": "http",
  "enable_websockets": true,
  "auth_mode": "service_token",
  "public_url": "https://backend.example.test/linx/lnx_123/?linx_token=...",
  "websocket_url": "wss://backend.example.test/linx/lnx_123/?linx_token=...",
  "status": "pending",
  "created_at": 1774626769,
  "updated_at": 1774626769,
  "expires_at": 1774630369
}

The Two Auth Modes

• service_token is the default. Quilt returns signed access URLs and validates the linx_token before proxying traffic.
• public removes the Quilt token requirement at the ingress layer and is appropriate only when you intentionally want open access.

Important Semantics

• protocol currently supports only http
• published services are tenant-scoped and persisted in sync-backed state
• published services require container networking to be enabled
• service lifetime lasts until explicit delete, container deletion, or optional TTL expiry
• public_url and websocket_url are derived from APP_BASE_URL, then BACKEND_DOMAIN, then forwarded or request host headers

Service Readiness Is Separate

Container readiness and published-service readiness are related, but they are not the same thing.

Possible published-service states:

• pending
• ready
• target_unreachable
• expired
• error

If the target container is not running, not network-ready, or not accepting connections, Quilt returns 503 Service Unavailable from the Linx path.

A Sensible Bring-Up Flow

1

Start the container first

Make sure the container exists and is actually exec_ready and network_ready.

2

Publish the target port

Create the published service against the container ID and the port your app is already listening on.

3

Use the returned URL

For service_token mode, use the signed URL Quilt returned instead of constructing one by hand.

4

Inspect service status if traffic fails

Check GET /api/services/<service_id> before assuming the proxy layer is broken.

Common Mistakes

Does publishing a service start my app listening on that port?

No. Quilt proxies to a container port that your application must already be serving.

If the container is running, is the published service automatically ready?

Not necessarily. Service readiness still depends on network reachability and the target port accepting connections.

Can I use published services for arbitrary TCP?

Not with this surface. Published services currently target HTTP traffic, with optional WebSocket upgrade support on the same path family.

Next Step

If you still need to create the workload itself, start with Containers.