mirror of
https://github.com/Ark0N/Codeman.git
synced 2026-10-02 13:39:41 +02:00
Codeman maintainer
bd286bf502
The wiki was written for seven run modes and never received Grok Build, DeepSeek Harness or OMP. They now appear everywhere the others do: the modes table and per-CLI notes, install commands, environment prefixes, the Quick Start table, the requirements rows, the vocabulary, and every "seven modes" count. The 1.27 to 1.29.0 changes land on the pages that own them: attaching a case to an existing container, multi-case adoption and the copy-a-case picker (Docker Cases); file reads over ssh in remote cases and what stays unavailable (Remote SSH Sessions, Working With Files, Security); single-page app routing, frame recovery, localhost links as tabs and the egress guard (Web Tabs); DeepSeek as the one non-Claude mode with real stop/blocked signals and Approvals items, Codex's own work detection, last-response, the model-endpoint routes and refreshed counts (HTTP API, Driving From An Agent, Hooks, Notifications, Keeping Agents Running, Core Concepts); Shift+drag, right-click copy, Auto Copy, the Ctrl+Z guard, font weight, the vertical rail and its activity sort (Keyboard Shortcuts, Input And Voice, The Dashboard, Settings Reference); the 600px phone cutoff, Codex shift arrows and iPhone Duo (Mobile Guide); the Docker Compose route and its update rule (Installation, Running As A Service); four new symptom entries and a "which CLIs" question (Troubleshooting, FAQ). Custom model endpoints are deliberately left to #430, which adds that page and edits Agent CLIs, Settings Reference and the sidebar; these edits stay out of the regions #430, #428 and #376 touch, and all three still merge cleanly on top. Both READMEs: the web-tab menu entry is labelled "Add URL" in the UI, not "Add dashboard". Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
113 lines
5.6 KiB
Markdown
113 lines
5.6 KiB
Markdown
# Remote SSH Sessions
|
|
|
|
Point a case at another machine and the agent runs **there**, with the same dashboard,
|
|
mobile UI, and autonomy features. Your laptop becomes a window onto a session living on the
|
|
remote host.
|
|
|
|
Like Docker, this is a **location overlay** on a case, not a run mode. All ten run modes
|
|
work remotely. See [Core Concepts](Core-Concepts).
|
|
|
|
## Why bother
|
|
|
|
The agent runs where the work is: a build server, a NAS, a GPU box, a machine reachable only
|
|
through a jump host. Your laptop can sleep, change networks, or close, and the run continues.
|
|
|
|
## Setting it up
|
|
|
|
**Add Case → Remote**:
|
|
|
|
| Field | Notes |
|
|
| --------------------- | -------------------------------------------------------------------- |
|
|
| **Host** | Hostname or IP. |
|
|
| **Username** | The SSH user. |
|
|
| **Port** | Defaults to 22. |
|
|
| **Identity file** | `~` and `$HOME` are expanded for you. |
|
|
| **Jump host** | The `-J` equivalent, `[user@]host[:port]`. |
|
|
| **SOCKS proxy** | For hosts reachable only through a proxy. |
|
|
| **Extra SSH options** | Any `KEY=VALUE` options your normal connection needs. |
|
|
| **Remote path** | The working directory on that machine. |
|
|
|
|
Hosts are saved and reusable, so a second case on the same machine is just a path. Host
|
|
profiles can also carry per-run-mode launch command overrides, for when the binary lives
|
|
somewhere unusual on that host.
|
|
|
|
The remote host needs **tmux**. Codeman probes for it when you link the host rather than
|
|
failing later at launch.
|
|
|
|
## What actually runs
|
|
|
|
The agent lives inside a dedicated tmux server on the **remote** host, and Codeman fronts it
|
|
with a local tmux pane running `ssh`.
|
|
|
|
That two-layer arrangement is what makes it durable: a dropped SSH connection, a network
|
|
change, or a closed laptop kills the local pane, not the remote session. Reconnecting lands
|
|
back in the same live conversation.
|
|
|
|
The remote session name is deliberately chosen so that a Codeman **running on the target
|
|
host** will not adopt it as one of its own. Two Codemans, one host, no interference.
|
|
|
|
## Auto-reconnect
|
|
|
|
A watcher with bounded backoff notices a dead SSH pane and quietly reattaches to the still
|
|
running remote session. On by default; the kill switch is in
|
|
**App Settings → Agents & CLIs → Remote auto-reconnect**.
|
|
|
|
Intentional kills are never revived. Closing a session means closing it. Neither is a clean
|
|
exit inside the pane (Ctrl-D, `exit`, Ctrl-C at the CLI's prompt): that tears the remote
|
|
tmux session down, and the watcher revives a session only when that durable session is
|
|
verifiably still alive. Only a transport drop is reconnected.
|
|
|
|
## Discover and attach
|
|
|
|
Codeman can list the `codeman-*` sessions already running on a host, whether that machine's
|
|
own Codeman started them or another operator did, and attach to one.
|
|
|
|
The distinction that matters:
|
|
|
|
| Session | On tab close |
|
|
| ------------ | ------------------------------------------------ |
|
|
| **Launched** | Killed, like any local session. |
|
|
| **Attached** | **Detached, never killed.** |
|
|
|
|
Attaching to someone else's session and closing your tab must not end their run, so it does
|
|
not. Several clients can attach the same remote session at different window sizes without
|
|
clamping each other, and discovery shows a shared badge with the client count.
|
|
|
|
## Files
|
|
|
|
Previews, downloads and text reads in a remote case go over the same ssh connection the
|
|
session uses, so a clicked path opens the file on the machine the agent is on, `Range`
|
|
seeking included. Nothing is copied to the Codeman host. Editing, Office previews,
|
|
thumbnails, the file tree and the tail viewer are not available remotely and answer a clear
|
|
400 rather than a misleading 404. Details in [Working With Files](Working-With-Files).
|
|
|
|
## Security
|
|
|
|
Every SSH command line in Codeman flows through one builder that shell-escapes every
|
|
user-supplied field: identity paths, jump hosts, proxy commands, and extra options. That is
|
|
the entire injection surface, and it is deliberately a single function rather than string
|
|
concatenation spread across the codebase.
|
|
|
|
Host, path, and identity fields are schema-validated on top of that.
|
|
|
|
Codeman does not store SSH passwords. Use keys, as you would for any other automation.
|
|
|
|
## Gotchas
|
|
|
|
- **The remote host needs tmux.** Probed at link time, so you find out immediately.
|
|
- **The local working directory is meaningless** for a remote session, and is not used.
|
|
- **Run flows must go through the quick-start path** for remote cases. This matters if you
|
|
are driving Codeman over the API: the plain session-create endpoint validates the working
|
|
directory locally and has no case concept, so it will reject or misroute a remote case.
|
|
- **Latency is SSH latency.** Local echo helps the typing feel, but a slow link is a slow
|
|
link.
|
|
- **Transcript-backed features follow the transcript.** Subagent windows and similar surfaces
|
|
read files on the machine where the agent runs.
|
|
|
|
## Read next
|
|
|
|
- [Core Concepts](Core-Concepts) - overlays versus run modes.
|
|
- [Docker Cases](Docker-Cases) - the other overlay.
|
|
- [Security](Security) - the wider model.
|
|
- [`docs/remote-sessions.md`](https://github.com/Ark0N/Codeman/blob/master/docs/remote-sessions.md) - the full design.
|