# jackin-remote design research (run on another machine, attend from laptop) (https://jackin.tailrocks.com/reference/research/agent-orchestration/remote-execution/jackin-remote-design/)



Design dossier backing [jackin-remote](/roadmap/jackin-remote/), the Phase 5 proposal for running agent workloads on a remote host while the operator keeps the local console UX. Nothing here is shipped; this page exists to keep the design rationale out of the roadmap tracker.

## Problem [#problem]

Some agent workloads do not fit on the operator's laptop. A long parallel queue, a CPU-heavy build pipeline, or a memory-hungry indexing job benefits from running on a beefy host while the operator continues to use their laptop normally.

Today, jackin❯ has no remote-host orchestration story. Operators can run jackin❯ over SSH or point Docker at a remote daemon, but those paths do not preserve the local console UX, explicit state ownership, credential posture, or local handler affordances that a first-class remote mode needs.

multicode addresses this with `multicode-remote`: a helper binary that runs the multicode TUI on the local laptop while agents run on a remote machine, with bidirectional rsync of workspace state and SSH-relayed handler invocations.

## Inspiration in multicode [#inspiration-in-multicode]

**Sources**:

* README — [multicode-remote](https://github.com/graemerocher/multicode#multicode-remote)
* Source — [`remote/src/main.rs`](https://github.com/graemerocher/multicode/blob/main/remote/src/main.rs) (the `multicode-remote` binary entry point)
* Source — [`remote/src/orchestration.rs`](https://github.com/graemerocher/multicode/blob/main/remote/src/orchestration.rs) (SSE relay, file sync, symlink dereferencing)
* Source — [`lib/src/remote_action.rs`](https://github.com/graemerocher/multicode/blob/main/lib/src/remote_action.rs) (handler-relay protocol — `RemoteActionRequest`)
* Config — [`config.toml` `[remote]` block](https://github.com/graemerocher/multicode/blob/main/config.toml) (sync intervals, sync-up/sync-bidi mounts, install command)

The useful kernel for jackin❯: SSH control, explicit sync direction, local action relay, and remote bootstrap should be evaluated before inventing a custom network protocol.

## Recommended shape [#recommended-shape]

Use SSH + rsync for V1, designed so future Kubernetes support can reuse the same attach, status, credential, and handler vocabulary. A typed RPC/gRPC client may be cleaner later, but the first remote-host story should work through ordinary SSH-accessible machines and should not wait for cluster orchestration.

```
jackin-remote (local laptop)
   └── ssh ──> jackin (remote host)
       ├── runs agents through the selected remote backend
       └── exposes a small control channel for status events, handler invocation requests, and launch/session lifecycle
```

### Config sketch [#config-sketch]

Remote config should be an explicit remote-host surface, not a silent overload of existing backend config. The exact schema is still open, but V1 needs named remotes with SSH target, remote `jackin` path, sync interval, sync rules, and optional install/bootstrap command.

```toml
[remote.dev-server]
ssh = "user@dev-server.local"
remote_jackin_path = "/usr/local/bin/jackin"
sync_interval_seconds = 2

[[remote.dev-server.sync_up]]
local = "~/.config/jackin"
remote = "~/.config/jackin"

[[remote.dev-server.sync_bidi]]
local = "~/dev/projects"
remote = "~/dev/projects"
exclude = ["target/", "node_modules/", ".jackin/"]

[remote.dev-server.install]
command = "curl -fsSL https://jackin.tailrocks.com/install.sh | bash"
```

### CLI sketch [#cli-sketch]

The original `jackin --remote <name> ...` sketch is still unimplemented in source. Keep the shape open until it is reconciled with backend selection and console launch flows, but V1 needs the same three operator verbs: attach the local console to a remote host, launch a role on a remote host, and sync without launching.

```sh
jackin --remote dev-server console
jackin --remote dev-server load the-architect
jackin --remote dev-server sync
```

### Handler relay [#handler-relay]

When the operator clicks a link in the local console, the action should fire on the local host — browser, IDE, diff viewer — not on the remote machine. V1 needs a structured remote action event such as `RemoteAction { kind: web|ide|diff, argument: url|path }` over the SSH control channel, decoded locally by `jackin-remote` and dispatched through the same local handler paths used by the console. This depends on [Operator handler system](/roadmap/operator-handler-system/) existing as the local dispatch target.

### Credentials [#credentials]

Current auth forwarding (`sync`, `api_key`, `oauth_token`, `ignore`, plus `sync_source_dir`) is a shipped local-backend baseline, not enough for remote hosts. Remote V1 should resolve credentials locally, pass only invocation-scoped grants/material to the remote side, and avoid broad rsync rules that copy credential directories or long-lived tokens into a shared host. The [credential source pattern](/roadmap/credential-source-pattern/) remains the right owner for that deeper grant model.

### Sync contract [#sync-contract]

Every synced path needs an explicit direction and owner. `sync_up` means the local host is authoritative, `sync_bidi` means conflict behavior is part of the contract, and remote-only jackin❯ runtime state stays remote unless the operator requests a recovery copy. Credentials are never included in broad sync rules; they use the credential grant path instead.

## Open design questions [#open-design-questions]

* **State ownership.** Which remote runtime state, if any, mirrors back to the laptop? Recommendation: remote runtime state remains authoritative on the remote host; local copies are recovery/export artifacts only.
* **Status transport.** Should the SSH control channel carry SSE-style lines, framed JSON, or reuse a future jackin❯ protocol stream?
* **Remote plus backend selection.** How does `--remote dev-server` compose with `[runtime].default_backend`, workspace `[runtime].backend`, and future `--backend`? Recommendation: remote chooses the host; backend selection still resolves on that host and must be reported explicitly.
* **Trust model.** A compromised remote can read synced workspaces and any credentials granted to that invocation. Remote-host isolation is not a feature; document the trust boundary plainly.
* **Handler protocol owner.** The local console has browser-opening and link affordances, but no general operator handler system. Decide whether this item owns the first typed handler protocol or depends on [Operator handler system](/roadmap/operator-handler-system/).

## Related work [#related-work]

* [jackin-remote](/roadmap/jackin-remote/) — the roadmap item this dossier backs.
* [Agent Orchestration Program](/reference/research/agent-orchestration/program-research/)
* [Operator handler system](/roadmap/operator-handler-system/)
* [Credential source pattern](/roadmap/credential-source-pattern/)
* [Session contract and explain mode](/roadmap/session-contract-explain-mode/)