> ## 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. # 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: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} rmux auth status rmux auth use oauth rmux auth use api-key --token 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`. ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} 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 ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} 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` ```toml theme={"theme":{"light":"github-light","dark":"github-dark"}} 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. ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} rmux configure --help # full flag surface rmux configure --show # resolved config for current directory ```