> ## Documentation Index
> Fetch the complete documentation index at: https://docs.remotemux.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Environments

> What a RemoteMux environment is, what lives in it, and how its lifecycle works.

An environment is the long-lived remote runtime for one project directory.

## What An Environment Contains

| Part            | Meaning                                                       |
| --------------- | ------------------------------------------------------------- |
| Remote runtime  | The VM or sandbox RemoteMux provisions for the project.       |
| Remote root     | `/workspace`, the shared project root once bootstrapped.      |
| Workspace set   | The default `main` workspace plus any named workspaces.       |
| Lifecycle state | `provisioning`, `ready`, `stopped`, `destroying`, or `error`. |

## One Environment Per Directory

When you run `rmux env new`, RemoteMux creates the environment and binds the current directory to it. When you run `rmux workspace new main`, RemoteMux seeds `/workspace` from the current local state, restores Git state, and creates the default `main` workspace.

After bootstrap, RemoteMux does not keep local and remote files in sync. Use `rmux env sync` or git for ongoing code movement.

## Hosted Ownership

On the hosted control plane, an environment belongs to an organization and optionally a project.

* Visibility comes from that org/project scope.
* Plan limits and `rmux usage` are evaluated against that scope.
* The token or session that created the environment is kept for audit attribution, but it is not the environment's ownership boundary.

If you set `organizationId` or `projectId` in `.rmux.toml`, or via `RMUX_ORGANIZATION_ID` / `RMUX_PROJECT_ID`, new hosted environments default to that scope.

## Lifecycle Commands

### Create

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
rmux env new              # create and bind to current directory
rmux workspace new main   # bootstrap the project workspace
```

### Inspect

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
rmux env status     # provider, runtime state, last sync, workspaces
rmux env list       # all environments visible to the current backend
rmux workspace ls   # workspaces in the current environment
rmux usage          # summary for the active org/project scope
```

### Stop and destroy

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
rmux env down       # stop compute, preserve state
rmux env destroy    # remove entirely, clear local binding
```

Target another environment by name or ID:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
rmux env down env_123
rmux env destroy my-project
rmux env down --all
rmux env destroy --all
```

If multiple environments share the same name, RemoteMux fails instead of guessing. Destroy is retryable -- if cleanup partially fails, rerun `rmux env destroy`.

## Environment-Level State

* Secrets: `rmux env secrets set`, `rmux env secrets ls`, `rmux env secrets rm`
* Exposed ports: `rmux env expose 3000`, `rmux env ports`
* Environment IDs: shown by `rmux env list` and `rmux usage`