Configuration

Config resolution, files, environment variables, and the full settings reference for all backends.

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

Resolution Order

Highest precedence first:

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

Hosted RemoteMux auth is resolved separately from project config:

1. RMUX_API_KEY
2. 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