Projects and environments¶
A project groups the services of one tenant and lists the environments they may live in. Every service is in
exactly one project and one of that project's environments. Use projects to keep apps apart (web, billing,
bots), and environments to keep stages of one app apart (production, staging, pr-42).
flowchart LR
T["Tenant acme"] --> D["Project default<br/>environments: production"]
T --> W["Project web<br/>environments: production, staging"]
D --> S1["service hello<br/>production"]
W --> S2["service front<br/>production"]
W --> S3["service front-staging<br/>staging"]
W --> S4["service api-staging<br/>staging"]
| Project | Environment | |
|---|---|---|
| Is | An object with an id (prj_…), a slug and a name |
A label (^[a-z][a-z0-9-]{0,31}$) in a project's list |
| Every tenant has | A default project |
production in the default project |
| A service has | One, chosen at creation, never changed | One of its project's, changeable |
| Decides | Grouping and filtering (service list --project) |
Grouping, and which services may call each other |
Service slugs are unique on the whole node, not per project or environment (the slug is the URL /s/{slug}), so two
projects cannot both hold a service called api. Name the staging copy api-staging, or use one slug per environment in
your CI script.
Create a project¶
Creating, changing and deleting a project needs services:write and a key with no project or environment
restriction (an unrestricted tenant key, or the operator with x-rt-tenant). Listing needs services:read.
$ 21ci project create web --name "Web shop" --env production,staging
ID: prj_01M4Q2GB5APYBGEPYPBX1X4ZYJ
Slug: web
Name: Web shop
Environments: production, staging
Created: 2026-10-12T04:12:20Z
$ 21ci project list
ID SLUG NAME ENVIRONMENTS
prj_01M4Q2FNM85KHERVGN5ZJAK0TK default Default production
prj_01M4Q2GB5APYBGEPYPBX1X4ZYJ web Web shop production,staging
curl -sS -X POST "$RT_API/v1/projects" \
-H "Authorization: Bearer $RT_KEY" -H 'Content-Type: application/json' \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"slug":"web","name":"Web shop","environments":["production","staging"]}'
# 201 {"id":"prj_…","tenant_id":"ten_…","slug":"web","name":"Web shop","environments":["production","staging"],…}
curl -sS -H "Authorization: Bearer $RT_KEY" "$RT_API/v1/projects"
# {"items":[…],"next_cursor":null}
- The slug matches
^[a-z][a-z0-9-]{1,62}$and is fixed at creation. The name defaults to the slug. - A project has 1 to 20 environments,
["production"]when you give none. - A tenant holds at most 100 projects (
403 quota_exceeded); a taken slug is409 project_slug_taken. - Every command and route takes a project as its slug or its
prj_…id.
Add and remove environments¶
curl -sS -X PATCH "$RT_API/v1/projects/web" \
-H "Authorization: Bearer $RT_KEY" -H 'Content-Type: application/json' \
-d '{"environments":["production","staging","pr-42"]}'
curl -sS -H "Authorization: Bearer $RT_KEY" "$RT_API/v1/projects/web/environments"
# {"project":"prj_…","environments":["production","staging","pr-42"]}
PATCH takes the complete new list. 21ci reads the current one for --add-env and --remove-env.
An environment that a service is still in cannot be removed: 409 environment_in_use. Move or delete those services
first.
Create services in a project¶
Name the project when you create the service; the environment must be one of the project's.
$ 21ci service create front --project web --env production
$ 21ci service create front-staging --project web --env staging
$ 21ci push ./src --service api-staging --create --project web --env staging
$ 21ci service list --project web
ID SLUG RUNTIME PROJECT ENV LIVE BUILD ACCESS
svc_01M4Q2GB5APYBGEPYPBX1X4ZYJ front deno web production - pending public
svc_01M4Q2H2Q8B5C9V0D4E7F1G3HJ front-staging deno web staging - pending public
…
$ 21ci service list --project web --env staging
- Without a project the service goes into
default, without an environment intoproduction. - An environment the project does not list is
422 validation_failed, and the message lists the allowed ones. - The project of a service never changes: a
PATCHthat names another project is422. To move a service, create a new one in the other project and deploy the same code to it. - The environment can change (
21ci service update front-staging --env production), but only with a key that has no project or environment restriction, because the environment decides who may call the service. Each change is audited asservice.environment_changed.
Environments decide who may call¶
Service-to-service calls (std:services, std:host/call) and std:queue enqueues between services of a tenant are
admitted by the target's call.allowed_callers. With an empty list, only services of the same project in the same
environment may call it, so front-staging reaches api-staging but not api. Environment labels are per project:
a staging service of another project is not admitted by env:staging. A non-empty list names every admitted caller:
service slugs, svc_… ids or env:<environment> (of the target's own project). Details and examples are in
Configure a service and Calls and queues.
Delete a project¶
A project that still holds a service is 409 project_not_empty; delete or keep its services elsewhere first. The
default project is where services without a project go.
A typical layout¶
| Project | Environments | Services |
|---|---|---|
default |
production |
small one-off services |
web |
production, staging |
front, api, and front-staging, api-staging |
bots |
production, pr-<n> per pull request |
telegram, telegram-pr-42 |
In CI, create the preview environment and service on the first run of a pull request, deploy on every push, and remove both when the pull request closes:
21ci project update bots --add-env "pr-$PR" # once per pull request
21ci push ./src --service "telegram-pr-$PR" --create --project bots --env "pr-$PR" --wait
# when the pull request closes:
21ci service delete "telegram-pr-$PR"
21ci project update bots --remove-env "pr-$PR"
The CI key needs services:write and no project or environment restriction for the project changes; a key that only
deploys existing services can be narrower (see Get access).
See also¶
- Deploy and roll back: the full project → environment → service flow with a first deploy.
- Configure a service: environments and allowed callers on one service.
- API reference: every project route.
- CLI reference:
21ci project.