Skip to main content

​
Introduction

rmux is a directory-first CLI for persistent remote sessions. From inside a project folder, you configure a backend, create an environment, and attach to remote tmux sessions that keep running even when your local terminal disconnects.

​
Core Concepts

​
Project directory

The current local directory is the main selector in the CLI. rmux stores a local binding in .rmux/state.json so it can reconnect that directory to the right remote environment later.

​
Environment

An environment is the remote compute and persistent workspace for one project directory. Today both supported backends use the same runtime shape:
  1. one EC2 devbox per environment
  2. /workspace as the remote project root
  3. tmux sessions running directly on the host
  4. AWS SSM Session Manager for attach flows

​
Session

Each environment starts with a default main session. You can create additional named sessions for parallel work: 
rmux session new -s agent-a
rmux session new -s server
For git repos, non-main sessions use dedicated git worktrees. For non-git directories, they use copied folders.

​
Backends

rmux currently supports two ways to run:
BackendWhat it meansBest fit
awsThe CLI talks directly to your AWS account.Bring-your-own-cloud setups.
managedThe CLI talks to an RMUX control plane with an API key.Hosted or centrally managed deployments.

​
Typical Flow

  1. cd into a project.
  2. Run rmux configure.
  3. Run rmux new.
  4. Create or attach to sessions with rmux session ....
  5. Stop or destroy the environment when you are done.
See Quick Start for the shortest end-to-end setup.
Last modified on March 19, 2026