---
title: Environments | Runware Docs
url: https://runware.ai/docs/serverless/environments
description: Run the same app id once per environment, each copy with its own configuration, secrets and workers, under one organization and one bill.
relatedDocuments:
  - https://runware.ai/docs/serverless/core-concepts
  - https://runware.ai/docs/serverless/secrets
  - https://runware.ai/docs/serverless/compute-and-scaling
---
## Introduction

An environment is **a named place inside your organization where apps run**. The same app id can run in several of them, and each copy keeps its own configuration, its own versions, its own workers and its own secrets.

Every organization has `production`, and **a request that names no environment addresses it**. Nothing you have deployed so far moved: it is already there.

```bash
GET /v1/apps                        # production
GET /v1/apps?environment=staging    # the staging copies
```

The CLI takes the same choice on **`--env`**, on `deploy`, on `open` and on every `apps` and `secrets` command.

```bash
runware serverless apps list                  # production
runware serverless apps list --env staging    # the staging copies
```

**A command with no `--env` does not have to mean production.** `RUNWARE_ENV` picks the environment for one shell, `runware config set environment staging` picks it until you change it, and `--env` wins over both. The CLI says which one it used and where it came from before the command runs, and a name the API would refuse fails before any request is sent.

**The usage reports read the other way round.** `serverless usage` covers every environment until you narrow it with `--env`, and `usage events` covers the organization until you name an `--app`, whose copy then follows the default like any app command.

## One id, one copy per environment

The app id is the name of the application. **The environment chooses which copy a request reaches**, and the two are separate apps from there on: separate versions, separate workers, separate environment variables, separate secret attachments.

A copy is created where you first deploy it and **never moves**. Promoting what you tested is deploying the same source into another environment, which builds there. Deleting one copy leaves the others untouched.

> [!NOTE]
> Because a copy is its own app, an app id that runs in two environments **counts as two apps** everywhere you see a tally, and a cursor from a page of one environment is not valid in another.

## What an environment holds

<table><tbody><tr><td>Scoped to the environment</td><td>Shared by the organization</td></tr><tr><td>Apps, their versions, workers and environment variables</td><td>The API key you authenticate with</td></tr><tr><td>Secrets, and the attachments that expose them</td><td>The GPU types you can deploy on</td></tr><tr><td>Worker and GPU caps, and the monthly budget</td><td>The source archives a deploy builds from</td></tr><tr><td>The prefix every worker token here is issued under</td><td>OIDC connectors, which each app attaches for itself</td></tr></tbody></table>

**Reading an environment gives the prefix its worker tokens carry**, as `oidcSubjectPrefix`, so a cloud trust rule can name the environment before an app or a connector exists there. The prefix is built from the environment's `id`, which belongs to the environment rather than to its name: delete one and create it again under the same name and it gets a new `id`, so **a trust rule written against the old prefix stops matching**. See [OIDC connectors](https://runware.ai/docs/serverless/oidc-connectors).

**A secret of the same name in another environment is a different secret.** One call copies a secret into other environments with its value, so a credential reaches a second environment without being sent again, and each copy is its own secret from then on.

## Caps and the monthly budget

An environment has **a cap on the workers it holds and a cap on their GPUs**. Both are checked whenever a request adds capacity, so creating an app, deploying, resuming a stopped one and raising a worker count all go through them. They do not bound autoscaling: what is already running keeps scaling inside its own `maxWorkers`.

The count an environment is judged against is **what its other apps hold**, each the larger of its live workers and its keep-warm floor, plus what the request starts. A request that would cross a cap is refused, and the apps keep what they hold. Lowering a cap below what already runs refuses the next deploy rather than stopping anything.

**The monthly budget is a pay-as-you-go cap for the calendar month**, which resets on the 1st at 00:00 UTC. Percentages you choose send an email as the spend passes them, each at most once per month. Where `pauseAtBudget` is on, reaching the budget stops the environment's apps and refuses invocations until the budget is raised past the spend or the month turns.

> [!WARNING]
> Spend is read from settlement, so it **trails live usage by a few minutes**, and a worker's final adjustment by longer. A budget caps what gets billed, so a worker can run for minutes before its spend reaches the cap.

## Organization defaults

Every cap and the access setting have **an organization default that an environment inherits while it sets nothing of its own**. An environment reports both: the value set on it, and under `resolved` the value actually in force.

Changing a default reaches every environment that inherits that field at once, and **it does not roll what is already running**.

```bash
GET /v1/environment-defaults
PUT /v1/environment-defaults
```

## Managing them from the CLI

`runware serverless environments` covers the same surface as the API, and **none of its commands takes `--env`**: the name is the argument.

```bash
runware serverless environments list
runware serverless environments show staging
runware serverless environments create staging --max-workers 4 --budget 50 --pause-at-budget
runware serverless environments update staging --max-workers 8
runware serverless environments update staging --clear max-workers,budget
runware serverless environments delete staging --yes
runware serverless environments defaults show
runware serverless environments defaults set --max-workers 10
```

`create` and `update` take `--max-workers`, `--max-gpus`, `--budget`, `--alert-percents` and `--pause-at-budget`. On `update`, a flag you leave out keeps the value it had, and **`--clear` is how a setting goes away**: it takes `max-workers`, `max-gpus`, `budget` or `alert-percents`, comma-separated or repeated. A cleared cap inherits the organization default again, a cleared budget means no budget, and cleared alert percents send no alert.

`list` and `show` print `-` for a cap nothing sets and mark a value that comes from the organization defaults as inherited, so the three cases stay apart.

**`delete` asks before it runs** unless you pass `--yes`. An environment that still holds a live app or a secret is refused, and the refusal is followed by the commands that name what is left.

`defaults set` changes only the caps you name, because it reads the defaults and writes them back whole. **Two people changing them at the same time lose one of the changes**, so keep it to one place.

## Creating and deleting

A name is **1 to 63 characters**: lowercase letters, digits, hyphens, underscores and periods, starting with a letter or a digit. A name no live environment holds is free, including the name of one you deleted.

**An environment is deleted only once it is empty**, with no live app and no secret left in it. `production` is never deleted, and a deleted app's history still lists the environment it ran in.

## Where to go next

- [Core concepts](https://runware.ai/docs/serverless/core-concepts) for the nouns an environment holds
- [Secrets](https://runware.ai/docs/serverless/secrets) for what changes when the same name lives in two places
- [Compute and scaling](https://runware.ai/docs/serverless/compute-and-scaling) for the worker settings a cap is checked against
- [Errors](https://runware.ai/docs/serverless/errors#environment-cap-reached) for the answers a cap and a pause give