Skip to main content

​
AWS BYOC Guide

Use backend=aws when you want rmux to talk directly to your own AWS account.

​
What This Backend Does

With the AWS backend, rmux:
  1. validates your AWS identity and resolved network/storage settings
  2. creates one EC2 devbox per environment
  3. syncs your project into /workspace
  4. uses AWS SSM Session Manager for attach flows
  5. stages sync archives, secrets, and workspace data through an S3 workspace bucket
There is no RMUX control plane requirement for this mode.

​
Prerequisites

You should have:
  1. an AWS account you control
  2. AWS credentials available through the AWS CLI, environment variables, or direct access keys
  3. the AWS Session Manager plugin available for attach flows
  4. a default VPC in the target region, or explicit subnet and security group settings
Published RMUX release bundles include the Session Manager plugin sidecar. If you are running from a source checkout, stage it once with: 
bun run stage:session-manager-plugin

​
Configure From AWS CLI

The shortest setup path is: 
cd /path/to/project
rmux configure --backend aws --from-aws-cli
That seeds region and profile defaults from your local AWS CLI configuration. You can also be explicit: 
rmux configure \
  --backend aws \
  --aws-region us-east-1 \
  --aws-auth-mode aws-cli \
  --profile default
Common optional flags: 
rmux configure \
  --backend aws \
  --vpc-id vpc-123456 \
  --subnet-ids subnet-a,subnet-b \
  --security-group-ids sg-123 \
  --instance-type t3.large \
  --workspace-bucket my-rmux-bucket

​
Validate AWS Setup

Run: 
rmux aws-check
This prints the resolved region, credential source, runtime adapter, and validated AWS resources. On the BYOC default path, rmux can auto-discover or create shared defaults such as:
  1. a workspace security group
  2. a workspace bucket
  3. missing default subnet or VPC inputs needed for planning
If you do not want the default VPC path, pass --vpc-id or explicit subnet IDs and security group IDs. The AWS runtime requires a workspace bucket. If you do not set one explicitly, the BYOC auto-provision flow can resolve it for you during preflight or create.

​
Create And Use The Environment

rmux new
rmux session ls
rmux session new -s agent-a
rmux session attach -t agent-a
Run commands remotely without attaching: 
rmux session run -t agent-a bun install
rmux session run -t agent-a bun test

​
Attach And Sync Model

Attach uses AWS SSM Session Manager rather than inbound SSH. rmux env sync uploads an archive to the resolved S3 workspace bucket, then extracts it into /workspace on the devbox. That same bucket is also used for parts of the secrets and lifecycle flow.

​
Authentication Modes

The AWS backend supports:
  1. aws-cli
  2. env
  3. access-key
Examples: 
rmux configure --backend aws --aws-auth-mode env
rmux configure --backend aws --aws-auth-mode access-key --access-key-id ... --secret-access-key ...

​
Useful Commands

rmux aws-check
rmux env status
rmux env sync
rmux env down
rmux env destroy
rmux usage
Last modified on March 19, 2026