Environments

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

rmux env new              # create and bind to current directory
rmux workspace new main   # bootstrap the project workspace

Inspect

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

rmux env down       # stop compute, preserve state
rmux env destroy    # remove entirely, clear local binding

Target another environment by name or ID:

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

Getting Started

Core Concepts

Guides

Backends

Reference

What An Environment Contains

One Environment Per Directory

Hosted Ownership

Lifecycle Commands

Create

Inspect

Stop and destroy

Environment-Level State

​What An Environment Contains

​One Environment Per Directory

​Hosted Ownership

​Lifecycle Commands

​Create

​Inspect

​Stop and destroy

​Environment-Level State

What An Environment Contains

One Environment Per Directory

Hosted Ownership

Lifecycle Commands

Create

Inspect

Stop and destroy

Environment-Level State