jackin-remote design research (run on another machine, attend from laptop)

Design dossier backing 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

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

Sources:

• README — multicode-remote
• Source — remote/src/main.rs (the multicode-remote binary entry point)
• Source — remote/src/orchestration.rs (SSE relay, file sync, symlink dereferencing)
• Source — lib/src/remote_action.rs (handler-relay protocol — RemoteActionRequest)
• Config — config.toml [remote] block (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

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

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.

[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

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.

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

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 existing as the local dispatch target.

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 remains the right owner for that deeper grant model.

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

• 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.

Related work

• jackin-remote — the roadmap item this dossier backs.
• Agent Orchestration Program
• Operator handler system
• Credential source pattern
• Session contract and explain mode