From 16dc83616a66de7b00dbbe8bc0900c718119ebf7 Mon Sep 17 00:00:00 2001
From: Michael Panchenko <35432522+MischaPanch@users.noreply.github.com>
Date: Wed, 3 Jun 2026 15:48:25 +0200
Subject: [PATCH] :sparkles: Add the ability to launch parallel devenv
 instances (#9906)

* :whale: Split devenv compose for parallel workspaces

Move shared services into an infra compose file and keep the main devenv container plus Valkey in a separate compose file driven by defaults.env. Parameterize host-side ports, container names, source path, and runtime env while keeping container-internal ports fixed for same-origin proxying.

Make tmux startup idempotent, add attach-devenv for the live instance, move shared MinIO user setup to infra startup, and let exporter scripts load backend _env.local overrides.

Co-authored-by: Codex <codex@openai.com>

* :whale: Run parallel devenv instances against shared infra

Add support for running N parallel devenv instances under separate compose
projects sharing Postgres, MinIO, mailer, and LDAP. Each instance has its
own main container, Valkey, source checkout, tmux session, and host port
range offset by 10000 (3449 -> 13449 -> 23449, etc.).

./manage.sh run-devenv-agentic --n-instances N reconciles the running set
to exactly {ws0..ws(N-1)}: missing instances are created (workspace sync
from the live repo via git ls-files + per-instance env-file generation
under docker/devenv/instances/ + detached tmux startup), surplus instances
are stopped highest-first via compose down (never -v), already-running
instances are left untouched. ws0 binds the live repo at PWD; ws1+ are
scratch clones under ~/.penpot/penpot_workspaces/.

Backend workers (enable-backend-worker) are gated on PENPOT_BACKEND_WORKER
in backend/scripts/_env; ws1+ overlays disable them so async-task
notifications stay bound to a single Valkey Pub/Sub instance.

Compose helpers wrap docker compose with env -i so per-instance overlay
--env-file actually overrides defaults.env -- without the strip, the shell
env from sourcing defaults.env at startup would shadow the overlay (Compose
gives shell precedence over --env-file).

Other:
- Drop network aliases (- main, - redis); use container_name for
  cross-container DNS so multiple instances on the shared network don't
  fight over the same DNS name.
- Pin volume names via name: (PENPOT_*_VOLUME) so volumes survive project
  renames; ws0 keeps the pre-existing physical names (penpotdev_*).
- Remove cross-project depends_on from main.yml (postgres/minio-setup now
  live in penpotdev-infra); manage.sh ensure-infra-up docker-waits on the
  minio-setup one-shot.
- Strict arg parsing in run-devenv / run-devenv-agentic; --n-instances 0
  rejected.
- Remove unused Host-matched server block from the Caddyfile.

Memory mem:devenv/core and developer docs updated.

Co-authored-by: Codex <codex@openai.com>

* :sparkles: Document and stabilise the parallel-workspace CLI; wire AI agents

Improve parallel-workspaces developer CLI,
and add an opt-in layer that lets four AI
coding agents (Claude Code, opencode, VS Code Copilot, OpenAI Codex CLI)
drive a specific workspace through a single launcher command.

Parallel-workspace semantics
----------------------------

each run-devenv-agentic call brings up one wsN;
--ws N (integer; default 0) targets a specific workspace and auto-starts
ws0 first when N>=1 so the worker invariant holds. --sync is forbidden on
ws0 and re-seeds the workspace from the live repo for ws1+. Stop semantics
mirror the start invariant -- ws0 is the last to stop, shared infra stops
with it, --all walks every instance highest-first. The worker policy
section explains why workers run only on ws0 (Postgres FOR UPDATE
SKIP LOCKED is safe across many workers but the cron dedup primitive is
best-effort, and :telemetry / :audit-log-archive are not idempotent).
Per-instance Valkey Pub/Sub isolation, msgbus topology, and the
"async task notifications miss ws1+ tabs" caveat are stated explicitly.

The mem:prod-infra/core memory captures the same external-services and
task-queue / Pub-Sub topology in agent-readable form, and
mem:backend/core and mem:critical-info now cross-link it so backend work
surfaces the horizontal-scaling constraints from the start.

AI coding agent integration
---------------------------

New top-level .devenv/ directory holds committed templates
(templates/{claude-code,opencode,vscode}.json and templates/codex.toml,
each with \${PENPOT_MCP_PORT} and \${SERENA_MCP_PORT} placeholders) plus
committed shared entries (matching shared/* files for Playwright, the
only workspace-independent server we ship today).

./manage.sh start-coding-agent <claude|opencode|vscode|codex> [--ws N]
launches the chosen client against one workspace. It cd's into the
target's directory (the live repo for ws0; workspace-path "wsN" for ws1+)
and refuses to launch unless (a) the binary is on PATH, (b) the
workspace directory exists for ws1+, and (c) the instance is up
(devenv-main-running) -- the MCP servers only exist while the devenv is
running. The agentic-devenv guide is restructured around this Quick
start path, with a per-client table and a Manual configuration fallback
for clients we don't cover.

Co-Authored-By: Codex <codex@openai.com>
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* :recycle: Scope the shadow devtools to the dev build

---------

Co-authored-by: Codex <codex@openai.com>
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .devenv/README.md                             |  133 ++
 .devenv/scripts/merge-mcp-config.py           |  204 ++++
 .devenv/shared/claude-code.json               |    8 +
 .devenv/shared/codex.toml                     |    8 +
 .devenv/shared/opencode.json                  |    9 +
 .devenv/shared/vscode.json                    |    9 +
 .devenv/templates/claude-code.json            |   12 +
 .devenv/templates/codex.toml                  |   10 +
 .devenv/templates/opencode.json               |   14 +
 .devenv/templates/vscode.json                 |   12 +
 .gitignore                                    |    3 +
 .serena/memories/backend/core.md              |    1 +
 .serena/memories/critical-info.md             |   10 +-
 .serena/memories/devenv/core.md               |   73 ++
 .serena/memories/mcp/core.md                  |    8 +
 .serena/memories/prod-infra/core.md           |   33 +
 backend/scripts/_env                          |   36 +-
 docker/devenv/defaults.env                    |   69 ++
 docker/devenv/docker-compose.infra.yml        |   99 ++
 docker/devenv/docker-compose.main.yml         |  106 ++
 docker/devenv/docker-compose.yaml             |  180 ---
 docker/devenv/files/Caddyfile                 |    4 -
 docker/devenv/files/nginx.conf                |    7 +
 docker/devenv/files/start-tmux.sh             |   75 +-
 .../developer/agentic-devenv.md               |  341 ++++--
 docs/technical-guide/developer/devenv.md      |  150 ++-
 exporter/scripts/run                          |    4 +
 exporter/scripts/wait-and-start.sh            |    4 +
 frontend/shadow-cljs.edn                      |   18 +-
 manage.sh                                     | 1071 ++++++++++++++++-
 30 files changed, 2338 insertions(+), 373 deletions(-)
 create mode 100644 .devenv/README.md
 create mode 100755 .devenv/scripts/merge-mcp-config.py
 create mode 100644 .devenv/shared/claude-code.json
 create mode 100644 .devenv/shared/codex.toml
 create mode 100644 .devenv/shared/opencode.json
 create mode 100644 .devenv/shared/vscode.json
 create mode 100644 .devenv/templates/claude-code.json
 create mode 100644 .devenv/templates/codex.toml
 create mode 100644 .devenv/templates/opencode.json
 create mode 100644 .devenv/templates/vscode.json
 create mode 100644 .serena/memories/devenv/core.md
 create mode 100644 .serena/memories/prod-infra/core.md
 create mode 100644 docker/devenv/defaults.env
 create mode 100644 docker/devenv/docker-compose.infra.yml
 create mode 100644 docker/devenv/docker-compose.main.yml
 delete mode 100644 docker/devenv/docker-compose.yaml

diff --git a/.devenv/README.md b/.devenv/README.md
new file mode 100644
index 0000000000..d56e327dd0
--- /dev/null
+++ b/.devenv/README.md
@@ -0,0 +1,133 @@
+# `.devenv/` — Per-Workspace AI-Client MCP Configs
+
+This directory carries the pieces needed to point an AI coding agent
+(currently Claude Code, opencode, VS Code Copilot, and the OpenAI Codex CLI)
+at the MCP servers running inside the parallel devenv instance the developer
+is currently working in. Every parallel workspace (`ws0`, `ws1`, …) has its
+own copy because the Penpot MCP and Serena MCP host ports are
+workspace-specific.
+
+## Layout
+
+```
+.devenv/
+  README.md
+  scripts/
+    merge-mcp-config.py    # generator helper invoked by manage.sh
+  shared/                  # committed; workspace-independent entries
+    claude-code.json       # Playwright — same for every workspace
+    opencode.json
+    vscode.json
+    codex.toml
+  templates/               # committed; entries with ${...} port placeholders
+    claude-code.json       # Penpot MCP, Serena MCP — port is the only diff
+    opencode.json
+    vscode.json
+    codex.toml
+  mcp/                     # gitignored; written by manage.sh per workspace
+    claude-code.json       # loaded via Claude Code's --mcp-config flag
+    opencode.json          # loaded via OPENCODE_CONFIG env var
+```
+
+One more file is generated outside `.devenv/`, in the directory VS Code itself
+auto-discovers (gitignored):
+
+```
+.vscode/mcp.json           # auto-loaded by GitHub Copilot in VS Code
+```
+
+Codex is the exception: it has no way to load an MCP config from an arbitrary
+path, and its only project-level config file (`.codex/config.toml`) is one a
+developer may already own. So we do **not** write a file for Codex at all —
+`start-coding-agent codex` injects our servers as `-c` command-line overrides
+built fresh from `shared/codex.toml` + `templates/codex.toml` at launch.
+
+* **`shared/`** holds MCP entries that don't depend on the workspace — the
+  browser-driving Playwright server today, plus any other workspace-independent
+  servers we add later. Same content in every workspace, so it's a static
+  checked-in file.
+* **`templates/`** holds the workspace-specific entries (Penpot MCP, Serena
+  MCP) with `${PENPOT_MCP_PORT}` and `${SERENA_MCP_PORT}` placeholders. The
+  placeholders are resolved per-workspace from the port-base constants in
+  `manage.sh`.
+* **`mcp/`** (Claude Code, opencode) is the result of merging `shared/` with
+  the port-substituted `templates/`. `manage.sh` writes these on every
+  `run-devenv-agentic` pass. Gitignored, dedicated paths with no developer
+  content — never edit by hand, your edits will be overwritten on the next
+  reconcile.
+* **`.vscode/mcp.json`** is the same merge, but written to the path VS Code
+  auto-discovers. Because on `ws0` that path *is* the live repo's own file, the
+  reconcile **deep-merges** into it: any servers you added yourself are kept,
+  and only the entries we manage (`penpot`, `serena-devenv`, `playwright`) are
+  (re)written to the current ports. On `ws1+` the file doesn't exist yet, so it
+  is created from scratch.
+* **`scripts/merge-mcp-config.py`** is the generator. Its `json` mode does the
+  JSON deep-merge (with `--merge-into-existing` for the VS Code path); its
+  `codex-args` mode prints the `-c` assignments for Codex. `manage.sh`'s
+  `_merge-mcp-config-json` helper is a thin shim over the former, and
+  `start-coding-agent` calls the latter directly. Run
+  `python3 .devenv/scripts/merge-mcp-config.py --help` for the CLI.
+
+## Launching a coding agent
+
+The easiest path is the wrapper command, which knows the right flags per
+client, `cd`'s into the target workspace, and refuses to launch unless the
+target instance is running and its MCP config has been generated:
+
+```bash
+# Default target is ws0 (the live repo).
+./manage.sh start-coding-agent claude               [...args to forward]
+./manage.sh start-coding-agent opencode             [...args to forward]
+./manage.sh start-coding-agent vscode               [...args to forward to 'code']
+./manage.sh start-coding-agent codex                [...args to forward]
+
+# Target a parallel workspace with --ws N. N is an integer (non-negative);
+# 'main', 'ws1' and similar spellings are rejected.
+./manage.sh start-coding-agent claude --ws 1
+./manage.sh start-coding-agent opencode --ws 2
+```
+
+Equivalents by hand (run from inside the workspace directory):
+
+```bash
+claude --mcp-config .devenv/mcp/claude-code.json
+OPENCODE_CONFIG=.devenv/mcp/opencode.json opencode
+code "$PWD"                  # VS Code auto-discovers .vscode/mcp.json
+# Codex: pass our servers as -c overrides (no config file is written).
+codex $(python3 .devenv/scripts/merge-mcp-config.py --format codex-args \
+          .devenv/shared/codex.toml .devenv/templates/codex.toml \
+          | sed 's/^/-c /')
+```
+
+`start-coding-agent codex` does the `-c` wiring for you (and resolves the
+workspace's ports first). Because our servers arrive as command-line
+overrides, no "trusted project" prompt is involved for them — that prompt only
+gates Codex's own `.codex/config.toml`, which we never write.
+
+## Overriding our entries
+
+Both the auto-discovered configs and the launcher-loaded configs sit *on top
+of* the developer's global config (with varying precedence rules). All four
+clients offer escape hatches for shadowing entries we ship:
+
+* **Claude Code** — `claude mcp add --scope local …` installs a private entry
+  that overrides the one in `mcp/claude-code.json`. Local scope wins.
+* **opencode** — drop an `opencode.json` at the repo root with the override
+  entries you need. opencode's precedence chain is *global → `OPENCODE_CONFIG`
+  → project*, so the project file always wins. The root `opencode.json` is
+  gitignored on purpose, since these overrides are personal.
+* **VS Code Copilot** — the reconcile deep-merges into `.vscode/mcp.json`, so
+  any servers you add there yourself are preserved (only `penpot`,
+  `serena-devenv` and `playwright` are rewritten). To shadow one of *ours*,
+  put an entry under the same name in your VS Code user-profile MCP config —
+  it is loaded alongside the workspace file and wins.
+* **Codex CLI** — our servers arrive as `-c` overrides, which are Codex's
+  highest-precedence layer, so they win over a same-named `[mcp_servers.<name>]`
+  in your `~/.codex/config.toml` or a project `.codex/config.toml`. To override
+  one of ours, append your own `-c` after the client name — extra args are
+  forwarded after ours and the later `-c` wins, e.g.
+  `./manage.sh start-coding-agent codex -- -c 'mcp_servers.penpot.url="…"'`.
+
+See `docs/technical-guide/developer/agentic-devenv.md` for the broader
+client-configuration story (browser remote debugging, AI-client config
+schemas, manual setup for unsupported clients).
diff --git a/.devenv/scripts/merge-mcp-config.py b/.devenv/scripts/merge-mcp-config.py
new file mode 100755
index 0000000000..ffa5d9a717
--- /dev/null
+++ b/.devenv/scripts/merge-mcp-config.py
@@ -0,0 +1,204 @@
+#!/usr/bin/env python3
+"""Combine a shared MCP-server config with a port-substituted template for one
+AI coding-agent client.
+
+Invoked per workspace by manage.sh's `write-instance-mcp-configs` (JSON
+clients) and by `start-coding-agent` (Codex). Each supported client ships a
+`.devenv/shared/<tool>.{json,toml}` (workspace-independent entries, e.g.
+Playwright) and a `.devenv/templates/<tool>.{json,toml}` (per-workspace entries
+with `${PENPOT_MCP_PORT}` / `${SERENA_MCP_PORT}` placeholders). This script
+combines the two for the target client.
+
+Two output modes are supported:
+
+  json         Deep-merge two JSON documents under a configurable top-level key
+               (`mcpServers` for Claude Code, `mcp` for opencode, `servers` for
+               VS Code Copilot) and write the result to <out>. Same-name
+               entries in the template override entries in shared. With
+               --merge-into-existing, any pre-existing <out> file is loaded as
+               the lowest-precedence layer first, so entries the developer
+               already had are preserved (ours win on name collision). This is
+               used for VS Code's auto-discovered `.vscode/mcp.json`, which on
+               ws0 IS the live repo's file and may hold the developer's own
+               servers; the Claude/opencode outputs live in a dedicated,
+               gitignored `.devenv/mcp/` path and are written without the flag
+               (a clean overwrite).
+
+  codex-args   Deep-merge the two TOML chunks and print one
+               `dotted.key=<toml-value>` assignment per line to stdout (no
+               <out> file). The caller wraps each line in a `codex -c` flag.
+               Codex has no way to load an MCP config from an arbitrary file
+               path (CODEX_HOME would relocate auth/history too), so rather than
+               writing the auto-discovered `.codex/config.toml` we inject our
+               servers as ephemeral per-invocation overrides. This never
+               touches the developer's project- or user-level Codex config.
+
+In both modes, `${VAR}` placeholders inside *either* chunk are resolved from
+the current environment (only template chunks carry placeholders in practice,
+but the substitution is uniform either way) using Python's
+`os.path.expandvars`. Undefined placeholders are left as `${VAR}` literal text
+-- callers (i.e. manage.sh) are responsible for exporting the variables before
+invoking the script.
+
+Usage:
+  merge-mcp-config.py --format json --key <key> [--merge-into-existing] \
+      <shared> <template> <out>
+  merge-mcp-config.py --format codex-args <shared> <template>
+
+Exit codes:
+  0  success
+  2  argparse error (missing required option, bad value, unreadable input)
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import sys
+import tomllib
+from pathlib import Path
+
+
+def merge_json(
+    shared_path: Path,
+    tpl_path: Path,
+    out_path: Path,
+    key: str,
+    merge_into_existing: bool,
+) -> None:
+    """Deep-merge JSON documents under a single top-level dict key into out.
+
+    Precedence (lowest to highest): an existing <out> file (only when
+    merge_into_existing is set), then shared, then the template. Entries under
+    `key` are merged by name, so the template wins on a name collision while
+    every other entry the lower layers contributed is kept. Top-level keys
+    other than `key` come from the existing file and shared (shared wins).
+    """
+    shared = json.loads(shared_path.read_text())
+    tpl = json.loads(os.path.expandvars(tpl_path.read_text()))
+
+    base: dict = {}
+    if merge_into_existing and out_path.exists():
+        base = json.loads(out_path.read_text())
+
+    merged: dict = {**base, **shared}
+    merged[key] = {**base.get(key, {}), **shared.get(key, {}), **tpl.get(key, {})}
+
+    out_path.write_text(json.dumps(merged, indent=2) + "\n")
+
+
+def _deep_merge(base: dict, overlay: dict) -> dict:
+    """Recursively merge overlay into base; overlay wins on scalar/list keys."""
+    out = dict(base)
+    for k, v in overlay.items():
+        if isinstance(out.get(k), dict) and isinstance(v, dict):
+            out[k] = _deep_merge(out[k], v)
+        else:
+            out[k] = v
+    return out
+
+
+def _toml_value(value: object) -> str:
+    """Serialize a scalar/list as a TOML literal for a `codex -c` value.
+
+    bool is checked before int because `isinstance(True, int)` is True. Strings
+    are emitted as JSON strings, which are valid TOML basic strings for the
+    ASCII values our configs carry (commands, args, URLs). Tables never reach
+    here -- they are flattened into dotted keys by _flatten.
+    """
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, (int, float)):
+        return repr(value)
+    if isinstance(value, str):
+        return json.dumps(value)
+    if isinstance(value, list):
+        return "[" + ", ".join(_toml_value(v) for v in value) + "]"
+    raise TypeError(f"unsupported TOML value type: {type(value).__name__}")
+
+
+_BARE_KEY = re.compile(r"^[A-Za-z0-9_-]+$")
+
+
+def _key_segment(seg: str) -> str:
+    """A dotted-key segment: bare if TOML-safe, else a quoted key."""
+    return seg if _BARE_KEY.match(seg) else json.dumps(seg)
+
+
+def _flatten(obj: dict, prefix: list[str]):
+    """Yield (dotted-path-segments, leaf-value) for every non-table leaf.
+
+    Lists are leaves (TOML arrays), so we do not recurse into them; nested
+    tables (e.g. an `env` table) are flattened into further dotted keys.
+    """
+    for k, v in obj.items():
+        path = prefix + [k]
+        if isinstance(v, dict):
+            yield from _flatten(v, path)
+        else:
+            yield path, v
+
+
+def emit_codex_args(shared_path: Path, tpl_path: Path) -> None:
+    """Print `dotted.key=<toml-value>` lines from the merged TOML chunks."""
+    shared = tomllib.loads(os.path.expandvars(shared_path.read_text()))
+    tpl = tomllib.loads(os.path.expandvars(tpl_path.read_text()))
+    merged = _deep_merge(shared, tpl)
+    for path, value in _flatten(merged, []):
+        dotted = ".".join(_key_segment(s) for s in path)
+        sys.stdout.write(f"{dotted}={_toml_value(value)}\n")
+
+
+def main(argv: list[str]) -> int:
+    parser = argparse.ArgumentParser(
+        description=__doc__.split("\n\n", 1)[0],
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument(
+        "--format",
+        choices=("json", "codex-args"),
+        required=True,
+        help="Output mode: 'json' writes a merged file; 'codex-args' prints -c assignments.",
+    )
+    parser.add_argument(
+        "--key",
+        help="Top-level JSON key under which MCP entries live (required for --format json).",
+    )
+    parser.add_argument(
+        "--merge-into-existing",
+        action="store_true",
+        help="json only: layer the merge on top of an existing <out> file, "
+        "preserving entries already there (ours still win on name collision).",
+    )
+    parser.add_argument("shared", type=Path, help="Path to the shared chunk.")
+    parser.add_argument("template", type=Path, help="Path to the port-placeholder template chunk.")
+    parser.add_argument(
+        "out",
+        type=Path,
+        nargs="?",
+        help="Path the merged result is written to (json only; codex-args writes stdout).",
+    )
+    args = parser.parse_args(argv)
+
+    if args.format == "json":
+        if not args.key:
+            parser.error("--key is required when --format json")
+        if args.out is None:
+            parser.error("out is required when --format json")
+        merge_json(args.shared, args.template, args.out, args.key, args.merge_into_existing)
+    else:  # codex-args
+        if args.key:
+            parser.error("--key is not accepted when --format codex-args")
+        if args.merge_into_existing:
+            parser.error("--merge-into-existing is not accepted when --format codex-args")
+        if args.out is not None:
+            parser.error("out path is not accepted when --format codex-args (result goes to stdout)")
+        emit_codex_args(args.shared, args.template)
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))
diff --git a/.devenv/shared/claude-code.json b/.devenv/shared/claude-code.json
new file mode 100644
index 0000000000..9091361a06
--- /dev/null
+++ b/.devenv/shared/claude-code.json
@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "playwright": {
+      "command": "npx",
+      "args": ["@playwright/mcp@latest", "--cdp-endpoint=http://127.0.0.1:9222"]
+    }
+  }
+}
diff --git a/.devenv/shared/codex.toml b/.devenv/shared/codex.toml
new file mode 100644
index 0000000000..1071c8ccf8
--- /dev/null
+++ b/.devenv/shared/codex.toml
@@ -0,0 +1,8 @@
+# Workspace-independent MCP servers for the OpenAI Codex CLI.
+# This block is concatenated with the port-substituted templates/codex.toml
+# by manage.sh's write-instance-mcp-configs to produce .codex/config.toml at
+# the workspace root.
+
+[mcp_servers.playwright]
+command = "npx"
+args = ["@playwright/mcp@latest", "--cdp-endpoint=http://127.0.0.1:9222"]
diff --git a/.devenv/shared/opencode.json b/.devenv/shared/opencode.json
new file mode 100644
index 0000000000..15d8f9372d
--- /dev/null
+++ b/.devenv/shared/opencode.json
@@ -0,0 +1,9 @@
+{
+  "mcp": {
+    "playwright": {
+      "type": "local",
+      "command": ["npx", "@playwright/mcp@latest", "--cdp-endpoint=http://127.0.0.1:9222"],
+      "enabled": true
+    }
+  }
+}
diff --git a/.devenv/shared/vscode.json b/.devenv/shared/vscode.json
new file mode 100644
index 0000000000..bb1a458d0f
--- /dev/null
+++ b/.devenv/shared/vscode.json
@@ -0,0 +1,9 @@
+{
+  "servers": {
+    "playwright": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["@playwright/mcp@latest", "--cdp-endpoint=http://127.0.0.1:9222"]
+    }
+  }
+}
diff --git a/.devenv/templates/claude-code.json b/.devenv/templates/claude-code.json
new file mode 100644
index 0000000000..192a61a177
--- /dev/null
+++ b/.devenv/templates/claude-code.json
@@ -0,0 +1,12 @@
+{
+  "mcpServers": {
+    "penpot": {
+      "command": "npx",
+      "args": ["-y", "mcp-remote", "http://localhost:${PENPOT_MCP_PORT}/mcp", "--allow-http"]
+    },
+    "serena-devenv": {
+      "command": "npx",
+      "args": ["-y", "mcp-remote", "http://localhost:${SERENA_MCP_PORT}/mcp", "--allow-http"]
+    }
+  }
+}
diff --git a/.devenv/templates/codex.toml b/.devenv/templates/codex.toml
new file mode 100644
index 0000000000..3ac341a7fa
--- /dev/null
+++ b/.devenv/templates/codex.toml
@@ -0,0 +1,10 @@
+# Workspace-specific MCP servers for the OpenAI Codex CLI. The PENPOT_MCP_PORT
+# and SERENA_MCP_PORT placeholders below are filled in per workspace by
+# manage.sh's write-instance-mcp-configs, then the result is concatenated
+# with shared/codex.toml to produce .codex/config.toml.
+
+[mcp_servers.penpot]
+url = "http://localhost:${PENPOT_MCP_PORT}/mcp"
+
+[mcp_servers.serena-devenv]
+url = "http://localhost:${SERENA_MCP_PORT}/mcp"
diff --git a/.devenv/templates/opencode.json b/.devenv/templates/opencode.json
new file mode 100644
index 0000000000..4d2db43297
--- /dev/null
+++ b/.devenv/templates/opencode.json
@@ -0,0 +1,14 @@
+{
+  "mcp": {
+    "penpot": {
+      "type": "remote",
+      "url": "http://localhost:${PENPOT_MCP_PORT}/mcp",
+      "enabled": true
+    },
+    "serena-devenv": {
+      "type": "remote",
+      "url": "http://localhost:${SERENA_MCP_PORT}/mcp",
+      "enabled": true
+    }
+  }
+}
diff --git a/.devenv/templates/vscode.json b/.devenv/templates/vscode.json
new file mode 100644
index 0000000000..843b5555b4
--- /dev/null
+++ b/.devenv/templates/vscode.json
@@ -0,0 +1,12 @@
+{
+  "servers": {
+    "penpot": {
+      "type": "http",
+      "url": "http://localhost:${PENPOT_MCP_PORT}/mcp"
+    },
+    "serena-devenv": {
+      "type": "http",
+      "url": "http://localhost:${SERENA_MCP_PORT}/mcp"
+    }
+  }
+}
diff --git a/.gitignore b/.gitignore
index ca6b947232..f800ad7f53 100644
--- a/.gitignore
+++ b/.gitignore
@@ -95,4 +95,7 @@
 /.idea
 /.claude
 /.playwright-mcp
+/.devenv/mcp/
+/opencode.json
+/.codex/
 /tools/__pycache__
diff --git a/.serena/memories/backend/core.md b/.serena/memories/backend/core.md
index 65f513e17c..b7a9199965 100644
--- a/.serena/memories/backend/core.md
+++ b/.serena/memories/backend/core.md
@@ -7,6 +7,7 @@ Backend: JVM Clojure; Integrant; PostgreSQL; Redis/Valkey; RPC; HTTP; storage; m
 - RPC, DB helpers, workers, cron: `mem:backend/rpc-db-worker-subtleties`
 - HTTP sessions, config, storage, media, file data persistence: `mem:backend/http-storage-filedata-subtleties`
 - Auth flows, permission model, teams, projects, invitations, comments, webhooks, audit: `mem:backend/auth-permissions-product-domains`
+- Services, task-queue/Pub-Sub topology constraints -> `mem:prod-infra/core`.
 
 ## Stable namespace map
 
diff --git a/.serena/memories/critical-info.md b/.serena/memories/critical-info.md
index 008b611b8b..17bb15bc55 100644
--- a/.serena/memories/critical-info.md
+++ b/.serena/memories/critical-info.md
@@ -13,15 +13,15 @@ You are working on the GitHub project `penpot/penpot`, a monorepo.
 - You have access to the GitHub CLI `gh` or corresponding MCP tools.
 - Issues are also managed on Taiga. Read issues using the `read_taiga_issue` tool.
 - Before writing code, analyze the task in depth and describe your plan. If the task is complex, break it down into atomic steps.
-* After making changes, run the applicable lint and format checks for the affected module before considering the work done (per example `mem:backend/core` or `mem:frontend/core`).
-
+  *After making changes, run the applicable lint and format checks for the affected module before considering the work done (per example `mem:backend/core` or `mem:frontend/core`).
+- Never run anything that destroys data without explicit permission, including `drop-devenv`, `docker compose down -v`, `docker volume rm ...`. The user's real work lives in the volumes of the shared infra.
 
 # Project modules
 
 This is a monorepo. Principles that apply to one module do *not* generally apply to others. Do not make assumptions.
 
 - `frontend/`: ClojureScript + SCSS SPA/design editor.
-- `backend/`: JVM Clojure HTTP/RPC server with PostgreSQL, Redis, storage, mail, and workers.
+- `backend/`: JVM Clojure HTTP/RPC server with PostgreSQL, Redis, storage, mail, and workers.Runtime services and the task-queue vs Pub/Sub topology that constrains horizontal scaling: `mem:prod-infra/core`.
 - `common/`: shared CLJC data types, geometry, schemas, file/change logic, and utilities.
 - `render-wasm/`: Rust -> WebAssembly Skia renderer consumed by frontend.
 - `exporter/`: ClojureScript/Node headless Playwright SVG/PDF export.
@@ -36,7 +36,9 @@ module. You can read it from `mem:<MODULE>/core`
 # Low-centrality project paths
 
 - `docker/` contains devenv related code, not needed unless specifically instructed.
-   More info in docs/technical-guide if instructed to work on this.
+   When working on devenv startup, compose layout, instance config (`defaults.env`),
+   tmux session lifecycle, MinIO provisioning, or anything in `manage.sh`'s
+   `*-devenv` commands, read `mem:devenv/core`.
 - `experiments/` contains standalone experimental HTML/JS/scripts; treat it as non-core unless the user explicitly asks about it.
 - `sample_media/` contains sample image/icon media and config used as fixtures/demo material; do not infer app behavior from it.
 
diff --git a/.serena/memories/devenv/core.md b/.serena/memories/devenv/core.md
new file mode 100644
index 0000000000..e612a5f923
--- /dev/null
+++ b/.serena/memories/devenv/core.md
@@ -0,0 +1,73 @@
+# Devenv startup and configuration
+
+Compose-based dev environment under `docker/devenv/`, driven by `manage.sh`. Parallel instances share infra + Postgres + MinIO; each instance has its own `main` container, Valkey, source checkout, tmux session.
+
+## Compose project layout
+
+- `penpotdev-infra`: shared `postgres`, `minio`, `minio-setup`, `mailer`, `ldap`. File: `docker-compose.infra.yml`.
+- `penpotdev-wsN` (N=0,1,…): per-instance `main` + `redis` (Valkey). File: `docker-compose.main.yml`. ws0 (a.k.a. `main`) binds `$PWD`; ws1+ bind clones at `${PENPOT_WORKSPACES_DIR}/wsN/` (default `~/.penpot/penpot_workspaces/`), maintained by the developer.
+- All projects join external network `penpot_shared`. Created idempotently by `ensure-devenv-network`, never removed by lifecycle commands.
+
+## Source-of-truth files
+
+- `docker/devenv/defaults.env`: ws0 baseline — container/volume names, runtime env, published host ports, tmux defaults. `manage.sh` aborts if unreadable.
+- For ws1+, `instance-env-overrides` computes the per-instance overrides (container/volume names, host ports offset `10000·N`, `PENPOT_PUBLIC_URI`, `PENPOT_REDIS_URI`, `PENPOT_BACKEND_WORKER=false`) and `instance-compose` injects them as env vars at compose time — never written to disk, recomputed each call so they can't drift. ws0 uses `defaults.env` as-is.
+- `backend/scripts/_env`: backend-internal only — secret keys, `PENPOT_FLAGS` (with `enable-backend-worker` gated on `PENPOT_BACKEND_WORKER`), `JAVA_OPTS`, `setup_minio()`. Never duplicates `defaults.env`.
+- Compose files use pure `${VAR}` substitution; missing var = compose fails.
+
+## Invariants
+
+- `infra-compose` / `instance-compose` wrap `docker compose` with `env -i`, then re-inject what compose needs. Stripping is required because `defaults.env` is sourced into manage.sh's shell at startup (stale values would leak); the ws1+ overrides are deliberately re-injected as shell env vars precisely because Compose gives shell precedence over `--env-file`, so they override the `defaults.env` baseline.
+- Volume names pinned via `name:` (PENPOT_*_VOLUME), decoupled from the compose project name. ws1+ inject distinct per-instance volume names; ws0 keeps the historical `penpotdev_*` physical names so project renames never require data migration.
+- Network aliases (`- main`, `- redis`) are not declared in main.yml. Compose's auto-service-alias still registers `redis` on the shared network, so DNS for `redis` is non-deterministic with multiple instances. Backend uses `PENPOT_REDIS_URI=redis://penpot-devenv-wsN-valkey/0` (container_name) instead.
+- No cross-project `depends_on`. `manage.sh ensure-infra-up` `docker wait`s on the `minio-setup` one-shot.
+- `JAVA_OPTS` in `manage.sh` is shadowed inside the container by `_env`. The `-e JAVA_OPTS=...` flag only matters for processes that don't source `_env`.
+
+## Worker policy
+
+Backend workers run only on ws0. `_env` gates `enable-backend-worker` on `PENPOT_BACKEND_WORKER`; ws1+ inject it as false. ws0 must be running whenever any ws1+ is running, and is the last instance to stop — `run-devenv-agentic --ws N` (N≥1) auto-starts ws0 first; `stop-devenv` refuses to stop ws0 while any ws1+ is up. Workers are pure fire-and-forget: `wrk/submit!` inserts a row into the shared Postgres `task` table and returns; RPC handlers never wait on completion and workers never publish to msgbus. The reason for "ws0 only" is avoiding multi-instance worker races (cron dedup is best-effort across instances, `wrk/submit!` `dedupe` is racy across submitters); details in `mem:prod-infra/core`.
+
+## Port layout
+
+Container-internal ports fixed; host side offset `10000·N`.
+
+| ws0 | ws1 | wsN | container | role |
+|---|---|---|---|---|
+| 3449 | 13449 | 3449+10000·N | 3449 | public HTTPS (Caddy; `/mcp/ws` same-origin) |
+| 3449/udp | 13449/udp | … | 3449/udp | HTTP/3 |
+| 4401 | 14401 | … | 4401 | MCP HTTP stream |
+| 4403 | 14403 | … | 4403 | MCP REPL |
+| 14181 | 24181 | … | 14281 | Serena MCP |
+| 14182 | 24182 | … | 24282 | Serena dashboard |
+
+Everything else (frontend dev, backend API, exporter, storybook, REPLs, plugin dev, MCP inspector/WebSocket) is in-process or same-origin via Caddy/nginx. Infra publishes: mailer 1080, ldap 10389/10636 (singletons, not offset).
+
+## Tmux + MCP routing
+
+`docker/devenv/files/start-tmux.sh` is session-level idempotent. Reads `PENPOT_TMUX_ATTACH`. If the session exists it attaches or exits; otherwise creates 4 base windows (frontend watch / storybook / exporter / backend) plus `mcp` (when `enable-mcp` in `PENPOT_FLAGS`) and `serena` (when `SERENA_ENABLED=true`). `run-devenv-agentic` always sets both env vars. The legacy `run-devenv` alias doesn't, hence its 4-window-only session. To switch from a legacy session to agentic, `stop-devenv` then `run-devenv-agentic` — the conditional windows are only added at session create time.
+
+MCP plugin routing is same-origin: frontend uses `<public-uri>/mcp/ws`, per-instance nginx proxies to MCP port 4401 in-container. For the plugin↔MCP server wiring (how the browser plugin discovers the URL, the in-memory connection registry, why DB-mediated routing isn't needed), see `mem:mcp/core`.
+
+## Workspace orchestration (ws1+)
+
+Workspace directories are user-maintained at `${PENPOT_WORKSPACES_DIR}/wsN`. `run-devenv-agentic --ws i` syncs only when `--sync` is passed, with one exception: if the workspace directory is missing on first use, sync runs implicitly to seed it.
+
+`sync-workspace wsN`:
+1. `assert-clean-git-state` — refuses on `.git/{rebase-apply,rebase-merge,MERGE_HEAD,CHERRY_PICK_HEAD,index.lock}`. No `--sync-force` escape.
+2. `rsync -a --delete $PWD/.git/ $workspace/.git/`.
+3. `git ls-files -z --cached --others --exclude-standard` → `rsync --files-from` (Git is the authority on tracked files; rsync's gitignore filter would drop committed files under gitignored parents like `.clj-kondo/config.edn`).
+4. Initial-only copy of `frontend/resources/public/js/config.js` (gitignored, but agentic mode needs it). After the first sync the workspace's copy belongs to the developer — subsequent syncs leave it alone.
+5. `git switch -C "wsN/<current-branch>"` inside the workspace.
+
+No `--delete` on the working-tree pass: gitignored caches in the workspace survive. Workspace dir + named volumes survive `compose down`.
+
+## CLI surface
+
+- `run-devenv-agentic [--ws main|0|wsN|N] [--sync] [--serena-context CTX]`: bring one instance up. Agentic only — MCP and Serena windows are always created. Default target main. Errors out if the target is already running. `--sync` is rejected on main; on ws1+ it's optional (forced only when the workspace dir does not exist yet). Auto-starts ws0 first when the target is ws1+ and ws0 is not yet up.
+- `stop-devenv [--ws main|0|wsN|N] [--all]`: stop instances. Flags mutually exclusive. `--ws N` (N≥1) stops just that workspace. `--ws 0` or no flag stops ws0 + shared infra, refused while any ws1+ is running. `--all` stops every ws highest-first then ws0, then infra.
+- `run-devenv`: legacy alias, ws0 non-agentic attached.
+- `attach-devenv [--ws main|0|wsN|N]`: pure attach. Fails fast if instance/session missing.
+- `run-devenv-shell [--instance 0|wsN|N] [cmd...]`: bash in target instance. (`--instance` flag not yet renamed to `--ws`.)
+- `start-devenv` / `log-devenv` / `drop-devenv`: legacy paths around ws0 + shared infra. `drop-devenv` never removes volumes.
+
+`exporter/scripts/run` and `wait-and-start.sh` source `backend/scripts/_env` then `_env.local` if present.
diff --git a/.serena/memories/mcp/core.md b/.serena/memories/mcp/core.md
index ba794b1d0f..772f7a3949 100644
--- a/.serena/memories/mcp/core.md
+++ b/.serena/memories/mcp/core.md
@@ -85,3 +85,11 @@ From the `mcp/` directory, run
 
 * `pnpm run build` to test the build of all packages
 * `pnpm run fmt` to apply the auto-formatter
+
+## Devenv plugin/server wiring
+
+In the normal Penpot devenv MCP path, the browser plugin does not discover or route through Postgres. The frontend provides the plugin extension API with `mcp.getServerUrl()`, currently derived from `frontend/src/app/config.cljs` as `penpotMcpServerURI` if set, otherwise `<public-uri>/mcp/ws`. The MCP plugin opens a direct WebSocket to that URL and appends the current MCP access token as a query parameter.
+
+The live plugin connection registry is in-memory inside each MCP server process (`PluginBridge.connectedClients` / `clientsByToken`). The database only stores MCP access tokens and profile props such as `mcp-enabled`; it does not manage which plugin is connected to which MCP server.
+
+For parallel devenvs, prefer same-origin MCP routing: each Penpot instance should expose `/mcp/ws` through its own nginx/Caddy path to the MCP server running inside the same main container. Keep container-internal ports fixed (MCP defaults `4401/4402/4403`, backend/exporter/frontend defaults, etc.) and only offset host-side published ports per instance. If internal ports are offset, hardcoded local proxy config such as `docker/devenv/files/nginx.conf` will misroute unless templated too.
diff --git a/.serena/memories/prod-infra/core.md b/.serena/memories/prod-infra/core.md
new file mode 100644
index 0000000000..e86eb69a32
--- /dev/null
+++ b/.serena/memories/prod-infra/core.md
@@ -0,0 +1,33 @@
+# Production infrastructure (services Penpot depends on)
+
+Backend (`app.config`, `PENPOT_*` env vars) is parameterized; deployments choose providers.
+
+## Services
+
+- **PostgreSQL**: durable store. Profiles, teams, files, sessions, audit, `storage_object` metadata, the `task` queue, `scheduled_task` cron registry, migrations. File-data also lives here when the file-data backend is `legacy-db`/`db`. One shared DB across all backends.
+- **Redis (Valkey-compatible)**: per-backend message bus and cache. Concrete uses: msgbus Pub/Sub for collaborative-editing broadcasts and team/profile-org notifications fired by RPC handlers (`app.rpc.notifications`, `files_update`, `teams`, `websocket`); file-summary cache gated by `enable-redis-cache`; rate-limit counters; and the dispatcher→runner work hand-off list `penpot.worker.queue:<tenant>:<queue>`. `PENPOT_REDIS_URI`.
+- **Object storage**: backends `:s3` and `:fs`. S3 in prod; devenv uses MinIO. Holds uploaded media, file-data when the file-data backend is `storage`, exports. Backend-side details (resolve, dedup, bucket set, file-data backends): `mem:backend/http-storage-filedata-subtleties`.
+- **SMTP mailer**: invitations, password resets, email verification (sent via the `:sendmail` worker task).
+- **LDAP** (optional auth provider): helpers in `app.auth.*`, gated by `enable-login-with-ldap`.
+
+## Task queue and worker model
+
+Async tasks are enqueued via `wrk/submit!` (`app.worker`), which inserts a row into the shared Postgres `task` table tagged with `queue = "<tenant>:<queue-name>"`. Submission is **fire-and-forget** — RPC handlers never poll, never wait, and workers never publish to msgbus. The only completion signal is the `task` row's `status` / `completed_at` columns, which nothing in `rpc/` reads. Soft-delete RPCs return immediately after marking the top-level row, leaving the cascade and reaping to workers.
+
+Workers run on backends with `enable-backend-worker` in `PENPOT_FLAGS`. Each worker-enabled backend has a `dispatcher` (polls `task` with `FOR UPDATE SKIP LOCKED`, marks status='scheduled', RPUSHes claimed task IDs into **its own** Redis list) and one or more `runner`s per queue (BLPOP from that same local list, execute, update the Postgres row). The Redis hand-off list is purely intra-backend — cross-backend coordination happens at the Postgres row level.
+
+## Cross-backend safety
+
+Postgres row locking is the only correctness primitive: `task` claims via `FOR UPDATE SKIP LOCKED`, cron firing via `FOR UPDATE SKIP LOCKED` on the `scheduled_task` row, plus task-handler-internal locks (e.g. `file_gc_scheduler` locks candidate file rows). This makes the work-claim path safe across any number of worker-enabled backends.
+
+Two known race patterns survive multi-backend operation:
+
+- **Cron dedup is best-effort.** The lock on `scheduled_task` is released when the task body finishes. If two backends' cron timers fire for the same scheduled instant with a gap larger than the task body's runtime, both execute it. Penpot's cron entries are idempotent (`session-gc`, `objects-gc`, `storage-gc-*`, `tasks-gc`, `upload-session-gc`, `file-gc-scheduler`); the exceptions are `:telemetry` (would double-report) and `:audit-log-archive` (depends on archive target idempotency).
+- **`wrk/submit! ::dedupe true`** does a non-atomic `DELETE` then `INSERT`. Concurrent cross-backend submits can both bypass the `DELETE` (each sees the other's uncommitted insert as absent) and end up with duplicate `'new'` rows. Each row claims and runs once independently, so the underlying work is fine; the "at most one pending" guarantee weakens.
+
+Penpot in production lives with both: horizontal-scale deployments accept "exactly-once" as "essentially-once for idempotent operations." Devenv parallel instances handle it by running workers only on ws0 (see `mem:devenv/core`).
+
+## See also
+
+- Devenv composition and the ws0-only worker placement: `mem:devenv/core`.
+- Storage backend resolution, dedup, file-data lifecycle: `mem:backend/http-storage-filedata-subtleties`.
diff --git a/backend/scripts/_env b/backend/scripts/_env
index 2a89244a81..b68d7d85ec 100644
--- a/backend/scripts/_env
+++ b/backend/scripts/_env
@@ -8,8 +8,18 @@ export PENPOT_SECRET_KEY=super-secret-devenv-key
 # DEPRECATED: only used for subscriptions
 export PENPOT_MANAGEMENT_API_KEY=super-secret-management-api-key
 
-export PENPOT_HOST=devenv
-export PENPOT_PUBLIC_URI=https://localhost:3449
+# Runtime config that varies per devenv instance (PENPOT_HOST, PENPOT_PUBLIC_URI,
+# PENPOT_DATABASE_*, PENPOT_REDIS_URI, PENPOT_OBJECTS_STORAGE_*, AWS_*) is owned by
+# docker/devenv/defaults.env and injected via the main service's env block.
+
+# Background worker flag is per-instance. Defaults to enabled (ws0); ws1+
+# overlays set PENPOT_BACKEND_WORKER=false so scheduled and async tasks only
+# run on ws0, keeping notification Pub/Sub bound to a single Valkey. See
+# mem:devenv/core for the rationale.
+__worker_flag=""
+if [[ "${PENPOT_BACKEND_WORKER:-true}" == "true" ]]; then
+    __worker_flag="enable-backend-worker"
+fi
 
 export PENPOT_FLAGS="\
        $PENPOT_FLAGS \
@@ -20,7 +30,7 @@ export PENPOT_FLAGS="\
        disable-login-with-github \
        disable-login-with-gitlab \
        disable-telemetry \
-       enable-backend-worker \
+       $__worker_flag \
        enable-backend-asserts \
        disable-feature-fdata-pointer-map \
        enable-feature-fdata-objects-map \
@@ -60,12 +70,6 @@ export PENPOT_HTTP_SERVER_MAX_MULTIPART_BODY_SIZE=314572800
 
 export PENPOT_USER_FEEDBACK_DESTINATION="support@example.com"
 
-export AWS_ACCESS_KEY_ID=penpot-devenv
-export AWS_SECRET_ACCESS_KEY=penpot-devenv
-export PENPOT_OBJECTS_STORAGE_BACKEND=s3
-export PENPOT_OBJECTS_STORAGE_S3_ENDPOINT=http://minio:9000
-export PENPOT_OBJECTS_STORAGE_S3_BUCKET=penpot
-
 export PENPOT_NITRATE_BACKEND_URI=http://localhost:3000/admin-console
 
 export JAVA_OPTS="\
@@ -84,14 +88,14 @@ export JAVA_OPTS="\
        --enable-native-access=ALL-UNNAMED";
 
 function setup_minio() {
-    # Initialize MINIO config
-    mc alias set penpot-s3/ http://minio:9000 minioadmin minioadmin -q
-    mc admin user add penpot-s3 penpot-devenv penpot-devenv -q
-    mc admin user info penpot-s3 penpot-devenv |grep -F -q "readwrite"
-    if [ "$?" = "1" ]; then
-        mc admin policy attach penpot-s3 readwrite --user=penpot-devenv -q
+    if [ "${PENPOT_OBJECTS_STORAGE_BACKEND}" != "s3" ]; then
+        return 0
     fi
-    mc mb penpot-s3/penpot -p -q
+
+    # Shared MinIO user/policy provisioning is handled by docker-compose.infra.yml.
+    # Per process startup only ensures that the configured bucket exists.
+    mc alias set penpot-s3/ "${PENPOT_OBJECTS_STORAGE_S3_ENDPOINT}" minioadmin minioadmin -q
+    mc mb "penpot-s3/${PENPOT_OBJECTS_STORAGE_S3_BUCKET}" -p -q
 }
 
 
diff --git a/docker/devenv/defaults.env b/docker/devenv/defaults.env
new file mode 100644
index 0000000000..70368b3c64
--- /dev/null
+++ b/docker/devenv/defaults.env
@@ -0,0 +1,69 @@
+# Single source of truth for instance-specific devenv configuration.
+# Loaded by docker compose via --env-file and also sourced by manage.sh
+# (see manage.sh). This is the ws0 baseline; for ws1+ manage.sh injects the
+# per-instance values as environment variables (see instance-env-overrides),
+# which override these via Compose's shell-over-env-file precedence. Variables
+# not overridden fall back to the values here.
+#
+# Backend runtime defaults that compose does not care about live in
+# backend/scripts/_env.
+
+# Container names and volume names. Volumes are pinned by explicit name
+# (rather than relying on COMPOSE_PROJECT_NAME prefixing) so the physical
+# volumes survive project renames without a data migration. ws0 reuses the
+# pre-Stage-2 physical volume names (penpotdev_*).
+PENPOT_MAIN_CONTAINER_NAME=penpot-devenv-ws0-main
+PENPOT_VALKEY_CONTAINER_NAME=penpot-devenv-ws0-valkey
+PENPOT_VALKEY_HOSTNAME=penpot-devenv-ws0-valkey
+PENPOT_POSTGRES_DATA_VOLUME=penpotdev_postgres_data_pg16
+PENPOT_MINIO_DATA_VOLUME=penpotdev_minio_data
+PENPOT_USER_DATA_VOLUME=penpotdev_user_data
+PENPOT_VALKEY_DATA_VOLUME=penpotdev_valkey_data
+
+# Backend runtime config (passed to the container env block). PENPOT_REDIS_URI
+# is set explicitly per instance to match the per-instance Valkey container
+# name; ws1+ overlays override this.
+PENPOT_HOST=devenv
+PENPOT_PUBLIC_URI=https://localhost:3449
+PENPOT_DATABASE_URI=postgresql://postgres/penpot
+PENPOT_DATABASE_USERNAME=penpot
+PENPOT_DATABASE_PASSWORD=penpot
+PENPOT_DATABASE_MAX_POOL_SIZE=20
+PENPOT_REDIS_URI=redis://penpot-devenv-ws0-valkey/0
+
+# Object storage (MinIO user/policy are provisioned by the infra compose file).
+PENPOT_OBJECTS_STORAGE_BACKEND=s3
+PENPOT_OBJECTS_STORAGE_S3_ENDPOINT=http://minio:9000
+PENPOT_OBJECTS_STORAGE_S3_BUCKET=penpot
+AWS_ACCESS_KEY_ID=penpot-devenv
+AWS_SECRET_ACCESS_KEY=penpot-devenv
+
+# Published host ports. Only ports that need to be reachable from outside the
+# container are exposed; everything else (frontend dev server, backend API,
+# storybook, exporter, REPLs, plugins, MCP inspector/websocket, aux) is
+# accessed in-process or through the same-origin Caddy/nginx proxy at
+# PENPOT_PUBLIC_HTTP_PORT. Container-internal ports remain fixed; per-instance
+# overlays may offset these host-side values.
+PENPOT_PUBLIC_HTTP_PORT=3449
+PENPOT_MCP_SERVER_PORT=4401
+PENPOT_MCP_REPL_PORT=4403
+
+SHADOW_SERVER_URL=wss://localhost:3449
+
+# Serena (agentic devenv). These are the published host ports for ws0; ws1+
+# offset them by 10000*N. The container-internal ports (Serena MCP 14281,
+# dashboard 24282) are fixed by Serena and mapped to these in compose.
+SERENA_EXTERNAL_PORT=14181
+SERENA_DASHBOARD_EXTERNAL_PORT=14182
+
+# Backend worker (scheduled + async tasks). ws0 only; per-instance overlays
+# for ws1+ override this to false. See mem:devenv/core.
+PENPOT_BACKEND_WORKER=true
+
+# Tmux session inside the main container.
+PENPOT_TMUX_ATTACH=true
+
+# Base directory holding non-main workspace clones (one subdir per wsN, N>=1).
+# Consumed by manage.sh only. Default lives in manage.sh ($HOME expansion is
+# not applied to values in this file). Export PENPOT_WORKSPACES_DIR to
+# override.
diff --git a/docker/devenv/docker-compose.infra.yml b/docker/devenv/docker-compose.infra.yml
new file mode 100644
index 0000000000..5bf979c4f8
--- /dev/null
+++ b/docker/devenv/docker-compose.infra.yml
@@ -0,0 +1,99 @@
+networks:
+  default:
+    name: penpot_shared
+    external: true
+
+volumes:
+  postgres_data_pg16:
+    name: ${PENPOT_POSTGRES_DATA_VOLUME}
+  minio_data:
+    name: ${PENPOT_MINIO_DATA_VOLUME}
+
+services:
+  minio:
+    image: "minio/minio:RELEASE.2025-04-03T14-56-28Z"
+    command: minio server /mnt/data --console-address ":9001"
+
+    volumes:
+      - "minio_data:/mnt/data"
+
+    environment:
+      - MINIO_ROOT_USER=minioadmin
+      - MINIO_ROOT_PASSWORD=minioadmin
+
+    networks:
+      default:
+        aliases:
+          - minio
+
+  minio-setup:
+    image: "minio/mc:latest"
+    depends_on:
+      - minio
+    entrypoint: ["/bin/sh", "-c"]
+    command:
+      - |
+        attempts=0
+        until mc alias set penpot-s3 http://minio:9000 minioadmin minioadmin -q; do
+          attempts=$$((attempts + 1))
+          if [ "$$attempts" -ge 30 ]; then
+            echo "minio-setup: gave up waiting for MinIO after $$attempts attempts" >&2
+            exit 1
+          fi
+          sleep 1
+        done
+        mc admin user info penpot-s3 penpot-devenv >/dev/null 2>&1 || mc admin user add penpot-s3 penpot-devenv penpot-devenv -q
+        mc admin policy attach penpot-s3 readwrite --user=penpot-devenv -q
+    networks:
+      default:
+
+  postgres:
+    image: postgres:16.8
+    command: postgres -c config_file=/etc/postgresql.conf
+    restart: always
+    stop_signal: SIGINT
+    environment:
+      - POSTGRES_INITDB_ARGS=--data-checksums
+      - POSTGRES_DB=penpot
+      - POSTGRES_USER=penpot
+      - POSTGRES_PASSWORD=penpot
+    volumes:
+      - ./files/postgresql.conf:/etc/postgresql.conf:z
+      - ./files/postgresql_init.sql:/docker-entrypoint-initdb.d/init.sql:z
+      - postgres_data_pg16:/var/lib/postgresql/data
+    networks:
+      default:
+        aliases:
+          - postgres
+
+  mailer:
+    image: sj26/mailcatcher:latest
+    restart: always
+    expose:
+      - '1025'
+    ports:
+      - "1080:1080"
+
+    networks:
+      default:
+        aliases:
+          - mailer
+
+  # https://github.com/rroemhild/docker-test-openldap
+  ldap:
+    image: rroemhild/test-openldap:2.1
+    expose:
+      - '10389'
+      - '10636'
+    ports:
+      - "10389:10389"
+      - "10636:10636"
+    ulimits:
+      nofile:
+        soft: 1024
+        hard: 1024
+
+    networks:
+      default:
+        aliases:
+          - ldap
diff --git a/docker/devenv/docker-compose.main.yml b/docker/devenv/docker-compose.main.yml
new file mode 100644
index 0000000000..fb8caf78c7
--- /dev/null
+++ b/docker/devenv/docker-compose.main.yml
@@ -0,0 +1,106 @@
+networks:
+  default:
+    name: penpot_shared
+    external: true
+
+volumes:
+  user_data:
+    name: ${PENPOT_USER_DATA_VOLUME}
+  valkey_data:
+    name: ${PENPOT_VALKEY_DATA_VOLUME}
+
+services:
+  main:
+    privileged: true
+    image: "penpotapp/devenv:latest"
+    build:
+      context: "."
+    container_name: "${PENPOT_MAIN_CONTAINER_NAME}"
+    stop_signal: SIGINT
+
+    # postgres / minio / minio-setup live in the penpotdev-infra compose
+    # project and cannot be referenced via depends_on across projects.
+    # manage.sh waits for infra readiness before bringing main up.
+    depends_on:
+      redis:
+        condition: service_started
+
+    volumes:
+      - "user_data:/home/penpot/"
+      - "${PENPOT_SOURCE_PATH}:/home/penpot/penpot:z"
+
+    ports:
+      # Host ports are instance-specific; container ports stay fixed.
+      - ${PENPOT_PUBLIC_HTTP_PORT}:3449
+      - ${PENPOT_PUBLIC_HTTP_PORT}:3449/udp
+
+      # MCP
+      - ${PENPOT_MCP_SERVER_PORT}:4401
+      - ${PENPOT_MCP_REPL_PORT}:4403
+
+      # Serena MCP server (agentic mode only). Internal ports fixed by Serena.
+      - ${SERENA_EXTERNAL_PORT}:14281
+      - ${SERENA_DASHBOARD_EXTERNAL_PORT}:24282
+
+    environment:
+      - EXTERNAL_UID=${CURRENT_USER_ID}
+
+      # SMTP setup (shared infra service; identical across instances)
+      - PENPOT_SMTP_ENABLED=true
+      - PENPOT_SMTP_DEFAULT_FROM=no-reply@example.com
+      - PENPOT_SMTP_DEFAULT_REPLY_TO=no-reply@example.com
+      - PENPOT_SMTP_HOST=mailer
+      - PENPOT_SMTP_PORT=1025
+      - PENPOT_SMTP_USERNAME=
+      - PENPOT_SMTP_PASSWORD=
+      - PENPOT_SMTP_SSL=false
+      - PENPOT_SMTP_TLS=false
+
+      # LDAP setup (shared infra service; identical across instances)
+      - PENPOT_LDAP_HOST=ldap
+      - PENPOT_LDAP_PORT=10389
+      - PENPOT_LDAP_SSL=false
+      - PENPOT_LDAP_STARTTLS=false
+      - PENPOT_LDAP_BASE_DN=ou=people,dc=planetexpress,dc=com
+      - PENPOT_LDAP_BIND_DN=cn=admin,dc=planetexpress,dc=com
+      - PENPOT_LDAP_BIND_PASSWORD=GoodNewsEveryone
+      - PENPOT_LDAP_ATTRS_USERNAME=uid
+      - PENPOT_LDAP_ATTRS_EMAIL=mail
+      - PENPOT_LDAP_ATTRS_FULLNAME=cn
+      - PENPOT_LDAP_ATTRS_PHOTO=jpegPhoto
+
+      # Per-instance runtime config. Defaults live in defaults.env.
+      - PENPOT_HOST=${PENPOT_HOST}
+      - PENPOT_PUBLIC_URI=${PENPOT_PUBLIC_URI}
+      - PENPOT_DATABASE_URI=${PENPOT_DATABASE_URI}
+      - PENPOT_DATABASE_USERNAME=${PENPOT_DATABASE_USERNAME}
+      - PENPOT_DATABASE_PASSWORD=${PENPOT_DATABASE_PASSWORD}
+      - PENPOT_DATABASE_MAX_POOL_SIZE=${PENPOT_DATABASE_MAX_POOL_SIZE}
+      - PENPOT_REDIS_URI=${PENPOT_REDIS_URI}
+      - PENPOT_OBJECTS_STORAGE_BACKEND=${PENPOT_OBJECTS_STORAGE_BACKEND}
+      - PENPOT_OBJECTS_STORAGE_S3_ENDPOINT=${PENPOT_OBJECTS_STORAGE_S3_ENDPOINT}
+      - PENPOT_OBJECTS_STORAGE_S3_BUCKET=${PENPOT_OBJECTS_STORAGE_S3_BUCKET}
+      - AWS_ACCESS_KEY_ID=${AWS_ACCESS_KEY_ID}
+      - AWS_SECRET_ACCESS_KEY=${AWS_SECRET_ACCESS_KEY}
+      - PENPOT_BACKEND_WORKER=${PENPOT_BACKEND_WORKER}
+      - PENPOT_TMUX_ATTACH=${PENPOT_TMUX_ATTACH}
+
+      # Agentic devenv: set to a commit/tag to update Serena on startup,
+      # leave empty to skip update and use the version baked into the image.
+      - SERENA_UPDATE_VERSION=1.5.0
+      - SHADOW_SERVER_URL=${SHADOW_SERVER_URL}
+
+    networks:
+      - default
+
+  redis:
+    image: valkey/valkey:8.1
+    hostname: "${PENPOT_VALKEY_HOSTNAME}"
+    container_name: "${PENPOT_VALKEY_CONTAINER_NAME}"
+    restart: always
+    command: valkey-server --save 120 1 --loglevel warning
+    volumes:
+      - "valkey_data:/data"
+
+    networks:
+      - default
diff --git a/docker/devenv/docker-compose.yaml b/docker/devenv/docker-compose.yaml
deleted file mode 100644
index 6963b18d8a..0000000000
--- a/docker/devenv/docker-compose.yaml
+++ /dev/null
@@ -1,180 +0,0 @@
-networks:
-  default:
-    driver: bridge
-    ipam:
-      config:
-        - subnet: 172.177.9.0/24
-
-volumes:
-  postgres_data_pg16:
-  user_data:
-  minio_data:
-  valkey_data:
-
-services:
-  main:
-    privileged: true
-    image: "penpotapp/devenv:latest"
-    build:
-      context: "."
-    container_name: "penpot-devenv-main"
-    stop_signal: SIGINT
-
-    depends_on:
-      - postgres
-      - redis
-      # - keycloak
-
-    volumes:
-      - "user_data:/home/penpot/"
-      - "${PWD}:/home/penpot/penpot:z"
-
-    ports:
-      - 3447:3447
-      - 3448:3448
-      - 3449:3449
-      - 3449:3449/udp
-      - 3450:3450
-      - 6006:6006
-      - 6060:6060
-      - 6061:6061
-      - 6062:6062
-      - 6063:6063
-      - 6064:6064
-      - 9000:9000
-      - 9001:9001
-      - 9090:9090
-      - 9091:9091
-
-      # MCP
-      - 4400:4400
-      - 4401:4401
-      - 4402:4402
-      - 4403:4403
-
-      # Plugins
-      - 4200:4200
-      - 4201:4201
-      - 4202:4202
-
-      # Serena MCP server (agentic mode only)
-      - ${SERENA_EXTERNAL_PORT:-14281}:14281
-      - ${SERENA_DASHBOARD_EXTERNAL_PORT:-14282}:24282
-
-    environment:
-      - EXTERNAL_UID=${CURRENT_USER_ID}
-      # SMTP setup
-      - PENPOT_SMTP_ENABLED=true
-      - PENPOT_SMTP_DEFAULT_FROM=no-reply@example.com
-      - PENPOT_SMTP_DEFAULT_REPLY_TO=no-reply@example.com
-      - PENPOT_SMTP_HOST=mailer
-      - PENPOT_SMTP_PORT=1025
-      - PENPOT_SMTP_USERNAME=
-      - PENPOT_SMTP_PASSWORD=
-      - PENPOT_SMTP_SSL=false
-      - PENPOT_SMTP_TLS=false
-
-      # LDAP setup
-      - PENPOT_LDAP_HOST=ldap
-      - PENPOT_LDAP_PORT=10389
-      - PENPOT_LDAP_SSL=false
-      - PENPOT_LDAP_STARTTLS=false
-      - PENPOT_LDAP_BASE_DN=ou=people,dc=planetexpress,dc=com
-      - PENPOT_LDAP_BIND_DN=cn=admin,dc=planetexpress,dc=com
-      - PENPOT_LDAP_BIND_PASSWORD=GoodNewsEveryone
-      - PENPOT_LDAP_ATTRS_USERNAME=uid
-      - PENPOT_LDAP_ATTRS_EMAIL=mail
-      - PENPOT_LDAP_ATTRS_FULLNAME=cn
-      - PENPOT_LDAP_ATTRS_PHOTO=jpegPhoto
-
-      # agentic devenv
-      # Serena update: set to a commit/tag to update Serena on startup, leave empty to skip update and use the version in the image
-      - SERENA_UPDATE_VERSION=1.5.0
-
-    networks:
-      default:
-        aliases:
-          - main
-
-  minio:
-    image: "minio/minio:RELEASE.2025-04-03T14-56-28Z"
-    command: minio server /mnt/data --console-address ":9001"
-
-    volumes:
-      - "minio_data:/mnt/data"
-
-    environment:
-      - MINIO_ROOT_USER=minioadmin
-      - MINIO_ROOT_PASSWORD=minioadmin
-
-    networks:
-      default:
-        aliases:
-          - minio
-
-  postgres:
-    image: postgres:16.8
-    command: postgres -c config_file=/etc/postgresql.conf
-    restart: always
-    stop_signal: SIGINT
-    environment:
-      - POSTGRES_INITDB_ARGS=--data-checksums
-      - POSTGRES_DB=penpot
-      - POSTGRES_USER=penpot
-      - POSTGRES_PASSWORD=penpot
-    volumes:
-      - ./files/postgresql.conf:/etc/postgresql.conf:z
-      - ./files/postgresql_init.sql:/docker-entrypoint-initdb.d/init.sql:z
-      - postgres_data_pg16:/var/lib/postgresql/data
-    networks:
-      default:
-        aliases:
-          - postgres
-
-  redis:
-    image: valkey/valkey:8.1
-    hostname: "penpot-devenv-valkey"
-    container_name: "penpot-devenv-valkey"
-    restart: always
-    command: valkey-server --save 120 1 --loglevel warning
-    volumes:
-      - "valkey_data:/data"
-
-    networks:
-      default:
-        aliases:
-          - redis
-
-  mailer:
-    image: sj26/mailcatcher:latest
-    restart: always
-    expose:
-      - '1025'
-    ports:
-      - "1080:1080"
-
-    networks:
-      default:
-        aliases:
-          - mailer
-
-
-  # https://github.com/rroemhild/docker-test-openldap
-  ldap:
-    image: rroemhild/test-openldap:2.1
-    expose:
-      - '10389'
-      - '10636'
-    ports:
-      - "10389:10389"
-      - "10636:10636"
-    ulimits:
-      nofile:
-        soft: 1024
-        hard: 1024
-
-    networks:
-      default:
-        aliases:
-          - ldap
-
diff --git a/docker/devenv/files/Caddyfile b/docker/devenv/files/Caddyfile
index a4e81434b0..1aa1f6b6a6 100644
--- a/docker/devenv/files/Caddyfile
+++ b/docker/devenv/files/Caddyfile
@@ -15,7 +15,3 @@ localhost:3449 {
 	# }
 	reverse_proxy localhost:4449
 }
-
-http://penpot-devenv-main:3450 {
-	reverse_proxy localhost:4449
-}
diff --git a/docker/devenv/files/nginx.conf b/docker/devenv/files/nginx.conf
index 5847e6551a..ce5566079f 100644
--- a/docker/devenv/files/nginx.conf
+++ b/docker/devenv/files/nginx.conf
@@ -136,6 +136,13 @@ http {
             proxy_http_version 1.1;
         }
 
+        location /api/remote-relay {
+            proxy_set_header Upgrade $http_upgrade;
+            proxy_set_header Connection 'upgrade';
+            proxy_pass http://127.0.0.1:3448;
+            proxy_http_version 1.1;
+        }
+
         location /mcp/ws {
             proxy_set_header Upgrade $http_upgrade;
             proxy_set_header Connection 'upgrade';
diff --git a/docker/devenv/files/start-tmux.sh b/docker/devenv/files/start-tmux.sh
index ae61f32c5c..a029dbe84a 100755
--- a/docker/devenv/files/start-tmux.sh
+++ b/docker/devenv/files/start-tmux.sh
@@ -6,6 +6,23 @@ cd ~;
 
 source ~/.bashrc
 
+PENPOT_TMUX_SESSION="penpot"
+PENPOT_TMUX_ATTACH="${PENPOT_TMUX_ATTACH:-true}"
+
+function attach_or_exit() {
+    if [ "$PENPOT_TMUX_ATTACH" = "true" ]; then
+        exec tmux -2 attach-session -t "$PENPOT_TMUX_SESSION"
+    fi
+
+    echo "[start-tmux.sh] tmux session '$PENPOT_TMUX_SESSION' is running detached"
+    exit 0
+}
+
+if tmux has-session -t "$PENPOT_TMUX_SESSION" 2>/dev/null; then
+    echo "[start-tmux.sh] Reusing existing tmux session '$PENPOT_TMUX_SESSION'"
+    attach_or_exit
+fi
+
 echo "[start-tmux.sh] Installing node dependencies"
 pushd ~/penpot/frontend/
 ./scripts/setup;
@@ -14,32 +31,32 @@ pushd ~/penpot/exporter/
 ./scripts/setup;
 popd
 
-tmux -2 new-session -d -s penpot
+tmux -2 new-session -d -s "$PENPOT_TMUX_SESSION"
 
-tmux rename-window -t penpot:0 'frontend watch'
-tmux select-window -t penpot:0
-tmux send-keys -t penpot 'cd penpot/frontend' enter C-l
-tmux send-keys -t penpot './scripts/watch app' enter
+tmux rename-window -t "$PENPOT_TMUX_SESSION:0" 'frontend watch'
+tmux select-window -t "$PENPOT_TMUX_SESSION:0"
+tmux send-keys -t "$PENPOT_TMUX_SESSION" 'cd penpot/frontend' enter C-l
+tmux send-keys -t "$PENPOT_TMUX_SESSION" './scripts/watch app' enter
 
-tmux new-window -t penpot:1 -n 'frontend storybook'
-tmux select-window -t penpot:1
-tmux send-keys -t penpot 'cd penpot/frontend' enter C-l
-tmux send-keys -t penpot './scripts/watch storybook' enter
+tmux new-window -t "$PENPOT_TMUX_SESSION:1" -n 'frontend storybook'
+tmux select-window -t "$PENPOT_TMUX_SESSION:1"
+tmux send-keys -t "$PENPOT_TMUX_SESSION" 'cd penpot/frontend' enter C-l
+tmux send-keys -t "$PENPOT_TMUX_SESSION" './scripts/watch storybook' enter
 
-tmux new-window -t penpot:2 -n 'exporter'
-tmux select-window -t penpot:2
-tmux send-keys -t penpot 'cd penpot/exporter' enter C-l
-tmux send-keys -t penpot 'rm -f target/app.js*' enter C-l
-tmux send-keys -t penpot './scripts/watch' enter
+tmux new-window -t "$PENPOT_TMUX_SESSION:2" -n 'exporter'
+tmux select-window -t "$PENPOT_TMUX_SESSION:2"
+tmux send-keys -t "$PENPOT_TMUX_SESSION" 'cd penpot/exporter' enter C-l
+tmux send-keys -t "$PENPOT_TMUX_SESSION" 'rm -f target/app.js*' enter C-l
+tmux send-keys -t "$PENPOT_TMUX_SESSION" './scripts/watch' enter
 
-tmux split-window -v
-tmux send-keys -t penpot 'cd penpot/exporter' enter C-l
-tmux send-keys -t penpot './scripts/wait-and-start.sh' enter
+tmux split-window -v -t "$PENPOT_TMUX_SESSION"
+tmux send-keys -t "$PENPOT_TMUX_SESSION" 'cd penpot/exporter' enter C-l
+tmux send-keys -t "$PENPOT_TMUX_SESSION" './scripts/wait-and-start.sh' enter
 
-tmux new-window -t penpot:3 -n 'backend'
-tmux select-window -t penpot:3
-tmux send-keys -t penpot 'cd penpot/backend' enter C-l
-tmux send-keys -t penpot './scripts/start-dev' enter
+tmux new-window -t "$PENPOT_TMUX_SESSION:3" -n 'backend'
+tmux select-window -t "$PENPOT_TMUX_SESSION:3"
+tmux send-keys -t "$PENPOT_TMUX_SESSION" 'cd penpot/backend' enter C-l
+tmux send-keys -t "$PENPOT_TMUX_SESSION" './scripts/start-dev' enter
 
 if echo "$PENPOT_FLAGS" | grep -q "enable-mcp"; then
     pushd ~/penpot/mcp/
@@ -47,10 +64,10 @@ if echo "$PENPOT_FLAGS" | grep -q "enable-mcp"; then
     pnpm run build;
     popd
 
-    tmux new-window -t penpot:4 -n 'mcp'
-    tmux select-window -t penpot:4
-    tmux send-keys -t penpot 'cd penpot/mcp' enter C-l
-    tmux send-keys -t penpot './scripts/start-mcp-devenv' enter
+    tmux new-window -t "$PENPOT_TMUX_SESSION:4" -n 'mcp'
+    tmux select-window -t "$PENPOT_TMUX_SESSION:4"
+    tmux send-keys -t "$PENPOT_TMUX_SESSION" 'cd penpot/mcp' enter C-l
+    tmux send-keys -t "$PENPOT_TMUX_SESSION" './scripts/start-mcp-devenv' enter
 fi
 
 if [ "${SERENA_ENABLED:-false}" = "true" ]; then
@@ -58,9 +75,9 @@ if [ "${SERENA_ENABLED:-false}" = "true" ]; then
         # update Serena (use sudo since the initial Serena installation is global; see Dockerfile)
         sudo -E uv tool install -p 3.13 serena-agent@${SERENA_UPDATE_VERSION} --prerelease=allow
     fi
-    tmux new-window -t penpot:5 -n 'serena'
-    tmux select-window -t penpot:5
-    tmux send-keys -t penpot "serena start-mcp-server --transport streamable-http --port 14281 --project penpot --context ${SERENA_CONTEXT} --host 0.0.0.0" enter
+    tmux new-window -t "$PENPOT_TMUX_SESSION:5" -n 'serena'
+    tmux select-window -t "$PENPOT_TMUX_SESSION:5"
+    tmux send-keys -t "$PENPOT_TMUX_SESSION" "serena start-mcp-server --transport streamable-http --port 14281 --project penpot --context ${SERENA_CONTEXT} --host 0.0.0.0" enter
 fi
 
-tmux -2 attach-session -t penpot
+attach_or_exit
diff --git a/docs/technical-guide/developer/agentic-devenv.md b/docs/technical-guide/developer/agentic-devenv.md
index 19940ccc00..ed362ce385 100644
--- a/docs/technical-guide/developer/agentic-devenv.md
+++ b/docs/technical-guide/developer/agentic-devenv.md
@@ -5,18 +5,73 @@ desc: Dive into agentic Penpot development.
 
 # Agentic Development Environment
 
-The agentic DevEnv is an extension of the standard DevEnv
-(the [general DevEnv instructions](/technical-guide/developer/devenv/) apply),
-which is optimised for AI agent-based development,
-adding additional tools and processes that support agentic automation.
+The agentic DevEnv is an extension of the standard DevEnv (the
+[general DevEnv instructions](/technical-guide/developer/devenv/) apply),
+optimised for AI agent-based development. It adds MCP servers (Penpot,
+Serena, Playwright) and supports a launcher that wires them into your AI client.
 
-The general workflow is as follows:
+Two things to know up front:
 
-1. Start the agentic DevEnv.
-2. Start a debugging-enabled browser and open Penpot, using a Penpot user with
-   the remote MCP integration enabled.
-3. Use an AI client (MCP client) which is connected to a suite of MCP servers
-   to solve development tasks.
+- **Parallel workspaces are first-class.** Run several devenv instances side
+  by side - one per AI agent if you like - each with its own source-tree
+  clone, ports, and tmux session. Pass `--ws N` to target one.
+- **Your existing AI-client config is preserved.** The launcher loads a
+  per-workspace MCP config on top of your global one.
+
+## Quick Start
+
+1. **Bring up one or more workspaces**[^cfg]:
+
+   ```bash
+   ./manage.sh run-devenv-agentic              # ws0 (the live repo)
+   ./manage.sh run-devenv-agentic --ws 1       # ws1 (sibling clone)
+   ```
+
+   Add `--ws 2`, `--ws 3`, … for more parallel workspaces.
+
+2. **Launch a browser with remote debugging enabled:**
+
+   For example, with Chrome:
+
+   ```bash
+   google-chrome --remote-debugging-port=9222 --user-data-dir="$HOME/.chrome-debug-profile"
+   ```
+
+3. **Open Penpot in that browser:**
+
+   - ws0: <https://localhost:3449>
+   - ws1: <https://localhost:13449>
+   - etc. (ports are offset by `10000 × N` for `wsN`)
+
+   On first login per account, open settings → Integrations and toggle
+   "MCP Server" on. The agentic DevEnv runs the MCP server in single-user
+   mode - the key and proxied URL shown in the UI are not needed.
+
+4. **Launch your AI client** against the workspace you want it to drive:
+
+   ```bash
+   ./manage.sh start-coding-agent claude              # ws0
+   ./manage.sh start-coding-agent claude --ws 1       # ws1
+   ```
+
+   Supported clients: `claude` | `opencode` | `vscode` | `codex`.
+5. **Attach to the tmux session** for the workspace (optional):
+
+   ```bash
+   ./manage.sh attach-devenv            # ws0
+   ./manage.sh attach-devenv --ws 1     # ws1
+   ```
+
+6. **Shut down workspaces** with `./manage.sh stop-devenv`, either one by one or all at once.
+   You cannot shut down `ws0` if any other workspace is still running, since it's the worker-bearer.
+   Shared infrastructure will be cleaned up when the last workspace is stopped.
+
+Optional: watch Serena's activity in its dashboard
+(<http://localhost:14182> for ws0, <http://localhost:24182> for ws1, etc.).
+
+[^cfg]: One-time, if you don't already have it: set
+`penpotFlags = "enable-mcp"` in `frontend/resources/public/js/config.js`
+(gitignored; create if missing).
 
 ## Capabilities
 
@@ -32,7 +87,6 @@ with a comprehensive toolbox for Penpot development:
 * **Serena MCP Server** provides code intelligence tools with support for Clojure and TypeScript.
   Its memory system is used to organise project knowledge in a context-efficient manner.
 * **Playwright MCP Server** provides tools for browser remote control.
-* (optional) **GitHub MCP Server** provides tools for interacting with GitHub (issue, PRs, etc.)
 
 Equipped with the tools provided by these MCP servers, the agent can fully close the development loop,
 i.e. it can ...
@@ -47,122 +101,247 @@ i.e. it can ...
 * test the changes in the live Penpot instance, and
 * create commits and PRs resolving the issue.
 
-## Configuring and Starting the Agentic DevEnv
+## The flow in detail
 
-**First-Time Setup: Building the Image.** If you are starting the agentic DevEnv for the first time, you need to build
-the updated docker image, adding support for agentic tools:
+### First-time setup
 
-```bash
-./manage.sh build-devenv --local
-```
-
-**Enable the Penpot MCP Connection in the Frontend.**
-The agentic DevEnv relies on a connection between the Penpot frontend and the Penpot MCP server
-being established automatically.
-Edit the file `frontend/resources/public/js/config.js`,
-creating it if it does not exist, and make sure the `penpotFlags` variable contains the
-`enable-mcp` flag.
+**The MCP frontend flag.** Edit `frontend/resources/public/js/config.js`
+(create it if missing) and ensure `penpotFlags` contains `enable-mcp`:
 
 ```javascript
 var penpotFlags = "enable-mcp";
 ```
 
-**Running the DevEnv in Agentic Mode.** Start the DevEnv in agentic mode with:
+The file is gitignored and lives in the live repo only. On every
+`run-devenv-agentic` call it is read directly for ws0; for wsN (N ≥ 1) it is
+copied into the workspace clone on the **initial** sync only - subsequent
+`--sync` passes leave the workspace's copy alone so per-workspace
+customisations survive. `run-devenv-agentic` refuses to start if the file is
+missing.
 
-```bash
-./manage.sh run-devenv-agentic
-```
-
-## Opening Penpot with Remote Debugging & MCP Enabled
-
-**Enable Remote Debugging in Your Browser.**
-Penpot needs to be opened in a browser that has remote debugging enabled.
-In Chromium-based browsers (such as Google Chrome, Opera, Vivaldi, etc.),
-this can be achieved by launching the browser with the `--remote-debugging-port` argument.
-For most newer browsers, you will also need to specify a user data directory,
-as using debugging with your regular browser profile is disallowed for security reasons.
+**Browser remote debugging.** The Playwright MCP server drives a real
+browser instance over the Chrome DevTools protocol. To enable it, launch a
+Chromium-based browser (Chrome, Vivaldi, Opera, …) with the
+`--remote-debugging-port` flag and a separate user-data directory:
 
 ```bash
 google-chrome --remote-debugging-port=9222 --user-data-dir="$HOME/.chrome-debug-profile"
 ```
 
-This enables the Playwright MCP server to connect to the browser and control it.
-Verify that debugging was enabled correctly by navigating to `http://127.0.0.1:9222/json/version`.
-If you change the port, adjust the MCP server configuration accordingly (see below).
-Note: For security reasons, you should not enable remote debugging with a profile
-that you use for regular browsing activities.
+Verify it works by visiting `http://127.0.0.1:9222/json/version`. If you
+change the port, update the Playwright MCP entry in `.devenv/shared/*.json`
+accordingly. For security reasons, do not enable remote debugging on the
+profile you use for regular browsing.
 
-**Open Penpot with the MCP Integration Enabled.**
-The Penpot instance in the DevEnv can be accessed at [https://localhost:3449](https://localhost:3449).
-Once logged in, navigate to your account settings, click on "Integrations" in the sidebar, and enable the "MCP Server" toggle.
-Note: You do not need to use the generated key (or the provided URL), as the MCP server in the agentic DevEnv is running in single-user mode and does not require authentication.
+**Enable the MCP integration in Penpot.** The Penpot UI has a per-account
+MCP toggle. After logging into your Penpot instance at
+[https://localhost:3449](https://localhost:3449), open account settings,
+click "Integrations" in the sidebar, and enable the "MCP Server" toggle.
+The agentic DevEnv runs the MCP server in single-user mode, so the
+generated key and proxied URL printed in the UI are *not* needed - only the
+toggle itself matters.
 
-## Configuring Your AI Client
+**(Optional) custom devenv image.** Only needed if you want to modify the
+devenv image itself (add a tool, change a base layer):
 
-Your AI client needs to be configured to connect to the MCP servers that collectively provide the agent with the necessary tools for Penpot development.
+```bash
+./manage.sh build-devenv --local
+```
 
-Below, we exemplarily provide a JSON-based configuration snippet, using `mcp-remote` to wrap HTTP-based servers.
+The default `run-devenv-agentic` flow pulls the published image
+automatically, so regular users never run this.
 
-Most clients using JSON-based configuration (e.g. Copilot, JetBrains AI Assistant, Claude Desktop, Antigravity)
-will work when inserting the server entries below into the client's configuration file.
-If your client uses a different configuration format, extract the relevant information (i.e. server URLs or launch commands)
-and configure the servers appropriately, referring to the documentation of your client.
+### Bringing up workspaces
+
+```bash
+./manage.sh run-devenv-agentic \
+    [--ws N] [--sync] [--serena-context CTX] \
+    [--git-user-name NAME] [--git-user-email EMAIL]
+```
+
+Brings one agentic instance up. Errors out if the target is already running.
+
+`--ws N` (N ≥ 1) auto-starts ws0 first if it is not already up - ws0 is the
+worker-bearer and must be running whenever any wsN is. Per-instance ports
+are offset by `10000 × N` (ws1's MCP at `http://localhost:14401/mcp`, Serena
+MCP at `http://localhost:24181`, Serena dashboard at
+`http://localhost:24182`, etc.). `manage.sh` prints the full URL set on
+every bring-up so you don't compute offsets by hand. See the
+[Dev environment guide](./devenv.md) for the workspace lifecycle, `--sync`
+semantics, and stop ordering.
+
+**Git identity for agent commits.** Coding agents typically need to commit
+inside the devenv, so `run-devenv-agentic` wires a Git identity into the
+container's global config on every bring-up. By default it propagates the
+host's effective `git config user.{name,email}` (local repo override wins
+over `~/.gitconfig`, matching what `git commit` on the host would record).
+Override with `--git-user-name "Full Name"` / `--git-user-email
+you@example.com` when you want agent commits to carry an identity different
+from your normal one. Without either source the script warns and proceeds;
+commits inside the devenv will fail until you fix it. See the
+[Dev environment guide](./devenv.md#git-identity-inside-the-container) for
+the full mechanics.
+
+> **Note:** the MCP and Serena tmux windows are only added when the tmux
+> session is first created. If a workspace was already brought up with
+> `./manage.sh run-devenv` (non-agentic), stop it before re-running
+> agentically:
+>
+> ```bash
+> ./manage.sh stop-devenv
+> ./manage.sh run-devenv-agentic
+> ```
+
+### Launching an AI client
+
+The agentic environment supports any AI client, one just needs to set the right MCP config,
+see [manual configuration](#manual-ai-client-configuration) below. For some popular clients, the `manage.sh`
+CLI offers direct support through the following mechanism:
+
+Every `run-devenv-agentic` regenerates three MCP-client config files with
+the workspace's ports baked in; Codex is wired up at launch instead (see
+below):
+
+| Client | File | Loaded how |
+| ------ | ---- | ---------- |
+| Claude Code | `<workspace>/.devenv/mcp/claude-code.json` | `--mcp-config <file>` flag |
+| opencode | `<workspace>/.devenv/mcp/opencode.json` | `OPENCODE_CONFIG=<file>` env var |
+| VS Code Copilot | `<workspace>/.vscode/mcp.json` | Auto-discovered when opening the workspace |
+| Codex CLI | _(none written)_ | Injected as `-c mcp_servers.…` overrides by `start-coding-agent codex` |
+
+The files are committed templates + an `envsubst` pass; see
+[`.devenv/README.md`](../../../.devenv/README.md) for the full layout.
+
+`./manage.sh start-coding-agent <client> [--ws N] [...passthrough]`
+launches the chosen client against one workspace, `cd`'ing into the right
+directory and refusing to launch if the instance is not running:
+
+```bash
+./manage.sh start-coding-agent claude              # ws0
+./manage.sh start-coding-agent opencode --ws 1     # ws1
+./manage.sh start-coding-agent vscode              # opens VS Code on ws0
+./manage.sh start-coding-agent codex --ws 2        # ws2
+```
+
+A given AI client session drives **exactly one workspace**, so running N
+parallel workspaces typically means running N AI client sessions, each
+pointed at a different workspace's ports.
+
+What each launcher does:
+
+* **Claude Code** is started with `--mcp-config .devenv/mcp/claude-code.json`,
+  which is **additive** - your existing global Claude Code MCP entries stay
+  available alongside the three entries we ship (Penpot MCP, Serena MCP,
+  Playwright). To shadow one of our entries with a private one, install it
+  under Claude Code's local scope (`claude mcp add --scope local …`); local
+  wins over `--mcp-config`.
+* **opencode** is started with `OPENCODE_CONFIG=.devenv/mcp/opencode.json`.
+  opencode's precedence chain is *global → `OPENCODE_CONFIG` → project*, so
+  the file we generate **overrides** entries with the same name in your
+  global config. To override our entries in turn, drop a personal
+  `opencode.json` at the repo root - it's gitignored on purpose.
+* **VS Code Copilot** - `code "$workspace"` opens VS Code on the workspace.
+  Copilot loads both your user-profile MCP config and the workspace's
+  `.vscode/mcp.json`. That workspace file is **deep-merged** rather than
+  overwritten: on ws0 (where it *is* the live repo's own file) any servers you
+  added survive, and only our three (Penpot MCP, Serena MCP, Playwright) are
+  rewritten to the current ports; on ws1+ it is created from scratch. To shadow
+  one of ours, add a same-named entry in your user profile - it wins.
+* **Codex CLI** - `codex` is exec'd from the workspace dir with our servers
+  passed as `-c mcp_servers.<name>....` overrides built from the committed
+  templates. **Nothing is written to `.codex/config.toml`**, so your own
+  project- or user-level Codex config is left untouched (and no "trusted
+  project" prompt is involved for our servers). Because `-c` is Codex's
+  highest-precedence layer, our entries win over a same-named server in your
+  config; to override one, append your own `-c` after the client name
+  (`... start-coding-agent codex -- -c 'mcp_servers.penpot.url="…"'`) - the
+  later `-c` wins.
+
+## Manual AI-client configuration
+
+The `start-coding-agent` launcher covers Claude Code, opencode, VS Code
+Copilot, and the Codex CLI. For any other client (JetBrains AI Assistant,
+Claude Desktop, Antigravity, …), or if you prefer to wire things up
+yourself, configure the MCP servers in your client's native format using
+the URLs below.
+
+The Penpot and Serena URLs for the workspace you want to target are printed
+by `manage.sh` every time it brings an instance up; copy them straight from
+that output. The mechanical rule is `port = base + 10000 × N` for `wsN`,
+with bases `4401` (Penpot MCP) and `14181` (Serena MCP). Playwright is not
+workspace-scoped - it connects to your local browser, so the same entry
+works for every client.
+
+### Project-level MCP config files (Claude Code, opencode - manual path)
+
+If you'd rather not go through the launcher, both Claude Code and opencode
+support project-level MCP config files that **merge with** the developer's
+global config:
+
+* **Claude Code** reads `.mcp.json` at the project root. Local scope
+  (`claude mcp add --scope local …`) overrides project scope.
+* **opencode** reads `opencode.json` at the project root (or any ancestor
+  Git directory). Configs are merged in the order *global → `OPENCODE_CONFIG`
+  → project*.
+
+The schemas differ between the two, so a workspace supporting both ships
+both files. For multi-workspace work, edit the port numbers in each
+workspace's copy once to match its offset.
+
+### Example configuration
+
+Below is a JSON-based configuration snippet in Claude Code's `mcpServers`
+schema, targeting `ws0` (main), using `mcp-remote` to wrap HTTP-based
+servers. To target a different workspace, substitute the Penpot MCP and
+Serena MCP URLs with the ones for that workspace.
+
+For clients using a different configuration format, extract the relevant
+information (server URLs or launch commands) and configure the servers
+appropriately, referring to your client's documentation.
 
 ```json
 {
   "mcpServers": {
-    "penpot": {
+    "penpot-ws0": {
       "command": "npx",
       "args": ["-y", "mcp-remote", "http://localhost:4401/mcp", "--allow-http" ]
     },
-    "serena-devenv": {
+    "serena-ws0-devenv": {
       "command": "npx",
-      "args": ["-y", "mcp-remote", "http://localhost:14281/mcp", "--allow-http"]
+      "args": ["-y", "mcp-remote", "http://localhost:14181/mcp", "--allow-http"]
     },
     "playwright": {
       "command": "npx",
       "args": ["@playwright/mcp@latest", "--cdp-endpoint=http://127.0.0.1:9222"]
-    },
-    "github": {
-      "command": "npx",
-      "args": ["-y", "@modelcontextprotocol/server-github"],
-      "env": {
-        "GITHUB_PERSONAL_ACCESS_TOKEN": "TODO_your_token"
-      }
     }
   }
 }
 ```
 
 **Penpot MCP Server**
-* The URL above connects directly to the server in the DevEnv, which runs in single-user mode.
-  You do not need to use the proxied URL or the user token that is provided by the Penpot UI.
+* The URL above connects directly to the server in the DevEnv, which runs
+  in single-user mode. You do not need to use the proxied URL or the user
+  token that is provided by the Penpot UI.
 
 **Serena MCP Server**
-* You can access Serena's dashboard at [http://localhost:14282](http://localhost:14282)
-
-**GitHub MCP Server**
-* The use of this MCP server is optional. (Direct shell access to GitHub CLI can be used alternatively.)
-* You need to provide a personal access token (PAT) with appropriate permissions:
-  * Create a token in your GitHub account settings [here](https://github.com/settings/personal-access-tokens).
-  * Choose the right resource owner: As a member of the `penpot` organisation, be sure to create a token where the resource owner is the organisation.
-    Otherwise, you will not be able to create pull requests or issues in the `penpot/penpot` repository.
-  * Grant the necessary permissions, e.g. read and write access to issues and pull requests.
+* The matching Serena dashboard lives on the next port (`14182` for ws0,
+  `24182` for ws1, …) and is also printed by `manage.sh` on startup.
 
 ## Working on Development Tasks
 
-After having made the configuration changes, restart your AI client.
-All four MCP servers should now be running and accessible to your client.
+After having made the configuration changes, restart your AI client. The
+configured MCP servers should now be running and accessible to your client.
 
-The agent's entrypoint for development is an activation of the `penpot` project with Serena.
-Start by instructing your agent as follows,
+The agent's entrypoint for development is an activation of the `penpot`
+project with Serena. Start by instructing your agent as follows,
 
 > Activate project penpot.
 
-and it should retrieve fundamental project information,
-expecting further instructions on what to do.
+and it should retrieve fundamental project information, expecting further
+instructions on what to do.
 
-**Always start your first prompt with these activation instructions**, as this bootstraps the agent's context.
+**Always start your first prompt with these activation instructions**, as
+this bootstraps the agent's context.
 
 ### Checking MCP Server Operability
 
diff --git a/docs/technical-guide/developer/devenv.md b/docs/technical-guide/developer/devenv.md
index 0443466e03..88ae8db6ca 100644
--- a/docs/technical-guide/developer/devenv.md
+++ b/docs/technical-guide/developer/devenv.md
@@ -45,13 +45,153 @@ This is an incomplete list of devenv related subcommands found on
 manage.sh script:
 
 ```bash
-./manage.sh build-devenv-local # builds the local devenv docker image (called by run-devenv automatically when needed)
-./manage.sh start-devenv       # starts background running containers
-./manage.sh run-devenv         # enters to new tmux session inside of one of the running containers
-./manage.sh stop-devenv        # stops background running containers
-./manage.sh drop-devenv        # removes all the containers, volumes and networks used by the devenv
+./manage.sh build-devenv --local # builds the local devenv docker image
+./manage.sh start-devenv         # brings up the shared infra + ws0 in background
+./manage.sh run-devenv           # ws0 with non-agentic tmux, attached (legacy alias)
+./manage.sh run-devenv-agentic   # one agentic instance; --ws to target ws1+; see below
+./manage.sh attach-devenv        # re-attaches to the tmux session of a running instance
+./manage.sh stop-devenv          # stops one instance (or --all); infra stops with the last
+./manage.sh drop-devenv          # removes containers (data volumes preserved)
 ```
 
+### Parallel workspaces
+
+The devenv runs as separate compose projects: shared infra (`penpotdev-infra`:
+Postgres, MinIO, mailer, LDAP) plus one `penpotdev-wsN` project per runtime
+instance. `ws0` (a.k.a. `main`) binds the live repo; `ws1+` bind clones the
+developer maintains explicitly under `${PENPOT_WORKSPACES_DIR}/wsN/`
+(default `~/.penpot/penpot_workspaces/`).
+
+Each call to `run-devenv-agentic` brings up one instance, and ws0 is always
+running whenever any ws1+ is — `--ws N` (N≥1) auto-starts ws0 first if it
+isn't already up:
+
+```bash
+./manage.sh run-devenv-agentic           # main (ws0)
+./manage.sh run-devenv-agentic --ws 1    # ws0 if needed, then ws1
+./manage.sh run-devenv-agentic --ws 2 --sync   # ws2, re-seeding from the live repo
+```
+
+Starting an instance that is already running is an error. `--sync` is only
+valid for `ws1+`; on ws0 it errors out. When a `ws1+` workspace directory
+does not exist yet, the first start syncs it implicitly from the live repo.
+Otherwise the workspace contents are left untouched unless `--sync` is passed
+again. Live-repo Git in a fragile state (rebase / merge / cherry-pick /
+`index.lock`) blocks all syncs.
+
+`frontend/resources/public/js/config.js` (which is gitignored and configures
+the frontend's MCP flag) is copied into each workspace on its initial sync
+only. After that the developer maintains it in each workspace; subsequent
+`--sync` runs leave the workspace copy alone.
+
+Stopping mirrors the start invariant — ws0 is the last to stop, and shared
+infra stops with it:
+
+```bash
+./manage.sh stop-devenv --ws 1           # stops ws1; ws0 + infra stay up
+./manage.sh stop-devenv                  # stops ws0 + infra; errors if ws1+ still running
+./manage.sh stop-devenv --all            # stops every ws1+ first, then ws0 + infra
+```
+
+Host ports are offset by `10000 × N`:
+
+| Service | ws0 | ws1 | ws2 |
+|---|---|---|---|
+| Penpot UI (HTTPS) | `https://localhost:3449` | `https://localhost:13449` | `https://localhost:23449` |
+| MCP HTTP stream | `http://localhost:4401/mcp` | `http://localhost:14401/mcp` | `http://localhost:24401/mcp` |
+| Serena MCP | `http://localhost:14181` | `http://localhost:24181` | `http://localhost:34181` |
+
+Container-internal ports stay fixed. Target a specific instance with
+`--ws N` on `attach-devenv`, `run-devenv-agentic`, `stop-devenv`,
+`start-coding-agent`, `run-devenv-shell`, and `isolated-shell`. `--ws`
+accepts a **non-negative integer only** — `--ws main` or `--ws ws1` is
+rejected, keeping the flag shape uniform across commands. `run-devenv` is
+ws0-only and takes no workspace flag. `run-devenv-agentic` also accepts
+`--serena-context CTX` and `--git-user-name NAME` / `--git-user-email
+EMAIL` (see below).
+
+Configuration lives in one tracked file, `docker/devenv/defaults.env` (the
+ws0 baseline); `ws1+` values (offset ports, `wsN` container/volume names) are
+derived and injected automatically, so there is no per-instance file to edit.
+
+### Git identity inside the container
+
+`run-devenv-agentic` wires a Git author identity into the container's
+**global** git config (`git config --global user.{name,email}`) so commits
+made from inside the devenv carry a real author/committer. Without this,
+the container would commit as the unconfigured `penpot@<container>`
+fallback — usable but useless for review.
+
+The values come from `--git-user-name NAME` / `--git-user-email EMAIL`
+when passed, or from your host's effective `git config user.{name,email}`
+otherwise. "Effective" here means the values plain `git config user.X`
+returns at the working directory `manage.sh` is invoked from — local
+(`<repo>/.git/config`) overrides global (`~/.gitconfig`), matching what
+`git commit` on the host would record. If neither is available the script
+prints a warning and continues — commits will fail inside the container
+until you set an identity. The values are applied every time
+`run-devenv-agentic` brings an instance up (idempotent), so re-running
+with different flags is the way to change the in-container identity.
+
+### Shared state and workers
+
+All instances share one Penpot database and one MinIO bucket; users, teams,
+files, and MCP tokens are visible from every instance. Per-instance Valkey
+keeps msgbus Pub/Sub channels (collab broadcasts, team-org notifications,
+file-summary cache, rate-limit counters) isolated.
+
+Background workers (`enable-backend-worker`) run only on ws0 — ws1+ overlays
+disable it. ws1+ RPC handlers still enqueue tasks into the shared Postgres
+`task` table; ws0's dispatcher claims them via `FOR UPDATE SKIP LOCKED` and
+runs them against the shared DB and MinIO. The "ws0 always up when ws1+ is
+up" invariant exists for this reason: it keeps a single worker-bearer and
+avoids the multi-instance cron-dedup race (the lock on `scheduled_task` is
+released when the task body finishes, so two cron timers firing the same
+scheduled instant with a gap larger than the body's runtime can both
+execute it).
+
+### Upgrading from a pre-parallel devenv
+
+The devenv compose configuration has been split into two files and reorganized
+into separate compose projects per runtime instance:
+
+- `docker/devenv/docker-compose.infra.yml` (Postgres, MinIO, mailer, LDAP)
+  runs under the compose project `penpotdev-infra`.
+- `docker/devenv/docker-compose.main.yml` (one main container + its Valkey)
+  runs once per runtime instance under `penpotdev-ws0`, `penpotdev-ws1`, ….
+- Both projects join the external Docker network `penpot_shared`, created
+  idempotently by `manage.sh`.
+- Configuration lives in `docker/devenv/defaults.env` (the ws0 baseline);
+  ws1+ overrides are computed and injected at compose time.
+
+If you had the devenv running on the previous single-project (`penpotdev`)
+layout, leftover containers and the auto-generated `penpotdev_default`
+network must be removed before bringing the new ws0 instance up. The named
+data volumes (`penpotdev_postgres_data_pg16`, `penpotdev_minio_data`,
+`penpotdev_user_data`, `penpotdev_valkey_data`) are pinned by explicit
+`name:` entries in the new compose files and are preserved through the
+transition — your Postgres DB, MinIO objects, and home cache survive.
+
+One-time cleanup, then bring up ws0:
+
+```bash
+# Stop and remove the old single-project containers (data volumes stay).
+docker stop penpot-devenv-main penpot-devenv-valkey 2>/dev/null
+docker rm   penpotdev-postgres-1 penpotdev-minio-1 penpotdev-minio-setup-1 \
+            penpotdev-mailer-1   penpotdev-ldap-1 \
+            penpot-devenv-main   penpot-devenv-valkey 2>/dev/null
+
+# Remove the orphaned auto-generated network.
+docker network rm penpotdev_default 2>/dev/null
+
+# Bring up infra + ws0 under the new project layout.
+./manage.sh run-devenv-agentic
+```
+
+After the cleanup, normal `./manage.sh start-devenv` / `run-devenv` /
+`run-devenv-agentic` commands work against the new layout. The legacy
+`penpotdev` compose project is no longer used.
+
 Having the container running and tmux opened inside the container,
 you are free to execute commands and open as many shells as you want.
 
diff --git a/exporter/scripts/run b/exporter/scripts/run
index 4bb272fc6a..a7f8836f74 100755
--- a/exporter/scripts/run
+++ b/exporter/scripts/run
@@ -3,4 +3,8 @@
 SCRIPT_DIR=$(dirname $0);
 source $SCRIPT_DIR/../../backend/scripts/_env;
 
+if [ -f $SCRIPT_DIR/../../backend/scripts/_env.local ]; then
+    source $SCRIPT_DIR/../../backend/scripts/_env.local;
+fi
+
 exec node target/app.js
diff --git a/exporter/scripts/wait-and-start.sh b/exporter/scripts/wait-and-start.sh
index f9638eb06d..53d1bc73f0 100755
--- a/exporter/scripts/wait-and-start.sh
+++ b/exporter/scripts/wait-and-start.sh
@@ -3,6 +3,10 @@
 SCRIPT_DIR=$(dirname $0);
 source $SCRIPT_DIR/../../backend/scripts/_env;
 
+if [ -f $SCRIPT_DIR/../../backend/scripts/_env.local ]; then
+    source $SCRIPT_DIR/../../backend/scripts/_env.local;
+fi
+
 bb -i '(babashka.wait/wait-for-port "localhost" 9630)';
 bb -i '(babashka.wait/wait-for-path "target/app.js")';
 sleep 2;
diff --git a/frontend/shadow-cljs.edn b/frontend/shadow-cljs.edn
index fadcb4131f..4b2dea2b38 100644
--- a/frontend/shadow-cljs.edn
+++ b/frontend/shadow-cljs.edn
@@ -9,8 +9,14 @@
   {:target :esm
    :output-dir "resources/public/js/"
    :asset-path "/js"
-   :devtools {:watch-dir "resources/public"
-              :reload-strategy :full}
+   ;; :devtools is dev-only, so it lives under :dev -- shadow merges that map
+   ;; for `watch`/`compile` but not `release`, keeping :devtools-url out of
+   ;; release entirely (shadow spec-checks it as non-empty-string? whenever the
+   ;; key is present, even in release). In the devenv SHADOW_SERVER_URL is
+   ;; always set per workspace (see defaults.env / manage.sh).
+   :dev {:devtools {:watch-dir "resources/public"
+                    :reload-strategy :full
+                    :devtools-url #shadow/env ["SHADOW_SERVER_URL" :default ""]}}
    :build-options {:manifest-name "manifest.json"}
    :modules
    {:shared
@@ -86,9 +92,11 @@
   {:target :browser
    :output-dir "resources/public/js/worker/"
    :asset-path "/js/worker"
-   :devtools {:browser-inject :main
-              :watch-dir "resources/public"
-              :reload-strategy :full}
+   ;; Dev-only; see the :main build above for why :devtools lives under :dev.
+   :dev {:devtools {:devtools-url #shadow/env ["SHADOW_SERVER_URL" :default ""]
+                    :browser-inject :main
+                    :watch-dir "resources/public"
+                    :reload-strategy :full}}
    :build-options {:manifest-name "manifest.json"}
    :modules
    {:main
diff --git a/manage.sh b/manage.sh
index 96581325db..38c5edc415 100755
--- a/manage.sh
+++ b/manage.sh
@@ -2,7 +2,56 @@
 
 export ORGANIZATION="penpotapp";
 export DEVENV_IMGNAME="$ORGANIZATION/devenv";
-export DEVENV_PNAME="penpotdev";
+export DEVENV_NETWORK="penpot_shared";
+export DEVENV_DEFAULTS_FILE="docker/devenv/defaults.env";
+
+# Load instance configuration (project name, container names, ports, runtime
+# config). Single source of truth for the devenv; consumed by both docker
+# compose (via --env-file) and the shell logic below. Hard dependency — abort
+# loudly if it's missing or unreadable.
+#
+# Host-shell env wins over file values: a value already set in the parent
+# environment is preserved. This matches docker compose's own precedence rule
+# for --env-file (so substitution-time and shell-time agree).
+if [ ! -r "$DEVENV_DEFAULTS_FILE" ]; then
+    echo "manage.sh: cannot read $DEVENV_DEFAULTS_FILE" >&2
+    exit 1
+fi
+while IFS='=' read -r __key __value; do
+    [[ -z "$__key" || "$__key" =~ ^[[:space:]]*# ]] && continue
+    if [ -z "${!__key+x}" ]; then
+        export "$__key=$__value"
+    fi
+done < "$DEVENV_DEFAULTS_FILE"
+unset __key __value
+
+# Source path for the workspace bind mount; consumed by docker-compose.main.yml.
+# ws0 binds the live repo at $PWD; ws1+ override this in their overlay env file.
+export PENPOT_SOURCE_PATH="${PENPOT_SOURCE_PATH:-$PWD}"
+
+# Base directory under which non-main workspace clones live (one subdir per
+# wsN, N>=1). Documented in defaults.env; default lives here so $HOME expands.
+export PENPOT_WORKSPACES_DIR="${PENPOT_WORKSPACES_DIR:-$HOME/.penpot/penpot_workspaces}"
+
+# Port allocation for parallel instances. Each wsN reserves a stride-wide port
+# block starting at N*stride; ws0 sits at offset 0, so a per-service base port
+# IS ws0's published port. To keep a single source of truth, the bases are
+# derived from the ws0 values sourced from defaults.env above rather than
+# duplicated here -- this makes it impossible for ws0's compose substitution and
+# the ws1+ offset arithmetic to drift apart. `:?` aborts loudly if defaults.env
+# is missing one. Consumed by instance-env-overrides (the values injected into
+# the per-instance compose env) and print-instance-info (the startup URLs).
+PENPOT_INSTANCE_PORT_STRIDE=10000
+PENPOT_PORT_BASE_PUBLIC=${PENPOT_PUBLIC_HTTP_PORT:?missing in defaults.env}
+PENPOT_PORT_BASE_MCP=${PENPOT_MCP_SERVER_PORT:?missing in defaults.env}
+PENPOT_PORT_BASE_MCP_REPL=${PENPOT_MCP_REPL_PORT:?missing in defaults.env}
+PENPOT_PORT_BASE_SERENA=${SERENA_EXTERNAL_PORT:?missing in defaults.env}
+PENPOT_PORT_BASE_SERENA_DASHBOARD=${SERENA_DASHBOARD_EXTERNAL_PORT:?missing in defaults.env}
+
+# Per-instance values like PENPOT_REDIS_URI must live in each instance's env
+# file (not in this shell), because docker compose's --env-file mechanism
+# lets a per-instance overlay override the baseline while the shell env
+# would otherwise shadow both for every project.
 
 export CURRENT_USER_ID=$(id -u);
 export CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD);
@@ -17,6 +66,50 @@ export JAVA_OPTS=${JAVA_OPTS:-"-Xmx1000m -Xms50m"};
 
 set -e
 
+# ----------------------------------------------------------------------------
+# Function map
+#
+# Utility helpers
+#   print-current-version, setup-buildx, put-license-file
+#
+# Devenv image lifecycle
+#   build-devenv, pull-devenv, pull-devenv-if-not-exists
+#
+# Devenv compose plumbing (used by every *-devenv command below)
+#   ensure-devenv-network   create the external 'penpot_shared' network
+#   infra-compose           wrap 'docker compose' for the shared-infra project
+#   instance-compose        wrap 'docker compose' for one instance's main
+#                           project, injecting that instance's overrides
+#   instance-env-overrides  the per-instance KEY=VALUE overrides (ws1+)
+#   devenv-main-container   resolve the 'main' container id via compose ps
+#   devenv-main-running     true if 'main' is up
+#
+# Devenv lifecycle (operate on the whole compose project)
+#   start-devenv, create-devenv, stop-devenv, drop-devenv, log-devenv
+#
+# Devenv interactive entry points (all operate on the running 'main' container)
+#   run-devenv-tmux         starts 'main' if needed and execs start-tmux.sh
+#                           interactively (this is what 'run-devenv' resolves to)
+#   run-devenv-agentic      same as run-devenv-tmux but enables MCP + Serena;
+#                           also regenerates .devenv/mcp/<tool>.json for the
+#                           target workspace (via write-instance-mcp-configs)
+#   attach-devenv           pure attach to the existing tmux session; fails
+#                           fast if the devenv or session is missing
+#   start-coding-agent      launches Claude Code or opencode against the
+#                           current workspace's generated MCP config
+#   run-devenv-shell        starts 'main' if needed and execs a bash shell
+#   run-devenv-isolated-shell  one-shot 'docker run' (NOT compose) against the
+#                           project user_data volume and the current PWD; used
+#                           for ad-hoc operations that should not touch a
+#                           running devenv
+#
+# Production build pipeline
+#   build                   one-shot 'docker run' that invokes a per-module
+#                           build script inside the devenv image
+#   build-<mod>-bundle      project a module's build output into ./bundles/
+#   build-<mod>-docker-image  package a bundle into a release docker image
+# ----------------------------------------------------------------------------
+
 ARCH=$(uname -m)
 
 if [[ "$ARCH" == "x86_64" || "$ARCH" == "amd64" || "$ARCH" == "i386" || "$ARCH" == "i686" ]]; then
@@ -80,31 +173,434 @@ function pull-devenv-if-not-exists {
     fi
 }
 
+function ensure-devenv-network {
+    docker network inspect "$DEVENV_NETWORK" >/dev/null 2>&1 || docker network create "$DEVENV_NETWORK" >/dev/null
+}
+
+# Compose-project plumbing for the parallel-workspaces layout.
+#
+# - Shared infrastructure (postgres, minio, mailer, ldap, minio-setup) runs
+#   under project `penpotdev-infra`.
+# - Each runtime instance (ws0, ws1, ...) runs its own main + valkey under
+#   project `penpotdev-wsN`. ws0 uses the `defaults.env` baseline as-is; ws1+
+#   override the per-instance values by injecting them as environment
+#   variables -- see instance-env-overrides (no files are written).
+# `env -i` strips the ambient shell before invoking docker compose, then we
+# re-inject exactly what compose needs. The stripping matters because
+# defaults.env is sourced into manage.sh's own shell at startup, so otherwise
+# those stale values would leak into substitution. And because Docker Compose
+# gives shell-env precedence over --env-file, the re-injected per-instance
+# overrides cleanly override the defaults.env baseline. Re-injected: HOME/PATH
+# (tooling), CURRENT_USER_ID/PENPOT_SOURCE_PATH (always per-call), and for ws1+
+# the instance-env-overrides block.
+function infra-compose {
+    env -i HOME="$HOME" PATH="$PATH" PWD="$PWD" \
+        docker compose -p penpotdev-infra \
+            --env-file "$DEVENV_DEFAULTS_FILE" \
+            -f docker/devenv/docker-compose.infra.yml \
+            "$@"
+}
+
+function instance-compose {
+    local instance="$1"; shift
+    local source_path
+    local -a overrides=()
+    if [[ "$instance" == "ws0" ]]; then
+        source_path="$PWD"
+    else
+        source_path="$(workspace-path "$instance")"
+        mapfile -t overrides < <(instance-env-overrides "$instance")
+    fi
+    env -i HOME="$HOME" PATH="$PATH" PWD="$PWD" \
+        CURRENT_USER_ID="${CURRENT_USER_ID:-$(id -u)}" \
+        PENPOT_SOURCE_PATH="$source_path" \
+        "${overrides[@]}" \
+        docker compose -p "penpotdev-${instance}" \
+            --env-file "$DEVENV_DEFAULTS_FILE" \
+            -f docker/devenv/docker-compose.main.yml \
+            "$@"
+}
+
+# Names of currently-running parallel instances (ws0, ws1, ...).
+function list-running-instances {
+    docker ps --format '{{.Label "com.docker.compose.project"}}' 2>/dev/null \
+        | sort -u \
+        | grep -oE '^penpotdev-ws[0-9]+$' \
+        | sed 's/^penpotdev-//' \
+        || true
+}
+
+function devenv-main-container {
+    local instance="${1:-ws0}"
+    # For ws1+, skip compose if the workspace clone doesn't exist yet — the
+    # instance has never been set up, so there is no container to find.
+    if [[ "$instance" != "ws0" && ! -d "$(workspace-path "$instance")" ]]; then
+        return 0
+    fi
+    instance-compose "$instance" ps -q main 2>/dev/null
+}
+
+function devenv-main-running {
+    local instance="${1:-ws0}"
+    local container
+    container=$(devenv-main-container "$instance")
+    [[ -n "$container" ]] && [[ "$(docker inspect -f '{{.State.Running}}' "$container" 2>/dev/null)" = "true" ]]
+}
+
+# Bring shared infra up and block until minio-setup has provisioned the
+# shared MinIO user/policy. Idempotent: a second call when everything is
+# already up returns immediately.
+function ensure-infra-up {
+    infra-compose up -d
+    local setup_container
+    setup_container=$(infra-compose ps -aq minio-setup 2>/dev/null)
+    if [[ -n "$setup_container" ]]; then
+        docker wait "$setup_container" >/dev/null 2>&1 || true
+    fi
+}
+
+# Refuse to sync workspaces if the live repo is in a fragile Git state.
+# Copying a partial rebase/merge/cherry-pick into all workspaces would leave
+# every instance in the same broken state.
+function assert-clean-git-state {
+    local fragile=""
+    [ -d .git/rebase-apply ] && fragile="$fragile rebase-apply"
+    [ -d .git/rebase-merge ] && fragile="$fragile rebase-merge"
+    [ -f .git/MERGE_HEAD ]    && fragile="$fragile merge"
+    [ -f .git/CHERRY_PICK_HEAD ] && fragile="$fragile cherry-pick"
+    [ -f .git/index.lock ]    && fragile="$fragile index.lock"
+    if [[ -n "$fragile" ]]; then
+        echo "Live repo Git state is unsafe to copy into workspaces:$fragile" >&2
+        echo "Finish or abort the in-progress operation, then retry." >&2
+        return 1
+    fi
+}
+
+# Absolute path of the workspace directory for a non-ws0 instance.
+function workspace-path {
+    local instance="$1"
+    echo "${PENPOT_WORKSPACES_DIR}/${instance}"
+}
+
+# Echo the host port that <base> maps to for <instance>.
+function instance-port {
+    local instance="$1"
+    local base="$2"
+    local n=0
+    [[ "$instance" =~ ^ws([0-9]+)$ ]] && n="${BASH_REMATCH[1]}"
+    echo $(( base + n * PENPOT_INSTANCE_PORT_STRIDE ))
+}
+
+# Echo the per-instance Compose variable overrides for a ws1+ instance, one
+# KEY=VALUE per line, for instance-compose to inject into its `env -i` line.
+# Compose gives shell-env precedence over --env-file, so these override the
+# defaults.env baseline. Every value is a pure function of the instance number,
+# so nothing is persisted: they are recomputed on every compose invocation and
+# can never drift from this logic. ws0 has no overrides (it uses defaults.env
+# as-is) and is never passed here.
+#
+# Omitted on purpose: COMPOSE_PROJECT_NAME (set via compose's -p flag),
+# PENPOT_SOURCE_PATH (injected directly by instance-compose), and
+function instance-env-overrides {
+    local instance="$1"
+    local public mcp mcp_repl serena serena_dash
+    public=$(instance-port "$instance" "$PENPOT_PORT_BASE_PUBLIC")
+    mcp=$(instance-port "$instance" "$PENPOT_PORT_BASE_MCP")
+    mcp_repl=$(instance-port "$instance" "$PENPOT_PORT_BASE_MCP_REPL")
+    serena=$(instance-port "$instance" "$PENPOT_PORT_BASE_SERENA")
+    serena_dash=$(instance-port "$instance" "$PENPOT_PORT_BASE_SERENA_DASHBOARD")
+    printf '%s\n' \
+        "PENPOT_MAIN_CONTAINER_NAME=penpot-devenv-${instance}-main" \
+        "PENPOT_VALKEY_CONTAINER_NAME=penpot-devenv-${instance}-valkey" \
+        "PENPOT_VALKEY_HOSTNAME=penpot-devenv-${instance}-valkey" \
+        "PENPOT_USER_DATA_VOLUME=penpotdev_${instance}_user_data" \
+        "PENPOT_VALKEY_DATA_VOLUME=penpotdev_${instance}_valkey_data" \
+        "PENPOT_PUBLIC_URI=https://localhost:${public}" \
+        "PENPOT_REDIS_URI=redis://penpot-devenv-${instance}-valkey/0" \
+        "PENPOT_PUBLIC_HTTP_PORT=${public}" \
+        "PENPOT_MCP_SERVER_PORT=${mcp}" \
+        "PENPOT_MCP_REPL_PORT=${mcp_repl}" \
+        "SERENA_EXTERNAL_PORT=${serena}" \
+        "SERENA_DASHBOARD_EXTERNAL_PORT=${serena_dash}" \
+        "PENPOT_BACKEND_WORKER=false" \
+        "SHADOW_SERVER_URL=wss://localhost:${public}"
+}
+
+# Thin wrapper around .devenv/scripts/merge-mcp-config.py for the JSON clients
+# (Claude Code, opencode, VS Code). The script does the actual envsubst + JSON
+# deep-merge; see its docstring for the contract. ${PENPOT_MCP_PORT} /
+# ${SERENA_MCP_PORT} placeholders in the template are resolved from the
+# caller's environment. Any extra flags (e.g. --merge-into-existing for the VS
+# Code output) are forwarded verbatim.
+#
+# Codex deliberately has no wrapper here: it cannot load an MCP config from an
+# arbitrary file path, so instead of writing a file we inject our servers as
+# `-c` overrides built at launch time -- see start-coding-agent.
+function _merge-mcp-config-json {
+    local shared="$1" tpl="$2" out="$3" key="$4"; shift 4
+    python3 .devenv/scripts/merge-mcp-config.py \
+        --format json --key "$key" "$@" \
+        "$shared" "$tpl" "$out"
+}
+
+# Generate the per-workspace AI-client MCP config files by merging the
+# committed .devenv/shared/<tool>.* with the port-substituted
+# .devenv/templates/<tool>.*. Developers who want to override entries should
+# use the client's own override mechanism: Claude Code's local scope, a
+# project-level opencode.json, a VS Code user-profile entry, or a user-level
+# ~/.codex/config.toml.
+#
+# Generated paths per tool:
+#   <workspace>/.devenv/mcp/claude-code.json   loaded via --mcp-config; clean
+#                                              overwrite (dedicated gitignored
+#                                              file, no developer content)
+#   <workspace>/.devenv/mcp/opencode.json      loaded via OPENCODE_CONFIG=; same
+#   <workspace>/.vscode/mcp.json               auto-loaded by VS Code Copilot;
+#                                              DEEP-MERGED into any existing file
+#                                              so a developer's own entries on
+#                                              ws0 survive (ws0's file IS the
+#                                              live repo's; ws1+ start fresh).
+#                                              Ours win on name collision.
+#
+# Codex is intentionally NOT generated here. It cannot load an MCP config from
+# an arbitrary path, and writing the auto-discovered .codex/config.toml would
+# clobber the developer's project-level Codex config on ws0. Instead its
+# servers are injected as `-c` overrides at launch -- see start-coding-agent.
+function write-instance-mcp-configs {
+    local instance="$1"
+    local workspace
+    if [[ "$instance" == "ws0" ]]; then
+        workspace="$PWD"
+    else
+        workspace=$(workspace-path "$instance")
+    fi
+
+    local src_dir="$workspace/.devenv"
+    if [[ ! -d "$src_dir/shared" || ! -d "$src_dir/templates" ]]; then
+        echo "[$instance] .devenv/shared or .devenv/templates missing under $workspace; skipping MCP config generation." >&2
+        return 0
+    fi
+
+    local mcp_dir="$src_dir/mcp"
+    mkdir -p "$mcp_dir" "$workspace/.vscode"
+
+    PENPOT_MCP_PORT=$(instance-port "$instance" "$PENPOT_PORT_BASE_MCP")
+    SERENA_MCP_PORT=$(instance-port "$instance" "$PENPOT_PORT_BASE_SERENA")
+    export PENPOT_MCP_PORT SERENA_MCP_PORT
+
+    _merge-mcp-config-json \
+        "$src_dir/shared/claude-code.json" \
+        "$src_dir/templates/claude-code.json" \
+        "$mcp_dir/claude-code.json" \
+        mcpServers
+    _merge-mcp-config-json \
+        "$src_dir/shared/opencode.json" \
+        "$src_dir/templates/opencode.json" \
+        "$mcp_dir/opencode.json" \
+        mcp
+    # VS Code's mcp.json is auto-discovered at a fixed path, so on ws0 it IS the
+    # developer's own project file -- deep-merge into it rather than overwriting.
+    # On ws1+ the path does not exist yet, so this writes it from scratch.
+    _merge-mcp-config-json \
+        "$src_dir/shared/vscode.json" \
+        "$src_dir/templates/vscode.json" \
+        "$workspace/.vscode/mcp.json" \
+        servers \
+        --merge-into-existing
+}
+
+# Seed (or re-seed) a workspace from the live repo, then switch it onto a
+# unique branch. Two-step sync:
+#   1. .git directory is rsync'd directly (so the workspace has its own
+#      clone with the developer's current commits / index).
+#   2. Working-tree files are enumerated by `git ls-files`, which is the
+#      only authoritative source for "what files belong in the working
+#      tree" (Git tracks files even when their parent directory matches
+#      a gitignore pattern, e.g. .clj-kondo/config.edn). Using rsync's
+#      gitignore filter directly misses those.
+# Gitignored caches already in the workspace (node_modules, target, etc.)
+# are left in place: no --delete on the working-tree pass.
+function sync-workspace {
+    local instance="$1"
+    if [[ "$instance" == "ws0" ]]; then
+        return 0
+    fi
+    assert-clean-git-state || return 1
+
+    local workspace
+    workspace=$(workspace-path "$instance")
+    mkdir -p "$workspace"
+
+    echo "[$instance] syncing workspace at $workspace ..."
+
+    # .git directory — direct mirror, including index, refs, hooks, etc.
+    rsync -a --delete "$PWD/.git/" "$workspace/.git/"
+
+    # Working-tree files: tracked + untracked-not-ignored. git ls-files
+    # speaks Git's actual semantics, including the "tracked overrides
+    # gitignore" rule. --files-from feeds the path list to rsync verbatim.
+    local files
+    files=$(mktemp)
+    git -C "$PWD" ls-files -z --cached --others --exclude-standard >"$files"
+    rsync -a --files-from="$files" --from0 "$PWD/" "$workspace/"
+    rm -f "$files"
+
+    # Initial seed of frontend/resources/public/js/config.js. The file is
+    # gitignored, so git ls-files would not list it, yet the agentic devenv
+    # needs it (enable-mcp flag). After the first sync the workspace copy
+    # belongs to the user — subsequent syncs leave it untouched.
+    local cfg="frontend/resources/public/js/config.js"
+    if [[ -f "$PWD/$cfg" && ! -f "$workspace/$cfg" ]]; then
+        install -D "$PWD/$cfg" "$workspace/$cfg"
+    fi
+
+    (
+        cd "$workspace"
+        git switch -C "${instance}/${CURRENT_BRANCH}" >/dev/null
+    )
+}
+
 function start-devenv {
     pull-devenv-if-not-exists $@;
+    ensure-devenv-network;
 
-    docker compose -p $DEVENV_PNAME -f docker/devenv/docker-compose.yaml up -d;
+    ensure-infra-up
+    instance-compose ws0 up -d
 }
 
 function create-devenv {
     pull-devenv-if-not-exists $@;
+    ensure-devenv-network;
 
-    docker compose -p $DEVENV_PNAME -f docker/devenv/docker-compose.yaml create;
+    infra-compose create
+    instance-compose ws0 create
 }
 
+# Stop instances. ws0 is the worker-bearer and must be the last one to stop;
+# shared infra is shut down together with ws0. Flags are mutually exclusive.
+#
+#   --ws N (N>=1)  stop just that workspace. Leaves ws0 and infra alone.
+#   --ws 0 | (no flag)  stop ws0 + shared infra. Refused if any ws1+ is running.
+#   --all          stop every wsN highest-first, then ws0, then infra.
 function stop-devenv {
-    docker compose -p $DEVENV_PNAME -f docker/devenv/docker-compose.yaml stop -t 2;
+    local target=""
+    local all=false
+    while [[ $# -gt 0 ]]; do
+        case "$1" in
+            --ws)
+                target="$(parse-ws-integer "$2")" || return 1; shift 2;;
+            --all)
+                all=true; shift;;
+            *)
+                echo "stop-devenv: unknown argument '$1'" >&2
+                return 1;;
+        esac
+    done
+    if [[ -n "$target" && "$all" == "true" ]]; then
+        echo "stop-devenv: --ws and --all are mutually exclusive." >&2
+        return 1
+    fi
+
+    local running ws
+    running=$(list-running-instances)
+
+    if [[ "$all" == "true" ]]; then
+        # Highest wsN first, then ws0, then infra. ws0 stop also brings infra.
+        for ws in $(printf '%s\n' $running | grep -v '^ws0$' | sed 's/^ws//' | sort -rn | sed 's/^/ws/'); do
+            stop-instance "$ws"
+        done
+        if printf '%s\n' $running | grep -qx ws0; then
+            stop-instance ws0
+        fi
+        infra-compose down -t 2
+        return 0
+    fi
+
+    # Default target: ws0 (which also stops infra).
+    [[ -z "$target" ]] && target="ws0"
+
+    if [[ "$target" == "ws0" ]]; then
+        local non_main=""
+        for ws in $running; do
+            [[ "$ws" != "ws0" ]] && non_main="$non_main $ws"
+        done
+        if [[ -n "$non_main" ]]; then
+            echo "stop-devenv: cannot stop ws0 while other instances are running:${non_main}." >&2
+            echo "Stop them first (--ws N) or use --all." >&2
+            return 1
+        fi
+        if printf '%s\n' $running | grep -qx ws0; then
+            stop-instance ws0
+        else
+            echo "[ws0] not running."
+        fi
+        infra-compose down -t 2
+        return 0
+    fi
+
+    # --ws N (N>=1): stop just that instance, leave ws0 + infra up.
+    if printf '%s\n' $running | grep -qx "$target"; then
+        stop-instance "$target"
+    else
+        echo "[$target] not running."
+    fi
 }
 
+# drop-devenv shares stop-devenv's CLI and invariants exactly; the only
+# difference is that on a full teardown it also removes the devenv image
+# (forcing the next bring-up to re-pull/rebuild). Single-workspace drops
+# keep the image because the rest of the workspaces still depend on it.
+#
+#   --ws N (N >= 1)  delegate to stop-devenv; image is kept.
+#   --ws 0 | (none)  delegate to stop-devenv; image is removed.
+#   --all            delegate to stop-devenv; image is removed.
 function drop-devenv {
-    docker compose -p $DEVENV_PNAME -f docker/devenv/docker-compose.yaml down -t 2 -v;
+    # Parse args ourselves to decide whether the image gets removed.
+    # stop-devenv then re-parses the same flags and runs the actual stop.
+    local target=""
+    local all=false
+    while [[ $# -gt 0 ]]; do
+        case "$1" in
+            --ws)
+                target="$(parse-ws-integer "$2")" || return 1; shift 2;;
+            --all)
+                all=true; shift;;
+            *)
+                echo "drop-devenv: unknown argument '$1'" >&2
+                return 1;;
+        esac
+    done
+    if [[ -n "$target" && "$all" == "true" ]]; then
+        echo "drop-devenv: --ws and --all are mutually exclusive." >&2
+        return 1
+    fi
 
-    echo "Clean old development image $DEVENV_IMGNAME..."
-    docker images $DEVENV_IMGNAME -q | awk '{print $3}' | xargs --no-run-if-empty docker rmi
+    local stop_args=()
+    [[ -n "$target" ]] && stop_args+=(--ws "${target#ws}")
+    [[ "$all" == "true" ]] && stop_args+=(--all)
+    stop-devenv "${stop_args[@]}" || return $?
+
+    # Image removal happens for the full-teardown paths only. A single-wsN
+    # (N >= 1) drop must keep the image since ws0 and any other wsN still
+    # rely on it.
+    if [[ -z "$target" || "$target" == "ws0" ]] || [[ "$all" == "true" ]]; then
+        echo "Clean old development image $DEVENV_IMGNAME..."
+        docker images $DEVENV_IMGNAME -q | xargs --no-run-if-empty docker rmi
+    fi
 }
 
 function log-devenv {
-    docker compose -p $DEVENV_PNAME -f docker/devenv/docker-compose.yaml logs -f --tail=50
+    local target="ws0"
+    while [[ $# -gt 0 ]]; do
+        case "$1" in
+            --ws)
+                target="$(parse-ws-integer "$2")" || return 1; shift 2;;
+            *)
+                echo "log-devenv: unknown argument '$1'" >&2
+                return 1;;
+        esac
+    done
+    instance-compose "$target" logs -f --tail=50
 }
 
 function run-devenv-tmux {
@@ -117,72 +613,496 @@ function run-devenv-tmux {
             -e*)
                 extra_env_args+=(-e "${1#-e}"); shift;;
             *)
-                shift;;
+                echo "run-devenv: unknown argument '$1'" >&2
+                return 1;;
         esac
     done
 
-    if [[ ! $(docker ps -f "name=penpot-devenv-main" -q) ]]; then
+    if ! devenv-main-running ws0; then
         start-devenv
         echo "Waiting for containers fully start (5s)..."
-        sleep 5;
+        sleep 5
     fi
 
+    local container
+    container=$(devenv-main-container ws0)
     docker exec -ti \
         "${extra_env_args[@]}" \
-        penpot-devenv-main sudo -EH -u penpot PENPOT_PLUGIN_DEV=$PENPOT_PLUGIN_DEV /home/start-tmux.sh
+        "$container" sudo -EH -u penpot PENPOT_PLUGIN_DEV=$PENPOT_PLUGIN_DEV /home/start-tmux.sh
+}
+
+# Strict parser for --ws values. Accepts a bare integer in the supported
+# range (0..PENPOT_MAX_WS_INDEX) and returns the canonical "wsN" form.
+# Anything else fails fast. The upper bound exists because the host ports
+# computed for higher N overflow the 16-bit TCP port range:
+#   port = base + N * PENPOT_INSTANCE_PORT_STRIDE (10000)
+# With the current Serena bases (14181/14182), N = 5 still fits inside
+# 65535 (64181/64182) but N = 6 overflows (74181/74182), so the cap is 5.
+PENPOT_MAX_WS_INDEX=5
+function parse-ws-integer {
+    local raw="$1"
+    if [[ ! "$raw" =~ ^[0-9]+$ ]]; then
+        echo "Invalid --ws value: '$raw' (expected a non-negative integer, e.g. --ws 0, --ws 1, --ws 2)" >&2
+        return 1
+    fi
+    if (( raw > PENPOT_MAX_WS_INDEX )); then
+        echo "Invalid --ws value: '$raw' (max supported is --ws $PENPOT_MAX_WS_INDEX; higher indexes would overflow the 16-bit TCP port range)" >&2
+        return 1
+    fi
+    echo "ws$raw"
 }
 
 
+# Bring a single agentic instance up: compose up + detached tmux start with
+# MCP and Serena enabled. Workspace sync and env-file generation are the
+# caller's responsibility (run-devenv-agentic handles them for ws1+).
+function start-instance {
+    local instance="$1"
+    local serena_context="$2"
+    local git_user_name="${3:-}"
+    local git_user_email="${4:-}"
+
+    instance-compose "$instance" up -d --no-deps main redis
+
+    # Wait briefly for main to be reachable; the tmux session lives inside.
+    local container deadline
+    container=$(devenv-main-container "$instance")
+    deadline=$(( SECONDS + 30 ))
+    while ! docker inspect -f '{{.State.Running}}' "$container" 2>/dev/null | grep -q true; do
+        [[ $SECONDS -ge $deadline ]] && {
+            echo "[${instance}] main container did not reach Running within 30s" >&2
+            return 1
+        }
+        sleep 1
+    done
+
+    # Seed the container's global git config from the values resolved on the
+    # host so commits made inside the devenv carry a real author/committer. Empty
+    # values are skipped — the host-identity warning is the caller's job.
+    if [[ -n "$git_user_name" ]]; then
+        docker exec "$container" sudo -u penpot git config --global user.name "$git_user_name"
+    fi
+    if [[ -n "$git_user_email" ]]; then
+        docker exec "$container" sudo -u penpot git config --global user.email "$git_user_email"
+    fi
+
+    # Detached tmux so callers don't block on attach. Agentic mode is the only
+    # mode here, so MCP and Serena are always on.
+    docker exec -d \
+        -e PENPOT_TMUX_ATTACH=false \
+        -e PENPOT_FLAGS="${PENPOT_FLAGS:-} enable-mcp" \
+        -e SERENA_ENABLED=true \
+        -e SERENA_CONTEXT="$serena_context" \
+        "$container" \
+        sudo -EH -u penpot PENPOT_PLUGIN_DEV="${PENPOT_PLUGIN_DEV:-}" /home/start-tmux.sh
+}
+
+# Stop and remove one instance's containers without touching its volumes or
+# its on-disk workspace directory (rule: never wipe data).
+function stop-instance {
+    local instance="$1"
+    instance-compose "$instance" down -t 2
+}
+
+# Print per-instance URLs (Penpot UI, MCP stream endpoint, Serena, attach
+# command) for one instance.
+function print-instance-info {
+    local instance="$1"
+    local public mcp serena serena_dash
+    public=$(instance-port "$instance" "$PENPOT_PORT_BASE_PUBLIC")
+    mcp=$(instance-port "$instance" "$PENPOT_PORT_BASE_MCP")
+    serena=$(instance-port "$instance" "$PENPOT_PORT_BASE_SERENA")
+    serena_dash=$(instance-port "$instance" "$PENPOT_PORT_BASE_SERENA_DASHBOARD")
+
+    # --ws takes a bare integer; ws0 is the default, so its flag is elided.
+    local n="${instance#ws}"
+    local ws_flag=""
+    [[ "$instance" != "ws0" ]] && ws_flag=" --ws ${n}"
+
+    echo
+    echo "[$instance]"
+    echo "  Penpot UI:           https://localhost:${public}"
+    echo "  MCP stream:          http://localhost:${mcp}/mcp"
+    echo "  Serena MCP:          http://localhost:${serena}"
+    echo "  Serena dashboard:    http://localhost:${serena_dash}"
+    echo "  Attach:              ./manage.sh attach-devenv${ws_flag}"
+    echo "  Coding agent:        ./manage.sh start-coding-agent claude${ws_flag}  (or: opencode|vscode|codex)"
+}
+
+# Bring up a single agentic instance (always with MCP + Serena).
+#
+#   --ws N       target instance (non-negative integer). Default: 0 (ws0).
+#   --sync       re-seed the workspace from the live repo. Forbidden on main;
+#                ws1+ also sync implicitly the first time when their workspace
+#                directory does not exist yet.
+#   --serena-context CTX  passed to Serena (default: desktop-app).
+#   --git-user-name NAME  Git author/committer name to wire into the
+#                container's global git config (so commits made inside the
+#                devenv carry a real identity). Defaults to the host's
+#                effective `git config user.name` when omitted (resolved at
+#                the current working directory, so a per-repo local override
+#                in <repo>/.git/config takes precedence over ~/.gitconfig).
+#   --git-user-email EMAIL  matching email; defaults to the host's effective
+#                `git config user.email` (same local-over-global precedence).
+#
+# ws0 is the worker-bearer and must be running whenever any ws1+ is up. When
+# starting ws1+, ws0 is brought up first automatically if it is not already
+# running. Errors out if the requested target itself is already running.
 function run-devenv-agentic {
+    local target="ws0"
+    local do_sync=false
     local serena_context="desktop-app"
-    local serena_external_port="14281"
-    local serena_dashboard_external_port="14282"
+    local git_user_name=""
+    local git_user_email=""
 
     while [[ $# -gt 0 ]]; do
         case "$1" in
+            --ws)
+                target="$(parse-ws-integer "$2")" || return 1; shift 2;;
+            --sync)
+                do_sync=true; shift;;
             --serena-context)
                 serena_context="$2"; shift 2;;
+            --git-user-name)
+                git_user_name="$2"; shift 2;;
+            --git-user-email)
+                git_user_email="$2"; shift 2;;
             *)
-                shift;;
+                echo "run-devenv-agentic: unknown argument '$1'" >&2
+                return 1;;
         esac
     done
 
-    if [[ ! $(docker ps -f "name=penpot-devenv-main" -q) ]]; then
-        SERENA_EXTERNAL_PORT="$serena_external_port" \
-        SERENA_DASHBOARD_EXTERNAL_PORT="$serena_dashboard_external_port" \
-        start-devenv
-        echo "Waiting for containers fully start (5s)..."
-        sleep 5;
+    if [[ "$target" == "ws0" && "$do_sync" == "true" ]]; then
+        echo "run-devenv-agentic: --sync is not allowed on main (ws0)." >&2
+        return 1
     fi
 
-    run-devenv-tmux \
-        -e SERENA_ENABLED=true \
-        -e SERENA_CONTEXT="$serena_context" \
-        -e PENPOT_FLAGS="${PENPOT_FLAGS} enable-mcp"
+    # Fall back to the host developer's effective git identity when the
+    # respective flag is not provided. Plain `git config user.X` (no --global)
+    # honours the local->global->system precedence, so a per-repo override in
+    # <repo>/.git/config takes precedence over ~/.gitconfig -- matching what
+    # `git commit` on the host would actually record. `|| true` swallows the
+    # non-zero exit for a missing entry; the empty result is propagated
+    # untouched and surfaces as a no-op inside the container (start-tmux.sh
+    # skips `git config --global` when the env var is empty).
+    if [[ -z "$git_user_name" ]]; then
+        git_user_name="$(git config user.name 2>/dev/null || true)"
+    fi
+    if [[ -z "$git_user_email" ]]; then
+        git_user_email="$(git config user.email 2>/dev/null || true)"
+    fi
+    if [[ -z "$git_user_name" || -z "$git_user_email" ]]; then
+        echo "[$target] warning: host git identity is incomplete (name='${git_user_name}', email='${git_user_email}')." >&2
+        echo "  Commits made inside the devenv will fail until you set it via --git-user-name / --git-user-email" >&2
+        echo "  or 'git config user.{name,email}' on the host." >&2
+    fi
+
+    if devenv-main-running "$target"; then
+        echo "run-devenv-agentic: instance '$target' is already running." >&2
+        return 1
+    fi
+
+    # Pre-flight: frontend/resources/public/js/config.js must exist in the
+    # live repo. The file is gitignored; ws0 reads it directly from $PWD and
+    # wsN gets a one-shot copy on its initial sync. Without it the frontend
+    # never sets the 'enable-mcp' flag, so the agent can't drive Penpot via
+    # MCP. Fail fast (before any side effects) so the developer can fix it
+    # without leaving infra / containers half-started behind.
+    local cfg="frontend/resources/public/js/config.js"
+    if [[ ! -f "$PWD/$cfg" ]]; then
+        echo "$cfg is missing in the live repo." >&2
+        echo "Create it before running run-devenv-agentic -- the file is gitignored," >&2
+        echo "read directly from \$PWD on ws0 and copied into wsN only on its initial" >&2
+        echo "sync. Without it the Penpot frontend will not establish the MCP" >&2
+        echo "connection, so the agent cannot drive it. Minimal content:" >&2
+        echo "  var penpotFlags = \"enable-mcp\";" >&2
+        return 1
+    fi
+
+    pull-devenv-if-not-exists
+    ensure-devenv-network
+    ensure-infra-up
+
+    # ws0 invariant: must be up whenever any ws1+ runs. Bring it up first if a
+    # non-main instance is being requested and ws0 is not yet running.
+    if [[ "$target" != "ws0" ]] && ! devenv-main-running "ws0"; then
+        echo "[ws0] not running; starting it first (workers run only on ws0)."
+        echo "Starting ws0..."
+        write-instance-mcp-configs "ws0"
+        start-instance "ws0" "$serena_context" "$git_user_name" "$git_user_email"
+        print-instance-info "ws0"
+    fi
+
+    if [[ "$target" != "ws0" ]]; then
+        local workspace
+        workspace=$(workspace-path "$target")
+        if [[ ! -d "$workspace" ]]; then
+            echo "[$target] workspace at $workspace does not exist; performing initial sync."
+            do_sync=true
+        fi
+        if [[ "$do_sync" == "true" ]]; then
+            sync-workspace "$target"
+        fi
+    fi
+
+    echo "Starting $target..."
+    write-instance-mcp-configs "$target"
+    start-instance "$target" "$serena_context" "$git_user_name" "$git_user_email"
+    print-instance-info "$target"
 }
 
 function run-devenv-shell {
-    if [[ ! $(docker ps -f "name=penpot-devenv-main" -q) ]]; then
-        start-devenv
+    local instance="ws0"
+    local positional=()
+    while [[ $# -gt 0 ]]; do
+        case "$1" in
+            --ws)
+                instance="$(parse-ws-integer "$2")" || return 1; shift 2;;
+            *)
+                positional+=("$1"); shift;;
+        esac
+    done
+
+    if ! devenv-main-running "$instance"; then
+        if [[ "$instance" == "ws0" ]]; then
+            start-devenv
+        else
+            echo "Instance '$instance' is not running." >&2
+            echo "Bring it up first with './manage.sh run-devenv-agentic --ws ${instance#ws}'." >&2
+            return 1
+        fi
     fi
+    # No positional args -> drop the user into a bash shell. Without this,
+    # `sudo -EH -u penpot` would be called with no command and just print its
+    # own usage.
+    if [[ ${#positional[@]} -eq 0 ]]; then
+        positional=(bash)
+    fi
+    local container
+    container=$(devenv-main-container "$instance")
     docker exec -ti \
+           -w /home/penpot/penpot \
            -e JAVA_OPTS="$JAVA_OPTS" \
            -e EXTERNAL_UID=$CURRENT_USER_ID \
-           penpot-devenv-main sudo -EH -u penpot $@
+           "$container" sudo -EH -u penpot "${positional[@]}"
+}
+
+function attach-devenv {
+    local instance="ws0"
+    while [[ $# -gt 0 ]]; do
+        case "$1" in
+            --ws)
+                instance="$(parse-ws-integer "$2")" || return 1; shift 2;;
+            *)
+                echo "attach-devenv: unknown argument '$1'" >&2
+                return 1;;
+        esac
+    done
+
+    if ! devenv-main-running "$instance"; then
+        echo "Instance '$instance' is not running." >&2
+        echo "Start it first with './manage.sh run-devenv-agentic [--ws N]'." >&2
+        return 1
+    fi
+
+    local session="penpot"
+    local container
+    container=$(devenv-main-container "$instance")
+
+    if ! docker exec "$container" sudo -EH -u penpot tmux has-session -t "$session" 2>/dev/null; then
+        echo "No tmux session '$session' inside instance '$instance'." >&2
+        echo "The session may still be starting (the workspace's startup script runs the" >&2
+        echo "project setup before creating it) or it may have been closed. Wait and retry." >&2
+        return 1
+    fi
+
+    docker exec -ti "$container" sudo -EH -u penpot tmux attach -t "$session"
+}
+
+# Launch an AI coding agent against one parallel devenv workspace with the
+# right MCP config wired in. The generated config enhances rather than
+# replaces the developer's global client config; see .devenv/README.md for
+# the precedence rules and override paths.
+#
+# Target selection:
+#   no flag    → ws0 (the live repo at $PWD).
+#   --ws N     → wsN's workspace clone at ${PENPOT_WORKSPACES_DIR}/wsN
+#                (N is an integer; non-integer values are rejected).
+# Before launching, the function cd's into the resolved workspace and refuses
+# to start unless the target instance's 'main' container is up — the Penpot
+# and Serena MCP servers only exist while the devenv is running.
+#
+# Per-client launch behaviour:
+#   claude    exec'd with --mcp-config <workspace>/.devenv/mcp/claude-code.json
+#   opencode  exec'd with OPENCODE_CONFIG=<workspace>/.devenv/mcp/opencode.json
+#   vscode    'code' launched on the workspace; .vscode/mcp.json is
+#             auto-discovered by GitHub Copilot
+#   codex     'codex' exec'd from the workspace with our servers passed as
+#             `-c mcp_servers.<name>....` overrides (built fresh from the
+#             committed templates). Nothing is written to .codex/config.toml,
+#             so the developer's own Codex config is left untouched.
+#
+# Usage: ./manage.sh start-coding-agent <claude|opencode|vscode|codex> [--ws N] [...passthrough]
+function start-coding-agent {
+    local client="${1:-}"
+    [[ $# -gt 0 ]] && shift
+
+    case "$client" in
+        ""|-h|--help)
+            echo "Usage: $0 start-coding-agent <claude|opencode|vscode|codex> [--ws N] [...passthrough]" >&2
+            return 1
+            ;;
+        claude|opencode|vscode|codex)
+            ;;
+        *)
+            echo "start-coding-agent: unknown client '$client' (expected one of claude, opencode, vscode, codex)." >&2
+            return 1
+            ;;
+    esac
+
+    local instance="ws0"
+    if [[ $# -gt 0 && "$1" == "--ws" ]]; then
+        instance="$(parse-ws-integer "$2")" || return 1
+        shift 2
+    fi
+
+    # --ws is the default-elided flag: only emit it in suggestion strings for
+    # ws1+; ws0 is the default target so 'run-devenv-agentic' is the right hint.
+    local ws_flag=""
+    [[ "$instance" != "ws0" ]] && ws_flag=" --ws ${instance#ws}"
+
+    # Resolve the workspace directory for the target instance. ws0 binds
+    # the live repo; ws1+ are clones under PENPOT_WORKSPACES_DIR.
+    local workspace
+    if [[ "$instance" == "ws0" ]]; then
+        workspace="$PWD"
+    else
+        workspace="$(workspace-path "$instance")"
+        if [[ ! -d "$workspace" ]]; then
+            echo "start-coding-agent: workspace for $instance not found at $workspace." >&2
+            echo "Bring '$instance' up first with './manage.sh run-devenv-agentic${ws_flag}'." >&2
+            return 1
+        fi
+    fi
+
+    # The MCP servers the agent talks to only exist while 'main' is up.
+    # Refuse rather than launch an agent that would error on every tool call.
+    if ! devenv-main-running "$instance"; then
+        echo "start-coding-agent: instance '$instance' is not running." >&2
+        echo "Start it first with './manage.sh run-devenv-agentic${ws_flag}'." >&2
+        return 1
+    fi
+
+    # Per-client binary + config path (relative to the workspace dir so the
+    # launch line in error messages and `exec` is short and stable). Codex has
+    # no generated config file -- its servers are injected as `-c` flags below
+    # -- so cfg_rel points at the committed template that those flags are built
+    # from (present on ws0 in the repo, synced into ws1+).
+    local bin cfg_rel
+    case "$client" in
+        claude)   bin="claude";   cfg_rel=".devenv/mcp/claude-code.json" ;;
+        opencode) bin="opencode"; cfg_rel=".devenv/mcp/opencode.json" ;;
+        vscode)   bin="code";     cfg_rel=".vscode/mcp.json" ;;
+        codex)    bin="codex";    cfg_rel=".devenv/templates/codex.toml" ;;
+    esac
+
+    if ! command -v "$bin" >/dev/null 2>&1; then
+        echo "start-coding-agent: '$bin' is not on PATH." >&2
+        echo "Install it first, then retry." >&2
+        return 1
+    fi
+
+    if [[ ! -f "$workspace/$cfg_rel" ]]; then
+        echo "start-coding-agent: $workspace/$cfg_rel not found." >&2
+        echo "Bring '$instance' up with './manage.sh run-devenv-agentic${ws_flag}'," >&2
+        echo "which sets up the per-workspace MCP config." >&2
+        return 1
+    fi
+
+    cd "$workspace" || return 1
+    case "$client" in
+        claude)
+            exec claude --mcp-config "$cfg_rel" "$@"
+            ;;
+        opencode)
+            OPENCODE_CONFIG="$cfg_rel" exec opencode "$@"
+            ;;
+        vscode)
+            exec code "$workspace" "$@"
+            ;;
+        codex)
+            # Build our servers as `-c mcp_servers.<name>....` overrides from the
+            # committed templates (ports resolved from the instance number) and
+            # pass them on the command line. Nothing is written to disk, so the
+            # developer's project- or user-level .codex/config.toml is untouched.
+            PENPOT_MCP_PORT=$(instance-port "$instance" "$PENPOT_PORT_BASE_MCP")
+            SERENA_MCP_PORT=$(instance-port "$instance" "$PENPOT_PORT_BASE_SERENA")
+            export PENPOT_MCP_PORT SERENA_MCP_PORT
+            local -a codex_args=()
+            local _assignment
+            while IFS= read -r _assignment; do
+                [[ -n "$_assignment" ]] && codex_args+=(-c "$_assignment")
+            done < <(python3 .devenv/scripts/merge-mcp-config.py --format codex-args \
+                        .devenv/shared/codex.toml \
+                        .devenv/templates/codex.toml)
+            if [[ ${#codex_args[@]} -eq 0 ]]; then
+                echo "start-coding-agent: failed to build Codex MCP overrides from" >&2
+                echo "  .devenv/{shared,templates}/codex.toml." >&2
+                return 1
+            fi
+            exec codex "${codex_args[@]}" "$@"
+            ;;
+    esac
 }
 
 function run-devenv-isolated-shell {
-    docker volume create ${DEVENV_PNAME}_user_data;
+    local instance="ws0"
+    local positional=()
+    while [[ $# -gt 0 ]]; do
+        case "$1" in
+            --ws)
+                instance="$(parse-ws-integer "$2")" || return 1; shift 2;;
+            *)
+                positional+=("$1"); shift;;
+        esac
+    done
+
+    # Resolve the user_data volume and source tree for the target workspace.
+    # ws0 uses the baseline volume name from defaults.env; wsN follows the
+    # instance-env-overrides naming convention (penpotdev_<instance>_user_data)
+    # and bind-mounts the workspace clone instead of $PWD.
+    local user_data_volume source_path
+    if [[ "$instance" == "ws0" ]]; then
+        user_data_volume="$PENPOT_USER_DATA_VOLUME"
+        source_path="$PWD"
+    else
+        user_data_volume="penpotdev_${instance}_user_data"
+        source_path="$(workspace-path "$instance")"
+        if [[ ! -d "$source_path" ]]; then
+            echo "isolated-shell: workspace for $instance not found at $source_path." >&2
+            return 1
+        fi
+    fi
+
+    # No command -> drop into bash. Always cwd to the source-tree root;
+    # callers that need a subdir can `cd` inside the shell or pass
+    # `bash -c 'cd subdir && cmd'`.
+    if [[ ${#positional[@]} -eq 0 ]]; then
+        positional=(bash)
+    fi
+
+    docker volume create "$user_data_volume" >/dev/null
     docker run -ti --rm \
-           --mount source=${DEVENV_PNAME}_user_data,type=volume,target=/home/penpot/ \
-           --mount source=`pwd`,type=bind,target=/home/penpot/penpot \
+           --mount source="$user_data_volume",type=volume,target=/home/penpot/ \
+           --mount source="$source_path",type=bind,target=/home/penpot/penpot \
            -e EXTERNAL_UID=$CURRENT_USER_ID \
            -e BUILD_STORYBOOK=$BUILD_STORYBOOK \
            -e BUILD_WASM=$BUILD_WASM \
            -e SHADOWCLJS_EXTRA_PARAMS=$SHADOWCLJS_EXTRA_PARAMS \
            -e JAVA_OPTS="$JAVA_OPTS" \
-           -w /home/penpot/penpot/$1 \
-           $DEVENV_IMGNAME:latest sudo -EH -u penpot $@
+           -w /home/penpot/penpot \
+           "$DEVENV_IMGNAME:latest" sudo -EH -u penpot "${positional[@]}"
 }
 
 function build-imagemagick-docker-image {
@@ -217,9 +1137,9 @@ function build {
     local script=${2:-build}
 
     pull-devenv-if-not-exists;
-    docker volume create ${DEVENV_PNAME}_user_data;
+    docker volume create ${PENPOT_USER_DATA_VOLUME};
     docker run -t --rm \
-           --mount source=${DEVENV_PNAME}_user_data,type=volume,target=/home/penpot/ \
+           --mount source=${PENPOT_USER_DATA_VOLUME},type=volume,target=/home/penpot/ \
            --mount source=`pwd`,type=bind,target=/home/penpot/penpot \
            -e EXTERNAL_UID=$CURRENT_USER_ID \
            -e BUILD_STORYBOOK=$BUILD_STORYBOOK \
@@ -393,21 +1313,68 @@ function build-storybook-docker-image {
 function usage {
     echo "PENPOT build & release manager"
     echo "USAGE: $0 OPTION"
-    echo "Options:"
-    echo "- pull-devenv                      Pulls docker development oriented image"
-    echo "- build-devenv                     Build docker development oriented image"
-    echo "- build-devenv --local             Build a local docker development oriented image"
-    echo "- create-devenv                    Create the development oriented docker compose service."
-    echo "- start-devenv                     Start the development oriented docker compose service."
-    echo "- stop-devenv                      Stops the development oriented docker compose service."
-    echo "- drop-devenv                      Remove the development oriented docker compose containers, volumes and clean images."
-    echo "- run-devenv                       Attaches to the running devenv container and starts development environment"
+    echo ""
+    echo "Development environment (devenv)"
+    echo "--------------------------------"
+    echo "The devenv runs Penpot in a Docker container and supports parallel"
+    echo "'workspaces': ws0 (the live repo at \$PWD) and optional wsN (N >= 1, sibling"
+    echo "clones). Use --ws N to target a specific workspace; the default is 0."
+    echo "Full guide: docs/technical-guide/developer/{devenv,agentic-devenv}.md."
+    echo ""
+    echo "Image lifecycle"
+    echo "- pull-devenv                      Pull the devenv docker image from the registry."
+    echo "- build-devenv [--local]           Build the devenv docker image (--local skips the registry push)."
+    echo ""
+    echo "Bring a devenv up / down"
+    echo "- run-devenv-agentic               Bring one workspace up with AI-agent tooling enabled (MCP + Serena),"
+    echo "                                   start its tmux session in the background, regenerate the per-workspace"
+    echo "                                   MCP configs, and print the workspace's URLs. Errors out if the target"
+    echo "                                   is already running."
+    echo "                                   Options:"
+    echo "                                     --ws N                target workspace (default: 0). N >= 1 auto-starts"
+    echo "                                                           ws0 first if it is not already up."
+    echo "                                     --sync                re-seed the wsN clone from the live repo before"
+    echo "                                                           starting (forbidden on ws0; implicit on first"
+    echo "                                                           start of a wsN with no on-disk workspace yet)."
+    echo "                                     --serena-context CTX  passed to Serena (default: desktop-app)."
+    echo "                                     --git-user-name NAME / --git-user-email EMAIL"
+    echo "                                                           identity wired into the container's git config"
+    echo "                                                           (default: host's effective 'git config user.X',"
+    echo "                                                           honouring per-repo local overrides; see"
+    echo "                                                           devenv.md > 'Git identity inside the container')."
+    echo "- start-devenv                     Bring ws0 + shared infra up in the background (no tmux, no MCP/Serena)."
+    echo "- create-devenv                    Create ws0 + shared-infra compose services without starting them."
+    echo "- stop-devenv                      Stop one or more workspaces. Shared infra stops with the last one."
+    echo "                                   Options: --ws N (stop wsN, N >= 1) | (no flag) (stop ws0 + infra;"
+    echo "                                            refused if any wsN is still running) | --all (stop every wsN"
+    echo "                                            highest first, then ws0 + infra)."
+    echo "- drop-devenv                      Same CLI and invariants as stop-devenv (see above), plus removal of"
+    echo "                                   the shared devenv image on full teardowns (no flag, --ws 0, or --all)."
+    echo "                                   Refused if any wsN (N >= 1) is still running. A single --ws N (N >= 1)"
+    echo "                                   keeps the image since other workspaces still need it."
+    echo "- log-devenv                       Tail a workspace's compose logs."
+    echo "                                   Options: --ws N (default: 0)."
+    echo ""
+    echo "Work inside a running devenv"
+    echo "- attach-devenv                    Attach to the tmux session inside a running workspace."
+    echo "                                   Options: --ws N (default: 0)."
+    echo "- start-coding-agent <client>      Launch an AI coding agent against one workspace with the right MCP"
+    echo "                                   config wired in. cd's into the workspace, refuses to launch if the"
+    echo "                                   instance is not running, and forwards extra args to the client."
+    echo "                                   client: claude | opencode | vscode | codex"
+    echo "                                   Options: --ws N (default: 0). See agentic-devenv.md and"
+    echo "                                   .devenv/README.md for per-client setup and override paths."
+    echo "- run-devenv-shell                 Open a bash shell inside the workspace's running devenv container"
+    echo "                                   ('docker exec' into the live 'main' container alongside the tmux"
+    echo "                                   session). Requires the workspace to be up."
+    echo "                                   Options: --ws N (default: 0)."
+    echo "- run-devenv                       Start ws0 if needed and attach to its tmux session interactively."
     echo "                                   Optional -e flags are forwarded to 'docker exec' (e.g. -e MY_VAR=value)."
-    echo "- run-devenv-agentic               Like run-devenv but with additional processes for agentic development enabled."
-    echo "                                   Options: --serena-context CONTEXT (default: desktop-app)"
-    echo "- run-devenv-shell                 Attaches to the running devenv container and starts a bash shell."
-    echo "- isolated-shell                   Starts a bash shell in a new devenv container."
-    echo "- log-devenv                       Show logs of the running devenv docker compose service."
+    echo "- isolated-shell                   Spawn a fresh, ephemeral devenv container ('docker run', not 'docker exec')"
+    echo "                                   with the workspace's source tree and build-cache volume mounted. Use this"
+    echo "                                   for ad-hoc work that should not touch the running devenv (e.g. manual"
+    echo "                                   builds); the workspace does not need to be running."
+    echo "                                   Options: --ws N (default: 0)."
     echo ""
     echo "- build-bundle                     Build all bundles (frontend, backend, exporter, storybook and mcp)."
     echo "- build-frontend-bundle            Build frontend bundle"
@@ -455,6 +1422,12 @@ case $1 in
     run-devenv-agentic)
         run-devenv-agentic ${@:2}
         ;;
+    attach-devenv)
+        attach-devenv ${@:2}
+        ;;
+    start-coding-agent)
+        start-coding-agent "${@:2}"
+        ;;
     run-devenv-shell)
         run-devenv-shell ${@:2}
         ;;