Skip to main content

​
Overview

Once an environment exists, most day-to-day RMUX usage comes down to a small set of commands: 
rmux workspace attach
rmux workspace ls
rmux env status
rmux env sync
The current directory is the selector. Re-enter the same local directory before using workspace or env commands so RMUX can load the binding from .rmux/state.json.

​
Common Workflows

1

Provision now and attach later

rmux new --no-attach
rmux workspace run bun install
rmux workspace attach
This is useful when you want the environment ready before you connect interactively.
2

Run a long-lived server in its own workspace

rmux workspace new server
rmux workspace run -w server bun run dev
rmux env expose 3000
rmux workspace logs server --follow
Keep app servers, preview processes, or watchers in named workspaces so your main shell stays clean.
3

Create isolated parallel workspaces

rmux workspace new agent-a
rmux workspace new agent-b
rmux workspace ls
main uses /workspace. For git repos, non-main workspaces use dedicated remote worktrees. For non-git directories, RMUX creates copied folders instead.
4

Reconnect from another terminal or later in the day

cd /path/to/project
rmux workspace attach
rmux workspace attach server
rmux env status
The local binding lets RMUX find the environment again, and tmux keeps the remote workspace alive between terminal disconnects.
5

Pause compute without losing the workspace

rmux env down
rmux workspace attach
env down stops compute but preserves remote state. Use rmux env destroy only when you want to remove the environment entirely.

​
Inspect The Environment

CommandUse it when
rmux env statusYou want provider, runtime, transport, sync time, and workspace details.
rmux workspace lsYou want the current workspace table, workspace path, log path, and last command.
rmux env listYou want the environment table for the current backend, including environment IDs.
rmux usageYou want backend-wide visibility into environments visible to the current identity.
rmux env list and rmux usage both print environment IDs in the first column. Use those IDs when you want to target a specific environment from another directory or when multiple environments share the same project name.

​
Logs, Secrets, And Ports

​
Logs

rmux workspace logs
rmux workspace logs server --follow

​
Secrets

rmux env secrets set OPENAI_API_KEY your-value
rmux env secrets ls
rmux env secrets rm OPENAI_API_KEY

​
Ports

rmux env expose 3000
rmux env ports
rmux env expose returns the generated URL immediately. rmux env ports lists all current exposed ports and URLs.

​
Lifecycle Reference

Create an environment for the current directory: 
rmux new
rmux env new
Check status: 
rmux env status
env status shows the current environment record plus runtime details such as provider, region or zone, transport, deployment state, last sync time, exposed public IP details, and the workspace table for that environment. Sync the local directory into the bound environment: 
rmux env sync
Stop compute but keep remote state: 
rmux env down
Destroy the current environment entirely: 
rmux env destroy
Target a different visible environment by name or ID: 
rmux env list
rmux env down env_123
rmux env destroy my-project
rmux env down <name-or-id>, rmux env down --all, rmux env destroy <name-or-id>, and rmux env destroy --all are also available when you want to manage other visible environments. If a destroy hits partial cleanup failures, rmux env status shows the cleanup state and rmux env destroy can be retried.

​
Workspace Behavior

Each environment starts with a default workspace named main. 
rmux workspace attach
rmux workspace run bun test
Create, attach to, and remove named workspaces: 
rmux workspace new agent-a
rmux workspace attach agent-a
rmux workspace cursor agent-a
rmux workspace rm agent-a
If the target workspace has uncommitted changes, rmux workspace rm may ask for confirmation. Use --force to skip that prompt.

​
Editor Access

Open a named workspace in VS Code or Cursor: 
rmux workspace editor main --vscode
rmux workspace editor agent-a --cursor
rmux workspace code main
rmux workspace cursor agent-a
rmux workspace editor <workspace> --cursor|--vscode ensures the target workspace exists, resolves its workspace path, prepares an RMUX-managed SSH host entry under ~/.ssh/rmux/config, and launches the editor against that host alias. rmux workspace cursor <workspace> and rmux workspace code <workspace> are shorthand aliases for Cursor and VS Code. It opens the resolved workspace path for that workspace. It does not attach to the workspace’s tmux terminal. Use rmux workspace attach <workspace> when you want the terminal session itself. This editor SSH flow currently supports backend=gcp and backend=aws. For backend=gcp, RMUX derives the SSH host details from gcloud compute config-ssh and stores an RMUX-managed alias in ~/.ssh/rmux/config. For backend=aws, RMUX installs or reuses an RMUX-managed SSH key under ~/.ssh/rmux/, enables SSH access on the devbox through SSM, and tunnels the actual SSH connection through AWS Session Manager with AWS-StartSSHSession. The environment does not need an inbound port 22 rule for this flow. For backend=aws, authentication behavior depends on the configured auth mode:
  1. aws-cli works for both rmux workspace editor and standalone ssh rmux-... through the configured AWS profile
  2. env and access-key work with rmux workspace editor, because RMUX injects the resolved AWS credentials into the launched editor process
  3. env and access-key standalone ssh rmux-... still depend on ambient AWS credentials in your current shell environment
backend=managed environments still use SSM-only attach and do not support rmux workspace editor yet.

​
Backend Differences

BackendAttach transportSync behaviorNotes
awsAWS SSM Session Managerenv sync pushes a staged snapshot with rsync over a Session Manager SSH tunnel.BYOC AWS can auto-discover or create shared defaults such as the workspace bucket and security group during preflight and create.
gcpgcloud compute sshenv sync pushes a staged snapshot with rsync over gcloud compute ssh.The current GCP path does not use a workspace bucket, and the preflight check is read-only.
managedAWS SSM Session Manager through the control planeenv sync stages an archive through deployment-managed S3.If managed.attachRoleArn is configured, attach can use short-lived AWS credentials instead of permanent user AWS credentials.
Across all backends, the remote workspace root is /workspace, each workspace has a primary host tmux session, and named workspaces use git worktrees for git repos and copied directories for non-git projects.
Last modified on March 20, 2026