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.
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. |
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
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
[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). |
| 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.
| 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
