# Feature Request: Launch Workspaces Inside Containers via Bash / SSH

[Meme-code]

Summary

It would be great if cmux could natively launch workspace panes inside containers (Docker, Podman, or over SSH), rather than only on the local machine. This would let developers spin up isolated, reproducible environments per-project directly from cmux — no extra tooling or manual docker exec / ssh commands needed.

Motivation

Many development workflows already depend on containers or remote machines:

• Dev containers — VS Code's devcontainer spec has normalized the idea of "open a project → land inside a container." cmux could offer the same experience but terminal-native.
• Polyglot teams — Different projects need different runtimes, system libraries, or OS-level dependencies. Containers keep the host clean.
• AI coding agents — Tools like Claude Code, Codex, and others often benefit from sandboxed environments where they can install packages and run code freely without affecting the host.
• Remote development — SSH into cloud VMs, GPU boxes, or CI runners is a daily workflow. Having cmux manage those sessions as first-class workspaces (with its notification system, split panes, and browser) would be a huge improvement over raw SSH.

Proposed Behavior

1. Workspace-level container config

Allow a workspace to declare a container or SSH target. Something like:

// .cmux/workspace.json  (or however cmux stores workspace config)
{
  "name": "my-project",
  "backend": {
    "type": "container",          // "local" | "container" | "ssh"
    "image": "node:20-bookworm",  // Docker/Podman image
    "mounts": [".:/workspace"],
    "ports": ["3000:3000"],
    "shell": "/bin/bash"
  }
}

For SSH:

{
  "name": "gpu-box",
  "backend": {
    "type": "ssh",
    "host": "dev@192.168.1.50",
    "identity": "~/.ssh/id_ed25519",
    "shell": "/bin/zsh"
  }
}

2. Lifecycle management

• On workspace open — cmux starts (or connects to) the container/SSH session automatically.
• On new pane/split — New panes exec into the same running container or SSH session, so all panes share the same environment.
• On workspace close — Optionally stop/remove the container (configurable: keep-alive vs. ephemeral).

3. Runtime flexibility

Support at least:

• Docker — Most common, widest ecosystem.
• Podman — Rootless, daemonless alternative gaining traction.
• SSH — For remote machines, cloud VMs, or anything not on localhost.

Detection could be automatic (prefer Podman if available, fall back to Docker), or user-configured.

4. CLI / Socket API integration

Extend the existing cmux CLI and socket API so scripts and agents can programmatically:

# Create a workspace backed by a container
cmux workspace create --name my-project --image python:3.12 --mount .:/workspace

# Attach a new pane to an existing container workspace
cmux pane split --workspace my-project --direction horizontal

# SSH workspace
cmux workspace create --name remote-gpu --ssh dev@gpu-box.local

How This Fits cmux's Design

cmux already has a strong workspace model (tabs, splits, metadata sidebar) and a scriptable API. Containers and SSH sessions are a natural extension — they're just a different "backend" for where the shell runs. The existing notification system, port display, and browser integration would all remain useful (arguably more useful when the workspace is a container with exposed ports).

Prior Art / References

• VS Code Dev Containers — workspace-level container config
• Warp Drive — cloud-based terminal sessions
• Zellij — terminal multiplexer with session management
• devpod — open-source dev environments backed by any provider

Open Questions

1. Config format — Should this live in a .cmux/ directory per project, a global config, or both?
2. Devcontainer spec compatibility — Worth supporting the existing devcontainer.json spec for interoperability?
3. Reconnection — If a container crashes or SSH drops, should cmux auto-reconnect?
4. Composability — Should a workspace be able to mix local and container panes (e.g., one pane local, one pane in a container)?

Would love to hear thoughts from the maintainers and community on this. Happy to contribute if there's interest!