Skip to main content

​
Quick Start

This guide gets you from a local project directory to a running remote session. If you are running from source in this repository, use ./dist/rmux in place of rmux.

​
1. Install Or Build

Install the published binary: 
curl -fsSL https://<your-public-dist-host>/install.sh | bash
Or build from source: 
bun install
bun run build
If you are testing AWS or managed attach flows from a source checkout, stage the bundled Session Manager plugin once: 
bun run stage:session-manager-plugin

​
2. Configure A Backend

Interactive setup writes ./rmux.conf in the current directory: 
cd /path/to/project
rmux configure
You can also configure explicitly.

​
AWS BYOC

rmux configure --backend aws --from-aws-cli
rmux aws-check
Use explicit AWS flags if you need to pin networking, auth mode, or the workspace bucket: 
rmux configure \
  --backend aws \
  --aws-region us-east-1 \
  --aws-auth-mode aws-cli \
  --profile default \
  --vpc-id vpc-123456

​
GCP BYOC

rmux configure \
  --backend gcp \
  --gcp-project-id YOUR_PROJECT \
  --gcp-zone us-central1-a

rmux gcp-check
gcp-check is read-only. It validates the active gcloud identity, project access, zone reachability, network configuration, and default Compute Engine service-account resolution.

​
Managed Cloud

rmux configure \
  --backend managed \
  --api-base-url https://rmux.example.com \
  --api-key <issued-key> \
  --managed-region us-east-1 \
  --managed-subnet-ids subnet-a,subnet-b \
  --managed-security-group-ids sg-123 \
  --managed-workspace-bucket rmux-managed-workspaces
For local development from this repository, run the control plane locally first: 
bun run dev:control-plane
Then point rmux configure at http://localhost:4000 and use the seeded development key rmux_dev_key. See the backend guides for the full setup surface:
  1. AWS BYOC Guide
  2. GCP BYOC Guide
  3. Managed Cloud Guide

​
3. Create The Environment

rmux new
rmux new creates the environment, syncs the current directory, and attaches to the default main session. Use --no-attach if you want to provision and sync without immediately connecting: 
rmux new --no-attach

​
4. Work With Sessions

List sessions: 
rmux session ls
Create a named session: 
rmux session new -s agent-a
Send a command without attaching: 
rmux session run -t agent-a bun install
Attach later: 
rmux session attach -t agent-a
Tail logs: 
rmux session logs -t agent-a --follow

​
5. Check Or Update The Environment

Show detailed status: 
rmux env status
Sync the current directory again: 
rmux env sync
Show usage across the current backend: 
rmux usage

​
6. Stop Or Remove It

Stop compute but keep the workspace: 
rmux env down
Destroy the environment and clear the local binding: 
rmux env destroy
rmux env down <name-or-id> and rmux env down --all are also available when you need to stop a different environment visible to the current backend. Next steps:
  1. Configuration
  2. Sessions And Environments
  3. AWS BYOC Guide
  4. GCP BYOC Guide
  5. Managed Cloud Guide
Last modified on March 19, 2026