Configuration

RemoteMux merges configuration from several sources so you can override defaults per project.

Resolution Order

Highest precedence first:

CLI flags for config values such as --backend or --api-base-url
Local ./.rmux.toml
Environment variables

Hosted RemoteMux auth is resolved separately from project config:

RMUX_API_KEY
Stored hosted auth selected with rmux auth use or rmux login

Stored hosted auth is single-mode: either an OAuth session or an API key, never both at once. .rmux.toml is not a hosted auth source. In CI, you can skip ./.rmux.toml entirely if the job sets the required config env vars such as RMUX_BACKEND and RMUX_API_BASE_URL. Use these commands to inspect and switch hosted auth explicitly:

rmux auth status
rmux auth use oauth
rmux auth use api-key --token <api-key>
rmux auth clear

Config Files

Path	Scope
`./.rmux.toml`	Project-local config for this directory.

Legacy rmux.conf and .rmux.conf are still read, but rmux configure writes ./.rmux.toml.

rmux configure            # interactive setup, writes ./.rmux.toml
rmux configure --show     # print resolved config after all merges

When backend=managed, interactive rmux configure prompts for the hosted auth mode on every run so you can explicitly choose OAuth or API key auth for that project. Do not commit .rmux.toml if it contains service tokens or cloud credentials. On hosted backends, organizationId and projectId in .rmux.toml set the default scope for commands like rmux env new, rmux usage, and rmux token create.

Backend Selection

rmux configure --backend aws
rmux configure --backend gcp
rmux configure --backend e2b
rmux configure --backend managed

The config format is TOML with top-level [aws], [gcp], [e2b], and [managed] tables. A single file can carry settings for multiple backends; the backend key decides which is active. Legacy aliases local (aws) and cloud (managed) are still accepted.

Example `.rmux.toml`

backend = "gcp"
apiBaseUrl = "https://api.remotemux.com"
organizationId = "org_123"
projectId = "proj_123"

[aws]
region = "us-east-1"
authMode = "aws-cli"
profile = "default"
vpcId = "vpc-123456"
subnetIds = ["subnet-a", "subnet-b"]
securityGroupIds = ["sg-123"]
instanceType = "t3.large"
workspaceBucket = "rmux-byoc-workspaces"
previewDomain = "preview.rmux.dev"

[gcp]
authMode = "gcloud-cli"
projectId = "rmux-dev"
region = "us-central1"
zone = "us-central1-a"
network = "default"
subnetwork = "default-us-central1"
machineType = "e2-standard-4"

[e2b]
apiKey = "e2b_xxx"
template = "base"
previewDomain = "preview.rmux.dev"
timeoutMs = 3600000

[managed]
region = "us-east-1"
instanceType = "t3.large"
previewDomain = "preview.rmux.dev"

Full Settings Reference

Core

Setting	Environment variable	Notes
`backend`	`RMUX_BACKEND`	`aws`, `gcp`, `e2b`, or `managed`.
`apiBaseUrl`	`RMUX_API_BASE_URL`	Control plane URL.
`organizationId`	`RMUX_ORGANIZATION_ID`	Default hosted organization for new environments, usage, and token creation.
`projectId`	`RMUX_PROJECT_ID`	Default hosted project scope within the selected organization.
`brewServices`		Optional machine bootstrap services. Example: `["redis", "temporal"]`.
`environment` (env var only)	`RMUX_ENVIRONMENT`	Target environment by name or ID for workspace commands (useful in CI).

Hosted auth is environment/session only:

Environment variable	Notes
`RMUX_API_KEY`	Explicit hosted auth override for the current shell or process. If unset, `rmux` falls back to the stored auth selected with `rmux auth use` or `rmux login`.

AWS

Setting	Environment variable	Notes
`aws.region`	`RMUX_AWS_REGION`	AWS region.
`aws.vpcId`	`RMUX_AWS_VPC_ID`	VPC for auto-discovered subnets and security groups.
`aws.authMode`	`RMUX_AWS_AUTH_MODE`	`aws-cli`, `env`, or `access-key`.
`aws.profile`	`RMUX_AWS_PROFILE`	AWS profile for `aws-cli` auth mode.
`aws.accessKeyId`	`RMUX_AWS_ACCESS_KEY_ID`	Access key for `access-key` auth mode.
`aws.secretAccessKey`	`RMUX_AWS_SECRET_ACCESS_KEY`	Secret key for `access-key` auth mode.
`aws.sessionToken`	`RMUX_AWS_SESSION_TOKEN`	Optional session token.
`aws.subnetIds`	`RMUX_AWS_SUBNET_IDS`	Comma-separated in env var form.
`aws.securityGroupIds`	`RMUX_AWS_SECURITY_GROUP_IDS`	Comma-separated in env var form.
`aws.instanceType`	`RMUX_AWS_INSTANCE_TYPE`	EC2 instance type.
`aws.workspaceBucket`	`RMUX_AWS_WORKSPACE_BUCKET`	Required for staged flows. BYOC path can auto-resolve.
`aws.previewDomain`	`RMUX_AWS_PREVIEW_DOMAIN`	Reserved for future BYOC ingress. AWS BYOC exposed ports currently use direct public-IP URLs.

GCP

Setting	Environment variable	Notes
`gcp.authMode`	`RMUX_GCP_AUTH_MODE`	`gcloud-cli` or `credentials-file`. Defaults to `gcloud-cli` unless a credentials file is set.
`gcp.projectId`	`RMUX_GCP_PROJECT_ID`	Required.
`gcp.region`	`RMUX_GCP_REGION`	Optional if `zone` is set.
`gcp.zone`	`RMUX_GCP_ZONE`	Required in practice.
`gcp.network`	`RMUX_GCP_NETWORK`	VPC network.
`gcp.subnetwork`	`RMUX_GCP_SUBNETWORK`	Optional subnetwork.
`gcp.machineType`	`RMUX_GCP_MACHINE_TYPE`	Compute Engine machine type.
`gcp.previewDomain`	`RMUX_GCP_PREVIEW_DOMAIN`	Reserved for future ingress. GCP BYOC exposed ports currently use direct public-IP URLs.
`gcp.credentialsFile`	`RMUX_GCP_CREDENTIALS_FILE`	Path to a service-account JSON key or another credential file accepted by `gcloud auth login --cred-file`. `gcloud` must still be installed for attach and remote commands.
`gcp.impersonateServiceAccount`	`RMUX_GCP_IMPERSONATE_SERVICE_ACCOUNT`	Optional service account email passed to `gcloud --impersonate-service-account`.

E2B

Setting	Environment variable	Notes
`e2b.apiKey`	`RMUX_E2B_API_KEY`	Required.
`e2b.template`	`RMUX_E2B_TEMPLATE`	Defaults to `base`.
`e2b.previewDomain`	`RMUX_E2B_PREVIEW_DOMAIN`	Preview/share-link domain. Defaults to `preview.rmux.dev`.
`e2b.timeoutMs`	`RMUX_E2B_TIMEOUT_MS`	Sandbox timeout in milliseconds.
`e2b.domain`	`RMUX_E2B_DOMAIN`	Optional API domain override.

Managed

The managed backend provisions sandbox environments through the control plane. Users only need backend = "managed" plus either a stored hosted auth selection or RMUX_API_KEY for hosted auth. No cloud credentials or infrastructure settings are required.

Tooling Overrides

Environment variable	Notes
`RMUX_SESSION_MANAGER_PLUGIN_PATH`	Point RemoteMux at a specific Session Manager plugin binary.
`RMUX_SESSION_MANAGER_PLUGIN_DIR`	Point RemoteMux at a directory containing the plugin.

List-valued variables (subnet IDs, security group IDs) use comma-separated values.

rmux configure --help    # full flag surface
rmux configure --show    # resolved config for current directory

Getting Started

Core Concepts

Guides

Backends

Reference

Resolution Order

Config Files

Backend Selection

Example `.rmux.toml`

Full Settings Reference

Core

AWS

GCP

E2B

Managed

Tooling Overrides

​Resolution Order

​Config Files

​Backend Selection

​Example .rmux.toml

​Full Settings Reference

​Core

​AWS

​GCP

​E2B

​Managed

​Tooling Overrides

Resolution Order

Config Files

Backend Selection

Example `.rmux.toml`

Full Settings Reference

Core

AWS

GCP

E2B

Managed

Tooling Overrides