Skip to main content
RMUX was built for one thing: letting you run AI coding agents without worrying about your laptop sleeping, your Wi-Fi dropping, or your battery dying.
This guide assumes you have already run rmux new for a project. If not, start with Quick Start.

​
Claude Code

​
Start a persistent Claude Code session

cd your-project
rmux new
Once attached, start Claude Code inside the remote terminal: 
claude
Claude Code is now running on the remote VM. It will keep working even if you disconnect.

​
Detach and let it work

Press Ctrl+B, then D to detach from the tmux session. Or just close your laptop entirely — the VM does not care.

​
Check on it later

cd your-project
rmux workspace attach
You see the full scrollback. Claude is still working (or finished and waiting for input).

​
Run multiple Claude Code instances

rmux workspace new feature-auth
rmux workspace new feature-api
rmux workspace new refactor-db
Attach to any workspace and start a separate Claude Code session in each: 
rmux workspace attach feature-auth
# Inside: claude
Each workspace gets its own git worktree, so multiple Claude instances can edit the same repo without creating merge conflicts.

​
Codex

rmux new
# Inside the remote terminal:
codex
Detach and reconnect the same way. Codex keeps running in the background.

​
Any CLI Agent

RMUX workspaces are normal tmux sessions on a remote VM. Any CLI tool that runs in a terminal works — there is nothing agent-specific about the runtime. If it runs in a shell, it runs in RMUX.

​
Parallel Agents

The most powerful RMUX pattern is running multiple agents on the same project at the same time, each in its own isolated workspace.

​
Set up parallel workspaces

rmux workspace new agent-backend
rmux workspace new agent-frontend
rmux workspace new agent-tests

​
Start an agent in each

rmux workspace attach agent-backend
# Start Claude Code, give it a backend task, then detach (Ctrl+B, D)

rmux workspace attach agent-frontend
# Start another Claude Code instance for frontend work, then detach

rmux workspace attach agent-tests
# Start Codex for test generation, then detach

​
Check progress without interrupting

View workspace logs without attaching: 
rmux workspace logs agent-backend --follow
List all active workspaces: 
rmux workspace ls
Check the environment status: 
rmux env status

​
How isolation works

  • The main workspace uses /workspace (the shared project root).
  • Named workspaces use git worktrees when the project is a git repo — each workspace gets its own working tree branched from the current state.
  • For non-git directories, RMUX creates copied folders instead.
This means agents in different workspaces can commit to different branches without stepping on each other.

​
Moving Changes Back

After agents finish their work, use git to review, push, fetch, and merge their branches from the main workspace or from your local checkout.

​
Secrets And API Keys

Agents often need API keys (for LLM providers, for example). RMUX can inject secrets into the remote environment: 
rmux env secrets set ANTHROPIC_API_KEY sk-ant-...
rmux env secrets set OPENAI_API_KEY sk-...
rmux env secrets ls
Secrets are available as environment variables inside all workspaces.

​
Overnight And Long-Running Tasks

RMUX is ideal for tasks that take hours:
  1. Start the task — attach, give the agent a large refactoring job or full test suite, then detach.
  2. Go to sleep — the VM keeps running.
  3. Check in the morning — rmux workspace attach to see results. The full terminal scrollback shows everything the agent did.
Use rmux env down when you are done to stop compute costs. The workspace state is preserved — rmux new in the same directory will resume where you left off.

​
Tips

  • Use named workspaces for agents — keep main clean for manual work and use rmux workspace new agent-name for each agent task.
  • Detach, do not kill — Ctrl+B, D detaches without stopping anything. exit or Ctrl+D inside the shell ends the session.
  • Check logs remotely — rmux workspace logs <name> --follow lets you tail output without attaching.
  • Expose ports — if an agent starts a dev server, use rmux env expose 3000 to get a public URL.

Day-To-Day Workflows

The full set of workspace commands for daily use.

Environment Lifecycle

Create, stop, resume, and destroy environments.

Workspace Model

How main, named workspaces, and tmux sessions fit together.

Configuration

Backend settings, config files, and environment variables.
Last modified on March 24, 2026