Skip to main content

​
Start Here

When RMUX behaves unexpectedly, start with the commands that show resolved config and the current environment state: 
rmux configure --show
rmux env status
rmux session ls
Then run the backend-specific validation command when it applies: 
rmux aws-check
rmux gcp-check
The current directory is part of the RMUX identity model. Many problems come from running commands outside the directory that created the environment binding.

​
Binding And Directory Problems

You are either in the wrong local directory or you have not created an environment for this project yet. Re-enter the project directory that originally ran rmux new, or create a new environment from the current directory.
RMUX already has a local binding for this project. Use rmux session attach to reconnect, rmux env status to inspect the current environment, or rmux env destroy if you really want to replace it.

​
AWS Problems

Confirm that backend=aws is selected, your AWS credentials are valid, and the resolved region is the one you expect. rmux configure --show is the fastest way to verify the merged config for the current directory.
Attach on aws and managed uses the AWS Session Manager plugin. Published RMUX binaries include the sidecar automatically. If you are running from a source checkout, stage it with bun run stage:session-manager-plugin.If you already have the plugin somewhere else, point RMUX at it with RMUX_SESSION_MANAGER_PLUGIN_PATH.
This means RMUX does not have a workspace bucket to use for staged sync. If you are using the default BYOC path, rerun rmux aws-check or rmux new and let RMUX resolve or create the default shared resources. If you are using explicit AWS networking settings, configure --workspace-bucket or aws.workspaceBucket directly.

​
GCP Problems

Enable the Compute Engine API in the target project, then rerun rmux gcp-check. RMUX’s GCP preflight is read-only, so this is usually the first hard failure you should fix.
Verify that the active gcloud account, project, and zone match the RMUX config for this directory. rmux configure --show should line up with gcloud auth list and the project you actually intend to use.

​
Managed Backend Problems

Double-check apiBaseUrl, apiKey, and the managed AWS settings resolved for this directory. Local development can use http://localhost:4000 and the seeded rmux_dev_key, but hosted deployments normally require issued API keys and deployment-specific networking values.
If your deployment relies on short-lived AWS attach credentials, confirm that managed.attachRoleArn is set correctly for that environment and that the control plane can mint the expected credentials.

​
Sync And Session Problems

Run rmux env sync from the bound local directory. rmux new performs the initial sync, but later local changes are not mirrored until you sync again.
Only main uses the shared /workspace root. For git repos, non-main sessions use separate remote worktrees. For non-git directories, RMUX creates copied folders instead.
Capture the output of rmux configure --show, rmux env status, the relevant aws-check or gcp-check result, and the exact command that failed. That gives enough context to separate config issues from runtime bugs quickly.
Last modified on March 20, 2026