Tutorial

Hosting

What a Service is, what you set on it, and the path from a push to a request.

Checked 2026-10-08

A Service is one deployable workload. It has a source — a repository, or an image by digest — and everything after that is the platform's: the build, the Release, the rollout, the routes, and the scaling down to zero when nobody is calling.

#The parts you set

#From a push to a request

1. Source. A SourceLink links the project to one repository through a forge connection. Source is read at an exact commit, with a token narrowed to that repository; a webhook only says that something changed.
2. Build. The build turns the source into an image — a release candidate identified by its digest.
3. Release. A Release is the immutable desired state of an environment's workloads. Writing a newer one supersedes the live one; a rollback is a new Release naming older digests.
4. Rollout. A Rollout moves one Service generation to its Release in waves — a canary Cell, one Cell, one region, all — and no wave advances without fresh recorded evidence.
5. Routes. A Route sends one exact host and path prefix to one backend. Every destination has its own Route; a wildcard grants no authority.
6. Previews. A Preview is a pull request's own deployment of the Service, built and torn down by the same Git flow.

#It idles to zero

scaling.min_instances defaults to zero, which means no traffic means no instances: the first request after a quiet spell wakes the Service. There is nothing to start, and nothing to shut down. Raise the floor only where a cold start is worse than the idle cost.

#Client deadlines and retries during a cold wake

A wake includes scheduling, any image pull, and application startup. Allow that time before the first response; a short client timeout can expire while the Service is still starting. Cold-wake latency is not a fixed guarantee.

For clients calling your deployed application's HTTP route:

• Set one overall deadline for the operation, including attempts and waits. As a starting policy, allow 60 seconds and at most three attempts; tune this to your application's startup time and the caller's latency budget. These are client recommendations, not a platform timeout or latency promise.
• Retry a connection failure, timeout, or HTTP 502, 503 or 504 only when replay is safe. These failures can also indicate an unhealthy application, not just a wake. Do not treat every error as a cold start.
• Start backoff at 500 ms, double it after each failure up to 5 seconds, and add random jitter so callers do not retry together. If the response includes Retry-After, wait at least the specified seconds or until its HTTP date; do not assume every wake error includes this header. Stop if the wait would exhaust the overall deadline, and never reset that deadline on a retry.
• Reads such as GET and HEAD are normally safe to replay. Retry a write only if your application implements idempotency for it; reuse the same application idempotency key and body across attempts. A timeout does not prove that the server failed to commit the write. Hosting does not add idempotency to your application's endpoints.

For WebSockets, apply the same bounded backoff to connection attempts. After connecting, use your application's session-resume protocol; reconnecting does not restore a previous socket or make replaying messages safe. When attempts or the deadline run out, surface the failure rather than retrying forever.

Name

orgs/{org}/projects/{project}/envs/{env}/services/{service}

Id

svc_<location><ulid>

A Service's name is a path, and the same path works in the API, the CLI and the console. hosting:read covers the reads; everything that changes the Service needs hosting:write.