Projects, environments & services
Everything you run on Koo fits one hierarchy: your account contains projects, a project contains environments, and an environment contains services. This page gives you the mental model; the task guides build on it.
The resource model
| Resource | What it is | ID prefix |
|---|---|---|
| Account | Your tenant: the handle, the members, the plan — the billing unit | acct_ |
| Project | A named group of environments | proj_ |
| Environment | A deployment target inside a project; it holds the services | env_ |
| Service | A running unit: a web service, a Postgres database, or a Redis database | svc_ |
| Deployment | An immutable, numbered version of one service | dep_ |
Every resource has a stable, prefixed ID. Services are the one exception in the API: within their environment they are addressed by name, not by ID.
An account owns everything and pays for everything. It has a unique handle, its own members and roles, and one plan.
A project groups the environments of one piece of software. Creating a project also creates its first environment, named production.
An environment is where services actually run — production, staging, whatever you need. You work on an environment through its canvas — see The canvas & staged changes.
A service is a running unit inside an environment: your own code as a web service, or a database.
A deployment is created every time a service deploys — an immutable version you can return to. See Deployments & rollback.
One word deliberately missing from this list: on Koo, an app is a published showcase listing, never something you deploy — see Publish your app.
Names are permanent
Projects, environments, and services all follow the same naming rule: lowercase letters, digits, and dashes; 3–16 characters; starting with a letter and ending with a letter or digit.
Names are immutable, so pick them carefully. A project name is unique within your account, an environment name within its project, and a service name within its environment.
The name is the identity. Renaming a service means deleting it and creating a new one; projects and environments cannot be renamed at all.
Web services: modes and sources
A web service runs your code in one of four modes: standard (always on), serverless (scales to zero when idle), cron (runs on a schedule, takes no traffic), or volume (with an attached persistent disk). See Service modes.
Its code comes from one of three sources: a GitHub repository (Deploy from Git), a container image (Deploy a container), or an archive uploaded with the CLI (koo up).
Databases
Postgres and Redis services are databases: no code to deploy, no deploy pipeline, and never reachable from the internet.
Services in the same environment reach a database over Koo's private network. You wire the two together with a connection variable on the consuming service — see Connect a database.
Locations and replicas
Locations belong to the service, not the environment: each service picks the locations it runs in, with a fixed replica count per location.
There is no autoscaler — no minimum/maximum replica range, and no metric-based scaling. For a serverless service the per-location count is its scale ceiling instead of a fixed count. See Locations and Resources & scaling.
Plan ceilings
On the Free plan the ceilings are the free allowance itself: a single project with its production environment, and one service of each type at the free size (0.5 vCPU / 1 GiB). Paid plans raise the counts — see Usage & limits.