Legion connector

The connector runs your local OpenCode agent as a remote executor for a task in a Legion Hub Room. It is meant for machines where the work has to happen on the machine itself — for example deploying to your own server.

Why

Your production SSH keys, root access and LLM subscription never leave your machine. The connector opens an outbound WebSocket to your Hub, receives a task, hands it to the OpenCode agent installed locally, and reports status, questions and the final result back over the same socket. There is no inbound port and no credential shared with the Hub.

Requirements

• Node.js >= 18.17
• OpenCode installed and working on the machine (opencode on PATH), version 1.18 or newer, 1.x or 2.x — see OpenCode versions.
• A Legion Hub you can reach over wss:// (or ws:// for a local Hub).

Install

Get a pairing code in the Hub UI ("Connect an external agent" on an agent's card), then on the target machine:

git clone https://github.com/MyLegionOnline/legion-connector.git
cd legion-connector
./install.sh <pairing-code> wss://your-hub.example.com/api/v1/connector/ws

On Linux with systemd the script creates a dedicated system user for the connector, legion-agent with uid 59999 (--user NAME and --uid N change them; it refuses root and a uid that another account or running process already has). It copies the package to /opt/legion-connector (owned by root, so the agent cannot change its own connector), builds it, writes a default ~legion-agent/.legion-connector/connector.toml with work_dirs set to ~legion-agent/work, exchanges the pairing code for a refresh token as that user, and installs a systemd unit that runs as that user so the connector survives reboots. The code is single-use and expires after 15 minutes.

Then sign OpenCode in to a model provider as the same user, since OpenCode keeps its credentials per user:

sudo -iu legion-agent opencode auth login

Without systemd (macOS, for example) the script sets the connector up for the current user; run it as a dedicated user yourself (see below).

Manual steps (what install.sh automates):

npm ci
npm run build
npm prune --omit=dev
node dist/index.js pair <pairing-code> --hub-url wss://your-hub.example.com/api/v1/connector/ws
node dist/index.js start

Configuration

Edit ~/.legion-connector/connector.toml (see connector.example.toml) before the first real task. Credentials (the refresh token) live separately in ~/.legion-connector/credentials.json, so the policy file is safe to keep in version control. Paths can be overridden with LEGION_CONNECTOR_HOME, LEGION_CONNECTOR_CONFIG and LEGION_CONNECTOR_CREDENTIALS.

Safety: the agent runs with your rights

OpenCode executes commands on your machine with the permissions of the user the connector runs as. Treat every task the way you would treat a command typed by someone with access to your Hub Room, and reduce the blast radius:

• Run the connector as a dedicated unprivileged system user whose uid is not used by any other process on the machine, containers included. Processes inside Docker containers run under host uids too (often 1000), and a user that shares the uid can read their /proc/<pid>/environ (API keys, tokens) and send them signals. useradd hands out the first free uid from 1000 on, so pick one explicitly. install.sh does this for you (legion-agent, uid 59999, checked against existing accounts and running processes); by hand it is sudo useradd --system --uid 59999 --create-home legion-agent, then check with ps -eo uid,comm | awk '$1==59999' that nothing else runs under it.
• Copy opencode.example.json to <work_dir>/opencode.json. Its permission.bash rules make OpenCode ask before rm, systemctl restart and similar commands; each "ask" appears as a confirmation card in the Hub chat, and reboot / shutdown are denied.
• Copy AGENTS.example.md to <work_dir>/AGENTS.md to give the agent the house rules (back up a config before changing it, report what was changed, restarted and health-checked).
• Set work_dirs in connector.toml to the directories the agent may work in (absolute paths). A task runs in the first entry; a directory suggested by the Hub is used only if it lies inside one of the entries, and a request that points elsewhere — including through .. or a symlink — is refused with an error frame before OpenCode is started.
• List risky command prefixes in confirm_ops (default: rm, systemctl restart, systemctl stop). The connector passes them to OpenCode as ask rules (also behind sudo), added after your opencode.json, so they win over an allow there. If OpenCode does not report the rules as active, the task is refused instead of running unconfirmed. Forbid commands outright with deny in opencode.json and do not list them in confirm_ops, which would turn that deny into a confirmation.
• Variables sent by the Hub (Room variables) reach the agent's environment, but names that would change the agent's own behaviour (, , , and similar) are ignored.

work_dirs decides where the agent starts, not what it does afterwards: OpenCode can still read or run things outside that directory unless its own permissions forbid it. Keep opencode.json strict and the connector's user unprivileged.

Revoking the connector in the Hub UI takes effect immediately: its access token can no longer be refreshed.

This is the beginning of the README. Read the rest at the original. Read the full README ↗