> ## 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.

# Troubleshooting

> Fix the most common RemoteMux setup, binding, attach, and sync problems.

## Start Here

When RemoteMux behaves unexpectedly, inspect the resolved config and current binding first:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
rmux configure --show
rmux auth status
rmux env status
rmux workspace ls
```

Then run the backend-specific check if available:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
rmux aws-check    # AWS only
rmux gcp-check    # GCP only
```

`backend=e2b` and `backend=managed` do not have dedicated preflight commands -- use `rmux configure --show`.

<Info>
  Many problems come from running commands outside the directory that created the environment binding. Make sure you are in the right project directory.
</Info>

## Binding And Directory

<Accordion title="No binding found for this directory">
  You are in the wrong directory or have not created an environment for this project. Re-enter the directory that ran `rmux env new`, or create a new environment.
</Accordion>

<Accordion title="This directory is already bound">
  Use `rmux workspace attach` to reconnect, `rmux env status` to inspect, or `rmux env destroy` if you want to replace the environment.
</Accordion>

## AWS

<Accordion title="rmux aws-check fails before environment creation">
  Confirm `backend=aws` is selected, AWS credentials are valid, and the region is correct. Run `rmux configure --show` to verify.
</Accordion>

<Accordion title="Attach fails on AWS backend">
  Attach uses the AWS Session Manager plugin, bundled in RemoteMux releases. If you have the plugin elsewhere, set `RMUX_SESSION_MANAGER_PLUGIN_PATH`.
</Accordion>

<Accordion title="aws.workspaceBucket must be configured">
  RemoteMux needs a workspace bucket for staged sync. On the BYOC default path, rerun `rmux aws-check` or `rmux env new` to let RemoteMux auto-resolve it. Otherwise, set `--workspace-bucket` or `aws.workspaceBucket` explicitly.
</Accordion>

## GCP

<Accordion title="compute.googleapis.com is not enabled">
  Enable the Compute Engine API in the target project, then rerun `rmux gcp-check`.
</Accordion>

<Accordion title="rmux gcp-check fails even though I am logged in">
  Verify the resolved auth mode, project, and zone match the RemoteMux config. Compare `rmux configure --show` with `gcloud auth list` when `gcp.authMode=gcloud-cli`.

  If you use `gcp.authMode=credentials-file`, confirm `gcp.credentialsFile` or `RMUX_GCP_CREDENTIALS_FILE` points to a readable credential file, and re-check any `gcp.impersonateServiceAccount` setting.
</Accordion>

## Managed

<Accordion title="Managed commands fail against the control plane">
  Check `apiBaseUrl` and your auth state with `rmux auth status`. Hosted deployments require a valid OAuth session or scoped service token. If commands fail in an interactive terminal, `rmux` now offers an auth picker automatically; otherwise switch explicitly with `rmux auth use oauth` or `rmux auth use api-key --token <api-key>`.

  If the active source is `env`, unset `RMUX_API_KEY`. If the active source is `none`, select a stored auth method with `rmux auth use ...`.
</Accordion>

<Accordion title="Workspace bootstrap fails or times out on managed">
  Contact your RemoteMux operator -- the control plane may be using a sandbox template that lacks the required dev tools.
</Accordion>

## E2B

<Accordion title="e2b.apiKey must be configured">
  Confirm `backend=e2b` is selected and the API key is present. `rmux configure --show` should show the backend, template, timeout, and a masked key.
</Accordion>

<Accordion title="E2B bootstrap requires apt-get or dnf">
  RemoteMux installs `tmux`, `git`, and `python3` on first use. Choose a template with `apt-get` or `dnf` available.
</Accordion>

## Sync And Workspaces

<Accordion title="Remote code looks stale">
  `rmux workspace new main` only seeds the project once. Use `rmux env sync` or git to move later changes.
</Accordion>

<Accordion title="Claude works locally but not in the workspace">
  Run `rmux claude status` from the project directory. If local auth exists but remote auth is missing, run `rmux claude sync`. If local auth is missing, run `rmux claude login`.
</Accordion>

<Accordion title="Named workspaces do not share the same files">
  Only `main` uses `/workspace`. Named workspaces use separate git worktrees (or copied folders for non-git projects).
</Accordion>

## Before You File A Bug

Capture these and include them in your report at [github.com/autocomputer-ai/rmux/issues](https://github.com/autocomputer-ai/rmux/issues):

* `rmux configure --show`
* `rmux auth status`
* `rmux env status`
* `rmux workspace ls`
* The relevant `rmux aws-check` or `rmux gcp-check` output
* The exact command and error message