Most people running a staging copy keep the relationship in their head: this deployment is the test one, that deployment is the real one, and the difference between them is whatever they remember changing. Projects and environments make that relationship explicit, so the platform can compare the two and move a release between them.
Nothing about this changes how your apps run. It is an organizational layer over deployments you already have.
What you get
- Projects that group environments such as staging and production
- Components inside each environment, linked to existing applications, with a role: web, worker, database or cache
- Comparison between two environments of the same project, showing variable names only
- The foundation for promotion: a grouped image promotion needs the same project, component and role on both sides
- A hostname switch between two running apps on the same server
What linking does and does not do
Linking an application to an environment does not deploy it, change its networking, copy its variables or share its credentials. The app keeps its ID, its history and its runtime configuration exactly as they are. Detaching removes only the association; the application and its data stay.
Roles are labels. Choosing database for a component does not validate an engine, provision anything or grant network access. If you want an actual database connection, that is the PostgreSQL binding, and it uses these associations as a prerequisite rather than replacing them.
Set it up
Create the project
In My Apps, switch to Advanced view and open Projects and environments, then create a project for the system you are organizing. Names are lowercase, start with a letter and hold up to 48 characters.
Create the environments
Create staging and production inside it. An account can hold up to 50 projects, each with up to 20 environments and up to 100 linked services per environment.
Link the apps you already run
Select an environment and an existing application, give the component a name and pick its role. Attach only apps that are running or failed, with no pending operation.
Use the same names on both sides
This is the step that pays off later. The staging web app and the production web app must share the same component name and the same role, or the platform cannot pair them for comparison or promotion.
Compare the two environments
Open the comparison view for the pair. It groups variables as equal, different, or present on one side only, and it shows source descriptors and connection state. It never returns values or credential digests.
That is deliberate. You find out that production has a variable staging is missing, or that both define the same name differently, without the platform ever handing a secret back through the portal, the API or a chat with an AI assistant. It answers “what differs”, not “what is it set to”. Local MCP needs 0.38.0 or later for this view.
Moving a hostname between environments
A traffic switch moves one hostname from one running custom app to another on the same server. The destination must currently have no hostname, and previews cannot take part.
Before applying, the target has to be running, any Docker healthcheck it declares has to be healthy, and a local HTTPS route probe has to succeed: connection errors and 5xx responses are rejected. The source keeps running after the switch, so you still have the previous version in place.
Requires agent 0.6.16 or later, and the agent has to announce traffic switching support. Update existing agents explicitly before relying on it.
The probe checks that the route answers locally. It does not certify that your application is correct, and it does not validate public DNS or TLS. A brief interruption during the switch remains possible, so treat it as a planned moment rather than something invisible to visitors.
An application belongs to at most one environment, and a component name is unique inside its environment. A conflicting association is refused rather than silently applied. To move an app, detach it with confirmation first, then attach it where you want it.
What this increment does not do
No inherited environment variables, no automatic dependency wiring, no deployment ordering, no project rename or delete, and no automatic provisioning of applications. Linking a database or cache component does not create a connection or open network access.
Saved deployment plans are a different feature: they describe reusable deploy inputs, while projects organize applications that already run.
Start now
Get an offshore VPS with the agent preselected, then set up the release path: promote an image to production, connect a PostgreSQL database and recover from a failed deployment.