Workspaces

What Is a Workspace?

A workspace belongs to a project and represents a single stream of work. For Git projects it is typically backed by a worktree. Each workspace holds its own copies of process, status check, browser session, and port definition settings.

Creating a Workspace

Create a workspace from the sidebar using the add button on a project. For Git projects, this is one click: Muxy creates the workspace immediately with sensible defaults.

• • Workspace title + Branch — both start from Muxy's suggested workspace name.
• • Target branch — defaults from project default branch, then `main`/`master` fallback.
• • Directory name — auto-generated for the worktree and editable later.
• • Tooltip — optional workspace context you can set after creation.

Settings Overrides

Workspace settings (processes, status checks, browser sessions, port definitions) start as copies of the project templates. After creation, each workspace maintains independent overrides that do not affect the project templates.

• • The project/workspace + opens the New Workspace form.
• • cmd+n opens the New Workspace form for the currently selected project/workspace.
• • When the New Workspace form is open, cmd+n creates a workspace immediately with generated defaults.
• • Update title by double-clicking the top header name, and update branch/tooltip by double-clicking inline labels; press Escape or click outside the inline controls to cancel edits. You can also use mx workspace update.
• • Renaming a workspace branch from the inline editor renames the underlying git worktree branch.
• • Add, remove, or rename port definitions per workspace.
• • Edit process commands; changes restart the process immediately if the workspace is running.
• • Add browser sessions that open immediately when the workspace is running.

Ports Per Workspace

Each workspace receives reserved ports based on named port definitions so multiple workspaces can run in parallel without port conflicts.

• • Port definitions are configured at the project level (e.g. `FRONTEND_PORT`, `API_PORT`) and inherited by workspaces.
• • Each definition is exposed as an environment variable to every workspace process.
• • Ports are reserved so they cannot be claimed by other processes between allocation and use.
• • Reserved ports are released when a workspace is archived.

Workspace: bugfix/login-timeout
FRONTEND_PORT=21001
API_PORT=21002

Environment Variables

Every workspace process receives the following environment variables at launch.

• • Named port env vars from the workspace's port definitions (e.g. `FRONTEND_PORT=20001`, `API_PORT=20002`).
• • `MUXY_PROJECT_DIR` — the project directory.
• • `MUXY_WORKSPACE_DIR` — the workspace directory.

These variables are available in setup scripts, stop scripts, process commands, and status check commands.

Switching Between Workspaces

Switching workspaces changes active context in one action: windows, process list, browser session targets, and status output all follow the selected workspace.

1. 1. Select another running workspace from the sidebar or with next/previous shortcuts.
2. 2. Focus it to bring the first tracked window forward (`cmd+shift+return`).
3. 3. Continue cycling within that workspace using next/previous or `cmd+1..9`.