# Environments

A project can have several environments - for example production and staging. Each environment tracks its own branch, environment variables, domain, and container, so you can run the same codebase in parallel configurations without them stepping on each other.

## Production and beyond

Every project gets a **production** environment automatically, tied to your default branch. On paid plans you can add more, each pointing at its own branch. When you push, orkestr matches the pushed branch to an environment and redeploys only that one - so a push to your staging branch never touches production.

```bash
production   ->  main
staging      ->  develop
preview-pr   ->  feature/checkout
```

## Containers and URLs

- Production serves at `{project}.orkestr.run`.
- Non-production environments get their own distinct subdomain.
- Each environment runs its own isolated container with its own resource allocation, so load or a crash in one never affects another.

## Environment variables

Set variables per environment from its page. They are encrypted at rest and injected into the container on the next deploy, so a variable change requires a redeploy to take effect. This is deliberate: it keeps a running container's configuration immutable and reproducible.

- Each environment has an independent set of variables - staging can point at a staging database while production points at the real one.
- Names starting with `ORKESTR_` are reserved for the runtime.
- Add-on connection details are injected as variables automatically when you attach a database or cache.

## Per-environment resources

Container CPU and memory come from your plan. On paid plans you can raise an environment's memory toward the plan's burst ceiling - useful when one environment (say production) needs more headroom than the others.

## Sharing and access control

Any environment can be made private and shared like a document. Visitors hit a sign-in page instead of your app, enter their email, and get a one-time sign-in link in their inbox. If they're allowed, they're in - your app needs no auth code at all, and never sees an unauthenticated request.

From the environment's **Share with people** panel, pick who gets in:

- **Just my workspace** - you and your team members sign in with their own emails. Nothing to maintain; workspace invites and removals apply automatically.
- **Specific people** - an explicit email list (up to 100), inside or outside your workspace. Ideal for clients and stakeholders.

Signed-in visitors stay signed in for 7 days per browser. Your app receives the visitor's email in the `X-Orkestr-User-Email` request header - use it for display or per-user logic, or ignore it entirely.

> **Two speeds**
>
> Turning sharing on or off redeploys the environment (the Save button becomes **Save & redeploy** and handles it). Everything else - adding or removing emails, workspace membership changes - applies within seconds, and cuts off existing sessions too: removing someone locks them out on all their devices without a redeploy.

Sharing is available on Pro and above, works on the environment's `orkestr.run` URL and custom domains alike, and can also be driven from the CLI, API, and MCP via the environment's `access_policy`.

## How other features use environments

- A [Job](https://orkestr.eu/docs/features/jobs) runs against a specific environment's current image and inherits that environment's variables.
- [Deployments](https://orkestr.eu/docs/features/deployments) are per environment - each environment has its own deploy history and rollback target.
- [Add-ons](https://orkestr.eu/docs/features/addons) attach at the project level and surface their connection variables to environments.

> **Plan limits**
>
> Starter: 1 environment. Pro: 3 per project. Enterprise: unlimited.

## FAQ

### What is the difference between an environment and a project?

A project is the repo and its overall configuration. An environment is one deployable instance of that project, tied to a branch, with its own variables and container.

### Do environments share a database?

Only if you point them at the same one. Each environment has its own variables, so you decide whether staging and production share data or run against separate add-ons.

### Why didn't my variable change take effect?

Variables are baked into the container at deploy time. Trigger a redeploy of that environment after changing them.

### I enabled sharing but the app is still public - why?

Enforcement attaches at deploy time. Use **Save & redeploy** in the sharing panel (or deploy the environment) and it takes effect when the deploy completes. Email list changes while sharing is on don't need this - they apply within seconds.

### Do people I share with need an orkestr account?

No. They sign in to your app with just their email and the link it receives - no account, no password.