Cross-Machine Coordination

Run agents on remote machines. Your laptop runs the TUI. A workbench, GPU box, or cloud instance runs the agents. One grid, multiple hosts.

How It Works

Two modes of initech, one binary:

• TUI mode (initech) runs on your machine. Normal TUI with local panes, plus connections to remote daemons. Remote panes appear in the same grid as local ones.
• Headless mode (initech serve) runs on the remote machine. Launches agents in PTYs, listens on TCP, streams terminal output to connected TUI clients. No rendering, no UI.

MacBook (TUI mode)                    Workbench (headless mode)
+-----------------------------+        +-------------------------+
| initech                     |  TCP   | initech serve           |
|                             |<------>|                         |
| super       [local]        | :7391  | eng1  [local PTY]       |
| pm          [local]        |        | eng2  [local PTY]       |
|                             |        | eng3  [local PTY]       |
| workbench:eng1 [R]         |        +-------------------------+
| workbench:eng2 [R]         |
| workbench:eng3 [R]         |
+-----------------------------+

Remote agents display as host:agent [R] in the TUI grid, ribbon, and overlay. You navigate between local and remote panes uniformly with Alt+arrows. Keyboard input to a focused remote pane flows over the TCP connection.

Setup Walkthrough

1. Remote machine (workbench)

Install initech, create a project directory, and configure for headless mode:

$ curl -fsSL https://initech.sh/install.sh | bash
$ mkdir myproject && cd myproject
$ initech init

Edit initech.yaml to configure headless mode:

project: myproject
root: /home/you/myproject
peer_name: workbench
mode: headless
listen: ":7391"
token: your-shared-secret
roles:
    - eng1
    - eng2
    - eng3

Start the daemon:

$ initech serve
  Listening on :7391 (peer: workbench)
  Started eng1, eng2, eng3

The daemon launches agents and waits for TUI clients. Agents keep running even when no client is connected.

2. Local machine (laptop)

In your project's initech.yaml, add a remotes block pointing to the workbench:

project: myproject
root: /Users/you/myproject
peer_name: laptop
roles:
    - super
    - pm
remotes:
    workbench:
        addr: "192.168.1.100:7391"
        token: your-shared-secret

3. Launch

$ initech

The TUI starts local agents (super, pm) and connects to the workbench. Remote agents (eng1, eng2, eng3) appear in the grid alongside local ones. You're now running 5 agents across 2 machines from one terminal.

Addressing Remote Agents

Use host:agent format for cross-machine communication:

# Send from laptop to workbench agent
$ initech send workbench:eng1 "fix the auth bug"

# Peek at a remote agent
$ initech peek workbench:eng2 -n 10

# Remote agent sends back to local
$ initech send laptop:super "[from eng1] ini-42: ready for QA"

Bare names (without host:) always resolve to local agents. No implicit cross-machine routing.

Use initech peers to see all connected machines and their agents:

$ initech peers
  PEER        AGENTS
  local       super pm
  workbench   eng1 eng2 eng3

Auto-Reconnect

If the network drops, the TUI automatically reconnects to the remote daemon. Remote agents are marked as disconnected in the grid until the connection is restored. No agent work is lost on the remote side because the PTYs never stopped running.

On reconnect, the daemon replays recent terminal output for each pane so you see current content immediately, not a blank screen that fills in over time.

Daemon Persistence

The headless daemon keeps agents running when no TUI client is connected. You can disconnect your laptop, close it, and reconnect later. This is analogous to how tmux server persists when the client detaches, but with initech's agent awareness and message delivery guarantees.

Security

Cross-machine connections are authenticated with a shared bearer token. Both sides must use the same token value. The token is sent during the connection handshake and validated before any data is exchanged.

The transport is raw TCP with no application-level encryption. This is designed for trusted networks:

• Tailscale / WireGuard VPN: Traffic is already encrypted at the network level. The token prevents unauthorized clients on the same tailnet.
• Trusted LAN: Machines on the same physical network. The token is the access control.
• Untrusted network: Use SSH tunneling (ssh -L 7391:localhost:7391 workbench) and set listen: "127.0.0.1:7391" on the daemon so it only accepts local connections.

The daemon can control agent processes (start, stop, restart) and inject text into their terminals. Treat the token like a password.

Last updated: April 2026