control

module
v0.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 14, 2026 License: MIT

README

Control

A Go peer execution network for Windows, Linux, and macOS. Connect machines to a gateway, then address them by name through the CLI, MCP, or local HTTP API.

An orchestrator coordinates work through a client. Worker nodes execute it and exchange files directly. The gateway handles enrollment, discovery, signaling, encrypted relay fallback, and fleet administration. Orchestrator and worker are operation roles, not fixed machine types. AI agents are optional callers or providers.

What it does

  • Private user fleets with persistent machine identities and names.
  • Direct WebRTC connections with WebSocket relay fallback and mutually authenticated TLS on both paths.
  • Durable tasks with idempotent submission, cancellation, streamed logs, and restart reconciliation.
  • Commands, scripts, AI CLIs, MCP servers, and opt-in GUI automation.
  • SHA-256 artifacts, resumable downloads, and direct worker-to-worker delivery.
  • Forward/reverse TCP tunnels, private-network HTTP requests, and explicit clipboard pastes.
  • Leases, bounded parallel workflows, a live dashboard, and idle-only managed updates.

Account-authenticated clients initiate execution. Workers can request peer work only through instruction-bound orchestrator delegation. Fleet membership alone permits discovery, not execution. See authority and delegation.

Install the gateway on a Linux VPS

Use the Linux VPS guide for a complete Ubuntu/Debian installation: install the verified binary, create a private operator key, run the gateway as an unprivileged systemd service, configure HTTPS with Caddy, and provision a user account.

Point a domain at the VPS and allow TCP 80/443. Keep the gateway's listener on 127.0.0.1:7330 behind the reverse proxy. The operator creates accounts with control users create NAME and gives each user only their own account key. Do not distribute the gateway superuser key to workers.

Install the orchestrator CLI

Linux or macOS:

curl -fsSL https://raw.githubusercontent.com/koltyakov/control/main/scripts/install.sh | sh

Windows, from PowerShell, CMD, or Bash:

powershell.exe -NoProfile -c "irm https://raw.githubusercontent.com/koltyakov/control/main/scripts/install.ps1|iex"

On Windows, open a new terminal to pick up the saved PATH. The installers require published GitHub release assets.

Log in with the account key supplied by your gateway operator:

control login --gateway https://control.example.com
control install-mcp opencode
control install-skill opencode
control machines
control dashboard

Login validates and saves your gateway URL and key. The integration commands above target OpenCode; see MCP and skills for other clients. Scripts and human CLI users can skip the integrations. Remote work needs no local node:

control exec worker -- hostname
control call worker node.describe

To make this machine an execution host and configure an AI client:

control setup --name main --client opencode

Setup reuses your saved login and installs node startup, MCP, and the Control skill. On Windows, default setup requires Administrator PowerShell; use --service user for startup at your login under your normal account. Supported AI clients include OpenCode, Claude Code, Cursor, Copilot, Codex, Windsurf, Antigravity, and generic agents.

Install workers on Windows, macOS, and Linux

control machines add win-worker --platform windows --service user
control machines add mac-worker --platform macos --service user
control machines add linux-worker --platform linux --service system

Run each printed installation command on its target. Windows uses PowerShell under the intended user and requests UAC for firewall setup. macOS uses Bash in that user's terminal. The Linux system-context command uses sudo and requires systemd. Installers detect amd64/arm64, verify the binary, redeem the invitation, and start the node. No worker login or account key is needed. Verify enrollment with control machines and control call win-worker node.describe from the orchestrator.

Use auto, or omit the name, to select the target's hostname. Invitations are single-use and expire after 15 minutes by default. You can also press a in the dashboard. See platform requirements and worker startup.

If a pending invitation reserves a name, use machines add NAME --platform OS --force or machines rename OLD NAME --force to retract its URL immediately. The dashboard offers f and asks for confirmation on this conflict. Force does not take over another enrolled identity.

User context runs with the installing user's files and credentials, but can stop after logout. System context starts at boot and survives logout. Linux/macOS system nodes run as root; Windows uses LocalService. Choose the context deliberately, especially for desktop tools. See installation and startup.

Run and inspect work

control exec worker --detach --id job-001 --timeout 4h -- COMMAND ARG...
control task logs worker job-001 --follow
control task wait worker job-001
control task cancel worker job-001

Stopping a wait or log follower does not cancel accepted work. Interrupted tasks are not automatically replayed after a node restart. Use a new task ID for new work.

control system worker
control system worker --refresh
control speedtest worker --size 64 --json
control artifact export worker input.mp4
control artifact get worker ARTIFACT_ID ./output.mp4

Resource sampling is separate from dashboard polling. Connection tests run only when requested. Artifact downloads retain partial files after interruption, resume by offset, and verify SHA-256 before publication. See the protocol reference for capability calls, grants, and workflows.

Install MCP and skills

Run the pair for your AI client on the orchestrator. MCP exposes Control tools; the skill teaches the client how to use the CLI. You can install either independently. Both default to global installation.

# OpenCode
control install-mcp opencode
control install-skill opencode

# OpenAI Codex
control install-mcp codex
control install-skill codex

# Claude Code
control install-mcp claude
control install-skill claude

# Generic agents using .agents
control install-mcp agents
control install-skill agents

Other client selectors are cursor, copilot, windsurf, and antigravity. Use the same commands with that name. Add --project . to either command for project-local installation, then restart the AI client to reload its configuration and skills.

The generic agents target writes ~/.agents/mcp.json and ~/.agents/skills/control/SKILL.md, or their project-local .agents equivalents. Your client may need to import that MCP config manually. See all supported selectors and configuration paths.

For another MCP-compatible client, configure a stdio server to run /absolute/path/to/control mcp. It uses the saved account login without a local node. Ask your AI client to work on a named machine; use durable tasks for long operations. Explicit --api or CONTROL_API selects local-node authority and cannot independently initiate peer execution.

Build and test

Go 1.27.2 or newer is required. Builds have no CGO dependency.

make build
make fmt-check
make lint
make check
make test-compose

make test-compose runs an isolated gateway, three nodes, and cross-container checks over WebRTC and relay, including an FFmpeg workflow. Docker supplies Go and application dependencies. Run make help for other development targets and see testing for focused checks and performance benchmarks.

Updates

control update updates the invoked CLI from GitHub Releases. Running nodes use the gateway's separate managed rollout. With saved superuser authorization, make update pushes a development bundle to the gateway and enrolled nodes; make update-status reports progress. Actual managed restarts require idle reservations. See managed updates.

Documentation

Limits and trust

Control uses a single gateway, without clustering, public signup, billing, or execution sandboxing. Providers run with their node's OS permissions. Keep account keys and gateway state out of worker-accessible locations, and keep the local node API on loopback. The gateway is trusted for naming, fleet membership, and executable distribution. See security boundaries.

Licence

MIT

Directories

Path Synopsis
cmd
control command
control-bundle command
control-bundle builds cross-platform bundles consumed by the update API.
control-bundle builds cross-platform bundles consumed by the update API.
internal
buildinfo
Package buildinfo identifies the running binary, independently of protocol version.
Package buildinfo identifies the running binary, independently of protocol version.
client
Package client implements the orchestrator's CLI/MCP component, routing calls through a local node API or a standalone authenticated client session.
Package client implements the orchestrator's CLI/MCP component, routing calls through a local node API or a standalone authenticated client session.
clipboard
Package clipboard accesses the user's desktop clipboard and streams explicit file pastes.
Package clipboard accesses the user's desktop clipboard and streams explicit file pastes.
dashboard
Package dashboard presents pool activity without tying monitoring to a single CLI invocation or task owner.
Package dashboard presents pool activity without tying monitoring to a single CLI invocation or task owner.
enrollment
Package enrollment defines single-machine installation invitations.
Package enrollment defines single-machine installation invitations.
gateway
Package gateway implements enrollment, discovery, signaling, encrypted relay fallback, and fleet administration.
Package gateway implements enrollment, discovery, signaling, encrypted relay fallback, and fleet administration.
installation
Package installation manages per-user node configuration and background startup.
Package installation manages per-user node configuration and background startup.
node
Package node implements the enrolled execution service.
Package node implements the enrolled execution service.
rpa
Package rpa defines the desktop helper contract shared by nodes and MCP clients.
Package rpa defines the desktop helper contract shared by nodes and MCP clients.
secrets
Package secrets stores worker-local credentials.
Package secrets stores worker-local credentials.
store
Package store provides crash-safe writes for small local metadata records.
Package store provides crash-safe writes for small local metadata records.
system
Package system samples host resources independently of dashboard refreshes.
Package system samples host resources independently of dashboard refreshes.
transport
Package transport provides mutually authenticated, multiplexed peer sessions over WebRTC data channels or the gateway's WebSocket relay.
Package transport provides mutually authenticated, multiplexed peer sessions over WebRTC data channels or the gateway's WebSocket relay.
update
Package update implements verified binary staging and managed rollout messages.
Package update implements verified binary staging and managed rollout messages.
wire
Package wire frames JSON control messages without consuming streamed payloads.
Package wire frames JSON control messages without consuming streamed payloads.
workgate
Package workgate provides atomic admission and idle maintenance reservations.
Package workgate provides atomic admission and idle maintenance reservations.
wsio
Package wsio provides reusable message storage for serial WebSocket readers.
Package wsio provides reusable message storage for serial WebSocket readers.
Package skills embeds the CLI instructions shipped with Control.
Package skills embeds the CLI instructions shipped with Control.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL