#Base
Base is your always-on cmux cloud workspace. It is the default cloud VM cmux opens for a signed-in account: persistent, resumable, and meant for coding agents, shells, and work you want to reach from any cmux client.
Preview naming. Some CLI output and lower-level menus still say Cloud VM while the product name moves to Base.
#What Base is
Base is the home workspace for cloud work in cmux. Opening Base is deterministic: cmux finds the right persistent VM for your current account scope, resumes it if needed, repairs the terminal endpoint if it can, and opens a terminal into it.
- Persistent: files, installed tools, shell history, and agent state stay on the VM until you explicitly reset Base.
- Stable identity: the same account scope opens the same Base VM every time.
- Reachable from clients: Mac and iOS attach through cmux auth, so the Mac that created the workspace does not need to stay online.
#Ownership
Base is scoped by the Stack account context you are using in cmux.
| Owner | Scope |
|---|
| Personal Base | One persistent VM owned by your Stack user. Only your signed-in clients can attach unless you share access through a product feature. |
| Team Base | One persistent VM owned by a Stack team. Access follows team membership and team policy, separate from each member's personal Base. |
Switching Stack accounts or teams changes which Base opens. A personal Base and a team Base are different VMs even if you use them from the same Mac.
#Open, reset, create, fork
The main button should be Open Base. It is idempotent and safe to press repeatedly.
- Open Base: create the scoped Base VM only if it does not exist, otherwise resume and attach to the existing one.
- Reset Base: create a new Base generation for the same account scope. The previous generation is retained so accidental resets are recoverable.
- Create VM: make an additional, separate cloud VM for explicit extra machines.
- Fork VM: copy the current VM into a new branch of work.
# Current preview CLI
cmux vm base open
cmux vm base reset
cmux vm ls
cmux vm status <id>
The current preview CLI exposes this through vm commands. The product model is Base for the default persistent workspace, and VM for explicit extra machines and low-level operations.
#Sessions and reconnects
Each terminal pane should have its own remote PTY session. Splitting or opening a new tab creates a new session. Restoring cmux reattaches each pane to its session when possible.
- Scrollback belongs to the pane in cmux and should survive app relaunch.
- Reconnects should be quiet in the terminal. cmux should show state in the UI instead of appending retry loops to scrollback.
- If the terminal endpoint is stale, cmux attempts an in-place repair before asking you to reset anything.
#iOS access
Base runs independently of a Mac process. The iOS app can list your Base workspaces and attach through the cloud control plane as long as you are signed in. This lets you check agents and terminals while your MacBook is asleep or offline.
#Notifications
A Base VM can have many attached clients. Agent notifications should fan out through the cloud event path to every signed-in client with access, including Mac and iOS.
#Security model
- Authentication uses your cmux account. A client must be signed in before it can list or attach to Base.
- Terminal attach endpoints should be short-lived and scoped to the authenticated account, device, VM, and session.
- Provider credentials and VM bootstrap secrets stay server-side. Clients receive only the attach endpoint or signed operation they need.
- Team Base access must be checked server-side on every list, open, attach, fork, checkpoint, and reset operation.
#Recovery
Base is designed to prefer repair over replacement because its identity and filesystem are part of the user promise.
- Retry: ask cmux to resume and reattach to the same Base VM.
- Reset: explicitly create a new Base generation. cmux keeps the old generation retained; permanent deletion should be a separate confirmation step.
- Feedback: include the VM id, elapsed time, and last non-secret error so support can tell whether the failure is auth, service readiness, terminal endpoint, or local client state.