Skip to main content

​
Sessions And Environments

rmux is built around two things:
  1. environments for a project directory
  2. sessions inside that environment

​
Environment Lifecycle

Create an environment for the current directory: 
rmux new
You can also use the namespaced form: 
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 session 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 environment entirely: 
rmux env destroy
rmux env down <name-or-id> and rmux env down --all are also available when you want to stop other visible environments. If a destroy hits partial cleanup failures, rmux env status shows the cleanup state and rmux env destroy can be retried.

​
Default Session

When you create a new environment, rmux creates a default session named main. Attach to it: 
rmux session attach
Run a command inside it: 
rmux session run bun test

​
Named Sessions

Create a new session: 
rmux session new -s agent-a
Attach to a named session: 
rmux session attach -t agent-a
List all sessions: 
rmux session ls
Kill a named session: 
rmux session kill -t agent-a
If the target session workspace has uncommitted changes, rmux session kill may ask for confirmation. Use --force to skip that prompt.

​
Workspace Isolation

Session workspaces are isolated by session name:
  1. main uses the shared /workspace root
  2. non-main sessions use git worktrees when the project is a git repo
  3. non-main sessions use copied folders when the project is not a git repo
You can inspect the workspace type and path with: 
rmux session ls
rmux env status

​
Logs

Show logs for the default session: 
rmux session logs
Follow logs for a named session: 
rmux session logs -t agent-a --follow

​
Secrets And Ports

Set a secret on the current environment: 
rmux env secrets set OPENAI_API_KEY your-value
List secrets: 
rmux env secrets ls
Remove a secret: 
rmux env secrets rm OPENAI_API_KEY
List exposed ports: 
rmux env ports
Expose a port: 
rmux env expose 3000
rmux env expose returns the generated URL immediately. rmux env ports lists all current exposed ports and URLs.

​
Usage And Targeting

Show backend-wide usage and visible environments: 
rmux usage
Stop another environment by name or ID: 
rmux env down my-environment
rmux env down env_123
Stop every visible environment for the current backend: 
rmux env down --all

​
Backend Differences

BackendAttach transportSync behaviorNotes
awsAWS SSM Session Managerenv sync stages an archive through S3 into the devbox.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 copies the current directory directly with gcloud compute scp.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, sessions run in host tmux, and non-main sessions use git worktrees for git repos and copied directories for non-git projects.
Last modified on March 19, 2026