Skip to main content

​
Managed Cloud Guide

Use backend=managed when you want rmux to connect to an RMUX control plane instead of provisioning directly from the CLI into your own AWS account.

​
What This Backend Does

With the managed backend, rmux:
  1. authenticates with RMUX_API_KEY
  2. talks to the configured HTTP control plane
  3. creates and manages AWS devbox environments through that service
  4. uses the same host-tmux workspace model as the AWS backend
  5. can mint short-lived AWS attach credentials when managed.attachRoleArn is configured

​
Prerequisites

You need:
  1. an API key for the target control plane
  2. a control plane base URL
  3. managed AWS settings for the region, networking, and workspace bucket used by that deployment

​
Configure The Backend

Example: 
cd /path/to/project
rmux configure \
  --backend managed \
  --api-key rmux_dev_key \
  --api-base-url http://localhost:4000 \
  --managed-region us-east-1 \
  --managed-subnet-ids subnet-a,subnet-b \
  --managed-security-group-ids sg-123 \
  --managed-workspace-bucket my-managed-bucket
If backend=managed, an API key is required. In practice the managed AWS deployment also needs subnet IDs, security-group IDs, and a workspace bucket before environments can be created.

​
Local Development Control Plane

For local development from this repository: 
bun run dev:control-plane
Then configure rmux to point at http://localhost:4000. The development service seeds a local key by default: 
rmux_dev_key
When DATABASE_URL is set, that seeded key is disabled by default unless RMUX_SEED_DEV_API_KEY=1.

​
Hosted Control Plane

For a hosted deployment, point rmux at the deployed API and use the issued API key for that environment: 
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 my-managed-bucket
If your deployment mints short-lived AWS credentials for attach, you can also set: 
rmux configure --backend managed --managed-attach-role-arn arn:aws:iam::123456789012:role/rmux-attach
Hosted operators should also set DATABASE_URL or RMUX_DATABASE_URL, and should set RMUX_SECRET_ENCRYPTION_KEY if they want stored environment secrets encrypted at rest.

​
Create And Use The Environment

rmux new
rmux session ls
rmux session attach
rmux session new -s agent-a
rmux session run -t agent-a bun install

​
Attach And Sync Model

Managed environments currently provision AWS devboxes behind the control plane.
  1. attach uses AWS SSM Session Manager
  2. sync stages archives through the deployment-managed workspace bucket
  3. the remote project root is still /workspace
  4. session behavior still uses host tmux, main, and named sessions with git worktrees or copied folders

​
Usage And Admin Commands

Show current backend usage: 
rmux usage
Admin commands are only relevant if your API key has admin permissions: 
rmux admin keys ls
rmux admin keys create --label "Customer A" --plan starter
rmux admin subscription --key-id <key-id> --status active
Last modified on March 19, 2026