Projects
A Project defines which parts of an application should share data, Config, Secrets, access rules, and operational context. Use one Project for Services that work together, and separate Projects when applications should have clear boundaries.
Last updated
AI agent? Start with llms.txt.
Group Services by the system they form
The web app that creates orders and the worker that processes them belong in the same Project because they need the same database and runtime values. Two unrelated automations usually belong in separate Projects even when the same team owns both. A Service stays in the Project it was created in, so add a new part to the Project whose data it uses.
This grouping changes how the application works. Services in a Project can use the Project's databases, Config, Secrets, private network, access settings, and members. That makes a Project one trust domain. Sign in and identity protect a Service from outside callers, not from its siblings, so put Services that should not trust each other in separate Projects. See How Tokay is organized for the full relationship between Workspaces, Projects, Services, and code.
Use the Project page to understand the whole app
The Project page brings related operational information together.
- Overview shows each Service and its current status.
- Databases contains databases, query consoles, imports, exports, and password rotation.
- Environment contains inspectable Config and protected Secrets shared by Services in the Project.
- Members controls who can operate the Project.
- Usage shows the Project's share of the Workspace server.
- Preview appears once the Project previews pushes. It holds what a preview runs with, what it can reach, and its links.
- Settings contains When you push, migration safety, the default copied into new web apps and functions, and the stop and delete controls.
Each web app and function chooses Public or Private, who is allowed, and any public routes on its own Access tab. Groups, Machines, and access activity for every Project live on the Workspace Access page.
A Project with one Service appears as a compact card on the dashboard. A Project with several Services expands to show how the application is doing as a group.
Deploy Services independently or together
Each Service has its own deployment history and health checked release. When several Services have updates ready, Deploy all starts them together without turning them into one release. A Service whose code, release and settings haven't changed keeps running; to restart one, deploy that Service. A blocker on one Service does not stop its siblings.
What happens when you push is also a Project setting. Each push can go live automatically, run in a preview first, or wait for a person. Two Projects can share the same Code, so staging goes live on every push while production waits for someone to release it.
Names help people navigate the system
Project and Service names can change as the application evolves. Renaming a web app changes the readable part of its URL, with redirects from earlier names, so web app renames are limited to three. See Web apps for the URL behavior.
An empty Project is valid and keeps its settings until you are ready to add Services.