# Projects and environments A project groups the things that belong together, for example everything of one product. A project has **environments**, such as Production and Staging. Every service, cron job and database, and every Key Value instance, is in exactly one environment of exactly one project. **Projects only organize. They do not isolate.** An environment is a label, a filter for the Overview and a place to choose when you create something. All environments of a workspace share the same limits, the same members and roles, the same private network and the same namespace. A service in Staging can reach a private service in Production by its name, and a Staging database counts toward the same limits as a Production one. If two things must not reach each other, put them in separate [workspaces](/docs/workspaces.md). ## The Default project You do not have to use projects. Everything that exists, and everything you create without choosing an environment, is in the **Default** project, in its **Production** environment. Kilby creates that pair the first time something needs it. Nothing is moved or restarted when it does. While the workspace has only that one project with that one environment, the dashboard looks as it always did: no extra select, no extra breadcrumb. Add a second project, or a second environment, and the dashboard starts showing where each thing is: - The breadcrumb of the page of a service, cron job or database becomes **Workspace > Project > Environment > name**. The project and the environment are links. - The **Overview** gets a select to show one project, or one environment, and puts a header over each group. The choice is remembered for you and is in the address (`/dashboard?scope=...`), so you can share it. Only the list is filtered: the health line and the list of things that need attention stay about the whole workspace. - The forms that create something get an **Environment** row. It starts on the environment you last created something in, or on Production of the Default project. - The search box (Cmd+K or Ctrl+K) finds a project or an environment, and finds a service by the name of its project or environment. ## Create and manage projects Open [Projects](/dashboard/projects) (or press `G` then `P`). The list shows each project with its environments and how many services, cron jobs and databases and Key Value instances each holds. - **New project**: a name of up to 40 characters. Capitals, spaces and any letters are fine; a slash is not. Names are compared without regard to capitals. A new project starts with a Production environment. - **Add an environment** on the page of the project, for example Staging or Preview. The tabs of that page are its environments. - **Rename** a project or an environment from its page. Renaming changes nothing about what runs. A workspace can have up to 20 projects, the Default one included, and a project can have up to 10 environments. These limits only keep the lists short. They are not a limit on how much you can run: that is in [Limits and quotas](/docs/limits.md). ## Choose where something goes - **When you create it**, in the dashboard, the API, the CLI or a blueprint, choose an environment. Without one it goes in Production of the Default project. - **Later**, open the **Environment** section of its settings, choose another environment and click **Move**. Moving changes where it is listed, nothing else: the service, database or instance is not restarted, redeployed or touched, and its address, variables and links to other things stay as they are. The move is recorded on the Activity page with where it came from and where it went. Environment variable groups stay at the level of the workspace. A group is not tied to a project or an environment: any service of the workspace can link it ([Environment groups](/docs/environment-groups.md)). ## Delete a project or an environment - **The Default project and its Production environment cannot be deleted.** They hold everything that was created without a choice. You can rename them. - **A project keeps at least one environment.** To remove the last one, delete the project. - **Something that is empty** is deleted; the dashboard asks you to confirm first. - **Something that still holds resources** is not deleted until you choose another environment to move them to. Kilby names what is in it, and moves it without restarting anything. Nothing is ever deleted along with a project. ## Who can do what Roles belong to the workspace, as everywhere in Kilby. A project has no members and no roles of its own, and no role has more or less power in one project than in another. | Action | Permission | |---|---| | See projects and environments, filter the Overview | `view`: every role, a Viewer included | | Create and rename projects and environments, choose an environment when you create something, move something | `deploy`: Developer, Admin, Owner | | Delete a project or an environment | `workspace`: Admin, Owner | ## With the command line ```sh kilby projects # the projects with their environments kilby projects create "Checkout app" kilby projects add-environment "Checkout app" Staging kilby projects move api --environment "Checkout app/Staging" kilby projects delete "Checkout app" --move-to Default/Production ``` An environment is written as its id, as `PROJECT/ENVIRONMENT`, or as its name alone when only one environment has that name. `kilby deploy` and `kilby kv create` take `--environment` to place what they create. `kilby services` shows an Environment column once something is outside the default one. See [CLI](/docs/cli.md) for the exact help. ## With the API | Endpoint | What it does | |---|---| | `GET /api/v1/projects`, `GET /api/v1/projects/` | The projects with their environments and counts. The first call in a workspace creates the Default project. | | `POST /api/v1/projects`, `PATCH /api/v1/projects/` | Create or rename a project. Needs `deploy`. | | `DELETE /api/v1/projects/` | Delete a project. Refused with `409` while it holds resources, unless you add `?move_to=`. Needs `workspace`. | | `.../projects//environments` and `.../environments/` | List, create, rename and delete the environments of a project, with the same rules. | | `environment` on `POST /api/v1/services` and `/api/v1/databases` (and Key Value) | Where to list what you create. Answers carry an `environment` object with the project. | | `PATCH /api/v1/services/`, `/databases/` | Send only `{"environment": "Project/Environment"}` to move it. It is a request of its own, because nothing restarts. | The reference has the fields, the answers and examples: [API reference](/api/docs). ## In a blueprint A service or a database in a `kilby.yaml` can name a `project` and an `environment`. Applying the blueprint creates the project and the environment when they do not exist, and the plan says so. `project` alone means that project's Production; `environment` alone means an environment of the Default project. A resource that names neither is not managed by the blueprint in this respect: taking the lines out of the file does not move it back. A move in the file shows in the plan as an ordinary change that is never risky, because nothing restarts. See [Blueprints](/docs/blueprints.md). When you import a `render.yaml` that has `projects` and `environments`, each service and database keeps the project and the environment it was written under. Render's network isolation and protected environments have no equivalent here, and the conversion report says so. ## With an AI agent The MCP tool `list_projects` lists the projects and environments, so that an agent can pass `project/environment` to `create_service`. It only reads. Creating, renaming, deleting and moving are left to people. See [Use Kilby from an AI agent](/docs/agents.md). ## Related - [Services](/docs/services.md): the services and cron jobs that an environment holds. - [Environment groups](/docs/environment-groups.md): shared variables, which belong to the workspace and not to a project. - [Workspaces, roles and 2FA](/docs/workspaces.md): what really separates things, and who may do what. - [Blueprints](/docs/blueprints.md): `project` and `environment` in a file. - [Limits and quotas](/docs/limits.md): the limits every environment shares.