Skip to content

Open-source AI teammates in Slack, Teams, Discord, Telegram and Mattermost. Self-host it, with any agent harness and any model.

docs(switchdash): cover remote execution and Switch rooms (CHOO-1860)

Louis Amaudruzb326ab7afd9b
diff --git a/dash/AGENTS.md b/dash/AGENTS.md
index 86602e6a2..8320ceb71 100644
--- a/dash/AGENTS.md
+++ b/dash/AGENTS.md
@@ -525,6 +525,8 @@ pnpm run test
- [Main process architecture](agents/architecture/main-process.md)
- [Renderer architecture](agents/architecture/renderer.md)
- [Shared modules](agents/architecture/shared.md)
+- [Remote execution: hosts, reachability, sidecar](agents/architecture/remote-execution.md)
+- [Switch rooms and sessions](agents/architecture/switch-rooms.md)
- [Data model (switchdash vs. its upstream origin)](agents/architecture/data-model.md)
- [Testing workflow](agents/workflows/testing.md)
- [Provider integration](agents/integrations/providers.md)
diff --git a/dash/agents/README.md b/dash/agents/README.md
index 907112c7a..466ccc0c7 100644
--- a/dash/agents/README.md
+++ b/dash/agents/README.md
@@ -8,6 +8,11 @@ This directory is the system of record for agent-facing repo guidance. Keep topi
2. `architecture/overview.md`
3. the task-specific page for the area you are changing
+If the change touches remote hosts or Switch rooms, read
+`architecture/remote-execution.md` and `architecture/switch-rooms.md` too — switchdash
+runs agents on SSH hosts as well as locally, and the remote path is a separate
+implementation.
+
## Directory Layout
- `architecture/`
diff --git a/dash/agents/architecture/overview.md b/dash/agents/architecture/overview.md
index ba82400d2..408db4035 100644
--- a/dash/agents/architecture/overview.md
+++ b/dash/agents/architecture/overview.md
@@ -8,6 +8,7 @@ All paths are relative to `apps/switchdash-desktop/`.
- `src/preload/`: Electron preload bridge — exposes typed `invoke`, `eventSend`, `eventOn` to renderer
- `src/renderer/`: React UI — app shell (`app/`), feature areas (`features/`), shared infrastructure (`lib/`), typed RPC client
- `src/shared/`: Agent provider registry, IPC primitives (RPC + events), shared domain types under `src/shared/core/`
+- `src/sidecar/`: The headless on-host sidecar that keeps a remote session running while switchdash is closed. Not an Electron process — see `remote-execution.md`
## Boot Sequence
@@ -29,3 +30,5 @@ All paths are relative to `apps/switchdash-desktop/`.
- Main process details: `main-process.md`
- Renderer details: `renderer.md`
- Shared modules and provider registry: `shared.md`
+- Remote hosts, reachability, and the sidecar: `remote-execution.md`
+- Switch rooms and session binding: `switch-rooms.md`
diff --git a/dash/agents/architecture/remote-execution.md b/dash/agents/architecture/remote-execution.md
new file mode 100644
index 000000000..58bea6e9b
--- /dev/null
+++ b/dash/agents/architecture/remote-execution.md
@@ -0,0 +1,105 @@
+# Remote Execution: Hosts, Reachability, and the Sidecar
+
+All paths are relative to `apps/switchdash-desktop/` unless noted.
+
+**Switchdash is not local-only.** An agent runs either on the local machine or on an SSH
+host. That choice reaches almost every layer — execution context, agent runtime,
+dependency detection, PTY — so a change that only handles the local case is a change that
+silently does less on a remote host. This page is the map of the remote half.
+
+## The pieces
+
+| Concern | Where |
+|---|---|
+| SSH host records, keyed by `~/.ssh/config` alias | `src/main/core/remote-hosts/`, table `remote_hosts` |
+| Reachability state machine | `remote-hosts/host-reachability-service.ts`, `src/shared/core/remote-hosts/reachability.ts`, table `remote_host_reachability` |
+| SSH config, connection, transport | `src/main/core/ssh/` |
+| Where a command runs | `src/main/core/execution-context/` — `local-execution-context.ts` / `ssh-execution-context.ts` |
+| How a session is launched | `src/main/core/agent-runtime/impl/` — `local-agent-runtime.ts` / `ssh-agent-runtime.ts` |
+| Remote dependency detection and install | `dependencies/remote-dependency-manager.ts`, `dependencies/ssh-install-runner.ts` |
+| The on-host sidecar | `src/sidecar/` (implementation), `src/main/core/sidecar/` (desktop-side diagnostics) |
+| A switchdash-managed Switch server | `src/main/core/managed-switch-server/` |
+| Renderer surfaces | `src/renderer/features/remote-hosts/` |
+
+## Reachability is a state machine, not a boolean (CHOO-1682)
+
+Before it existed, "can we reach host X?" was answered independently by every caller — the
+pooled connection's in-memory state, an on-demand `testConnection`, or just attempting the
+work and interpreting the ssh2 error. That produced unbounded retry loops against dead
+hosts and raw transport errors in the UI. Now there is **one per-host state** that every
+host-dependent path consults up front:
+
+- `unknown` — never probed this run. **Work is allowed through**; the first attempt is what
+ establishes reachability.
+- `reachable` — a probe or live connection succeeded.
+- `unreachable` — probes failing. Background work pauses; a bounded backoff probe keeps
+ checking so recovery is automatic.
+- `suspended` — **authentication** failed. Retrying a rejected key never self-heals, so
+ there is no automatic probing; the user must fix auth and retry explicitly.
+
+The backoff is `1s, 5s, 15s, 30s, 60s, 300s` (capped and repeated). Early steps are tight
+because the common cause is a credential the user is actively re-establishing (VPN,
+`aws sso login`); the long tail keeps a genuinely dead host from costing anything. A manual
+retry short-circuits the schedule.
+
+**When adding a host-dependent path, gate it on reachability rather than discovering the
+failure yourself.** The distinction between `unreachable` and `suspended` is the point: one
+is worth retrying automatically and the other is not.
+
+### Never report "fine" for something you did not observe
+
+A check that could not run is **not** a passing check. Collapsing "couldn't determine" into
+"satisfied" is the stale-green bug (CHOO-1780) — the UI claims a host is ready, the user
+acts on it, and the failure surfaces somewhere less obvious. Keep `unknown` as a
+first-class answer all the way to the surface.
+
+## Host setup is a persisted plan (CHOO-1809)
+
+> This section describes `feature-request/remote-host-onboarding-rewrite`. If you are
+> reading it on a checkout where `src/main/core/remote-hosts/setup/` does not exist, that
+> branch has not merged yet.
+
+Onboarding a host used to be a single boolean — a row existed or it didn't — with every
+prerequisite probed independently by whichever component happened to render. There was no
+notion of *where a host got to*, so nothing could be resumed or ordered, and a failure
+halfway through left no record.
+
+A **setup plan** is that missing object: an ordered list of steps, persisted per host in
+`remote_host_setup_plans`, answering "what still needs to happen on this host, and what
+went wrong last time?".
+
+- Model: `src/shared/core/remote-hosts/setup.ts`, `host-status.ts`
+- Main: `src/main/core/remote-hosts/setup/` — `plan-builder.ts`, `host-setup-runner.ts`,
+ `host-setup-service.ts`, `setup-plan-store.ts`, `step-outcomes.ts`
+- Renderer: `src/renderer/features/remote-hosts/setup/`, `host-readiness.ts`
+
+Two properties worth preserving:
+
+- **Nothing advances the plan on its own.** Each step runs when the user asks for that
+ step; the ordering is guidance, not automation. There is deliberately no
+ run-everything button.
+- **A check outcome is richer than a boolean** — `satisfied`, `missing`, `not-running`,
+ `wrong-version`, `unknown`. `not-running` matters because `docker` being on `PATH` tells
+ you nothing about whether `dockerd` is up, and running an installer over a stopped
+ service would misreport the cause.
+
+## The sidecar
+
+A remote agent runs inside tmux next to a switchdash-deployed **sidecar**, so it keeps
+working and listening to its Switch rooms while switchdash is closed (CHOO-1059).
+
+`src/sidecar/` is a second, headless implementation of what the desktop does for a
+session — it starts sessions, keeps them connected to their room, and injects messages into
+their pane — with no Electron, no database and no renderer.
+
+**Read the sidecar section of `AGENTS.md` before changing session launch behaviour.** It
+lists the desktop/sidecar pairs that must stay in step, and the sharpest edge: anything
+reaching a session through its **environment** is built separately on each side.
+
+## When editing here
+
+- Check the reachability state before adding a host-dependent code path.
+- Ask whether a change to local session launch needs the same change in `src/sidecar/`.
+- Remote dependency detection and install are separate implementations from the local
+ ones — see `dependencies/remote-dependency-manager.ts`.
+- See `agents/architecture/switch-rooms.md` for how a session binds to a Switch room.
diff --git a/dash/agents/architecture/switch-rooms.md b/dash/agents/architecture/switch-rooms.md
new file mode 100644
index 000000000..8f9f9e2b1
--- /dev/null
+++ b/dash/agents/architecture/switch-rooms.md
@@ -0,0 +1,86 @@
+# Switch Rooms and Sessions
+
+All paths are relative to `apps/switchdash-desktop/`.
+
+Switchdash exists to manage Switch agents, and a Switch agent's work happens in **rooms**.
+A session can be *attending* a room: it receives the room's events and can post back into
+it. This page covers that binding, how a session is started in response to room activity,
+and how a room's conversation is shown in the app.
+
+## Where it lives
+
+| Concern | Where |
+|---|---|
+| Room connection, credentials, event stream | `src/main/core/switch-rooms/` |
+| Room/session binding | table `session_room_connections`, `session-room-store.ts` |
+| Auto-start a session from room activity | `switch-rooms/auto-session-watcher.ts` |
+| Prompt injection into a live TUI | `switch-rooms/injection-sink.ts`, `tmux-injection-sink.ts` |
+| Switch servers (managed or external) | `src/main/core/switch-servers/`, `managed-switch-server/` |
+| Renderer | `src/renderer/features/switch-rooms/`, `features/switch-servers/` |
+| Shared types | `src/shared/core/switch-rooms/` |
+
+## A session attends at most one room
+
+The binding is a `session_room_connections` row keyed by `session_id` with
+`ON DELETE CASCADE`, so it cannot outlive the session (or the agent above it).
+
+This is worth knowing because of what it replaced: the binding used to be a JSON blob in
+`app_settings`, which referenced nothing and therefore survived both. Switchdash would
+restore sessions on every launch for agents whose Switch server had been destroyed. If you
+are tempted to persist session-adjacent state somewhere convenient, that is the bug to
+remember.
+
+## Auto-sessions
+
+`auto-session-watcher.ts` watches for room activity addressed to an agent that has no live
+session, and starts one. This is why an agent can be addressed from Slack or Mattermost and
+simply respond, without anyone opening switchdash first.
+
+**The sidecar has its own implementation of this watcher**
+(`src/sidecar/notification-watcher.ts`). They are two implementations of one behaviour, and
+neither follows the other — see the sidecar table in `AGENTS.md`.
+
+## Prompt injection
+
+Some providers cannot be handed a new prompt through an API once their TUI is running, so
+switchdash types it in. `InjectionSink` abstracts the transport:
+
+- **Local** — write straight to the agent's PTY via node-pty.
+- **Remote** — the sidecar performs `tmux send-keys` into the agent's tmux pane.
+
+`acquire` returns null when the target is not ready to receive input (e.g. the PTY is not
+live yet); callers defer and retry rather than dropping the injection.
+
+## The inline bridge pane (CHOO-1674)
+
+A room's conversation can be rendered **inside** switchdash in a `<webview>`, rather than
+sending the user out to a browser. `src/shared/core/switch-rooms/room-embed.ts` resolves
+one of two answers:
+
+- `kind: 'inline'` — a `<webview>` on a partition that already has the Mattermost session
+ cookie installed, with `chromeless` asking the guest preload
+ (`src/preload/mattermost-guest.ts`) to hide the global header and sidebars.
+- **Deeplink** — the room is bridged somewhere we cannot embed (Slack, or a Mattermost we
+ hold no credentials for). The app offers the deeplink **instead of pretending** it can
+ show the conversation.
+
+Two things not to rediscover:
+
+- **Only managed servers can be embedded.** Mattermost embedding needs a port we chose and
+ credentials we hold; an external server's Mattermost is somebody else's deployment.
+- **Mattermost's `/_popout/` route does not work for this.** It looks like the supported
+ way to embed a single channel, but it requires the desktop app's `window.opener` token
+ handshake — under an Electron user agent the web app ignores our session cookie and
+ bounces to a login page. The ordinary channel URL is loaded and the surrounding chrome
+ hidden instead. The decision sits behind one resolved value so swapping strategies later
+ touches that module and nothing else.
+
+`room-embed-layer.tsx` keeps at most `MAX_LIVE_EMBEDS` (4) live webviews once visited —
+each is a real renderer process, so this trades memory for instant switching and drops the
+oldest beyond a handful.
+
+## When editing here
+
+- Changing session startup? Check whether `src/sidecar/` needs the same change.
+- Changing what reaches a session's environment? Both sides build that separately.
+- See `agents/architecture/remote-execution.md` for hosts, reachability, and the sidecar.
diff --git a/dash/agents/conventions/versioned-schemas.md b/dash/agents/conventions/versioned-schemas.md
index a4a18fcc3..cef9b62ec 100644
--- a/dash/agents/conventions/versioned-schemas.md
+++ b/dash/agents/conventions/versioned-schemas.md
@@ -219,8 +219,14 @@ For Drizzle column helpers, use the exported `parseVersionedColumn` and
## All migrated columns
+These are the columns currently bound with `versionedJsonColumn()` in
+`src/main/db/schema.ts`:
+
| Column | Schema file | Versioning |
|--------|-------------|------------|
-| `workspaces.config` | `src/shared/core/workspaces/workspace-config.ts` | v1 → v2 → v3 (versioned from start) |
-| `workspaces.data` | `src/shared/core/workspaces/workspace-provider-data.ts` | unversioned (v0) |
-| `conversations.config` | `src/shared/core/conversations/conversation-config.ts` | unversioned (v0) |
+| `agents.provider_config` | `src/shared/core/agents/agent-provider-config.ts` | v1 (versioned from start) |
+| `sessions.config` | `src/shared/core/sessions/session-config.ts` | unversioned (v0) |
+
+The `workspaces.*` and `conversations.config` columns this table used to list are gone —
+both tables were dropped when the location/session model replaced the upstream
+project/workspace/conversation model. See `agents/architecture/data-model.md`.
diff --git a/dash/agents/risky-areas/database.md b/dash/agents/risky-areas/database.md
index 4c4abeeda..9d12982b1 100644
--- a/dash/agents/risky-areas/database.md
+++ b/dash/agents/risky-areas/database.md
@@ -130,9 +130,8 @@ guidance.
| Column | Schema file |
|--------|-------------|
-| `workspaces.config` | `src/shared/core/workspaces/workspace-config.ts` |
-| `workspaces.data` | `src/shared/core/workspaces/workspace-provider-data.ts` |
-| `conversations.config` | `src/shared/core/conversations/conversation-config.ts` |
+| `agents.provider_config` | `src/shared/core/agents/agent-provider-config.ts` |
+| `sessions.config` | `src/shared/core/sessions/session-config.ts` |
### Snapshot columns and raw SQL
diff --git a/dash/agents/workflows/testing.md b/dash/agents/workflows/testing.md
index 81c2e2afc..b9756c45c 100644
--- a/dash/agents/workflows/testing.md
+++ b/dash/agents/workflows/testing.md
@@ -23,12 +23,14 @@ pnpm run test
- Vitest config is in `vitest.config.ts` (separate from the build config in `electron.vite.config.ts`).
- Five test projects:
- - `node` — `src/**/*.test.ts` excluding `_*` dirs, browser tests, migration tests, `*.db.test.ts`, and `src/main/db/legacy-port/**/*.test.ts`
- - `main-db` — `src/main/core/**/*.db.test.ts` and `src/main/db/legacy-port/**/*.test.ts` against real SQLite
+ - `node` — `src/**/*.test.ts` excluding `_*` dirs, browser tests, migration tests, and `*.db.test.ts` under `src/main/core/` and `src/main/db/`
+ - `main-db` — `src/main/core/**/*.db.test.ts` and `src/main/db/**/*.db.test.ts` against real SQLite
- `fixtures` — fixture generator, run via `pnpm run db:fixtures`
- `migrations` — `src/main/db/tests/migrations/**`, run via `pnpm run test:migrations`
- `browser` — `src/renderer/tests/browser/**/*.test.{ts,tsx}` via Playwright
- `pnpm run test` runs the `node`, `main-db`, `migrations`, and `browser` projects.
+- Both project globs still mention `src/main/db/legacy-port/`, which no longer exists. The
+ globs are harmless but match nothing — do not go looking for that directory.
- Tests use per-file `vi.mock()` setup.
- Integration-style tests create temporary project directories in `os.tmpdir()`.