Services and shared variables
Most projects start as one application with one set of variables. As soon as a project runs as several parts — an API, a worker, a frontend, an auth service — each part needs its own PORT, its own DATABASE_URL or its own process name, while a handful of settings (SUPABASE_URL, SENTRY_DSN) are the same for everyone.
Services let you describe exactly that inside one project and one environment.
The two kinds of variables
| Belongs to | Who receives it | |
|---|---|---|
| Shared variable | No service | Every service, and every sync target of the environment |
| Scoped variable | One service (for example api) | Only that service's sync target, plus any Whole environment target |
A variable is shared by default. You make it scoped by picking a service when you create or edit it.
No services in your project? Then every variable is shared and nothing on this page applies yet. You will not see the service controls until you add a service.
Before you begin
- You need to be an owner or admin of the organization to add or delete services.
- Services are defined per project and apply to every environment of that project.
Adding a service
Open the project settings
Go to your project and click Settings. Scroll to the Services section.
Click Add Service
Give the service a short name — the name of the part of your stack that will run with these variables, such as api, worker or frontend. A description is optional.
Save
The service is now available in every environment of the project. Existing variables stay shared; nothing changes until you assign them.
A service cannot be deleted while it still has variables or sync targets. Move its variables to another service (or make them shared) and remove its targets in Integrations first. This protects you from a service's secrets silently becoming shared and being pushed everywhere.
Working with services on the variables page
Once a project has at least one service, the variables page gains a few controls.
The Show filter
Above the variables list you'll see Show: followed by chips:
- All — every variable in the environment, shared and scoped
- Shared only — variables with no service (the ones every sync target receives)
- One chip per service — that service's variables plus the shared ones, which is exactly what that service's sync target pushes
Each row shows a small label with the service it belongs to, or Shared.
Choosing a service for a variable
The Add Variable and Edit forms have a Service field. Leave it on Shared (no service) for settings everyone needs, or pick a service to send the variable only to that service.
If you opened the form while a service chip was selected in the filter, that service is pre-selected.
The same key in several services
A key can exist once as a shared variable and once per service. PORT can be 3000 for api and 4000 for worker; each service's sync target receives its own value.
Importing into a service
When you import a .env file, the import dialog shows Import to service. All imported keys get that service; leave it on Shared (no service) to import them as shared variables.
Moving variables in bulk
Select several rows with the checkboxes, open Assign Service in the bulk toolbar and pick a service — or Shared — to move them all at once.
Services in the CLI
The CLI understands services through the --service flag:
# Pull only what the worker needs: its own variables plus the shared ones
envmanager pull --service worker
# Push a .env file into a service (creating the service if needed)
envmanager push --service worker --create
# Set one variable on a service
envmanager set WORKER_CONCURRENCY=4 --service worker
# Create a service without pushing anything
envmanager service create worker --description "Background jobs"
Without --service, commands work on the shared variables (or on every scope, for list and diff). See the CLI commands reference for details.
Sending each service to the right place
Services decide which variables belong together. Sync targets decide where they go: each integration can have one target for the shared variables and one per service, all in the same environment.
- A service with no target is unmapped — its variables stay in EnvManager only, and the Integrations page warns you.
- GitHub always receives the whole environment, including every service.
Read Sync Targets per Service to set this up.