ArcLink

ArcLink is a Sovereign Control Node for operating Raven, Captain onboarding, fleet inventory, Docker ArcPod deployments, Academy workflows, provider routing, and the Telegram/Discord bridges around Hermes agents.

The public install surface is now one lane:

./deploy.sh control install
./deploy.sh control upgrade
./deploy.sh control health

The bare shortcuts are intentionally mapped to the same Control Node lane:

./deploy.sh install     # control install
./deploy.sh upgrade     # control upgrade
./deploy.sh health      # control health

The old Shared Host/systemd installer and the public Shared Host Docker menu are retired. Fleet growth now happens by registering worker machines with the Control Node and placing ArcPods as Docker deployments on those workers. ArcPods as Docker deployments on registered fleet workers are the supported fleet shape. For production remote workers, prefer a self-owned private mesh such as WireGuard for --ssh-host and --wireguard-private-ip; SSH executor allowlists and machine-mode guards still apply. Control install/reconfigure prepares the Control Node WireGuard keypair, endpoint metadata, and a WireGuard-bound private control URL for remote ArcPod API, share-broker, and inference traffic. Worker join generates worker-local WireGuard keys, writes the worker config, and appends the fleet SSH key without replacing authorized_keys, modifying sshd_config, or changing port 22. Tailscale remains useful as an access overlay or first-contact/domain alternative, but it is not the primary production dependency. When a Captain's Crew can span machines, configure ARCLINK_FLEET_SHARE_HUB_URL only when overriding the default WireGuard SSH git hub. Normal remote workers derive ssh://arclink@<control-wg-ip>/<fleet-share-root>/{user}/fleet-shared.git so Fleet Shared stays unified without another operator prompt.

Current Architecture

Layer	Purpose	Primary commands
Sovereign Control Node	Hosted API, web control plane, Raven, Stripe/billing rails, public bots, fleet inventory, provisioning, admin actions, Academy, inference routing.	./deploy.sh control install, upgrade, health, logs, ps, ports
Fleet Inventory	Expandable worker inventory for local, Hetzner, Akamai/Linode, and SSH-managed machines.	./deploy.sh control register-worker, ./deploy.sh control inventory ...
ArcPods	Captain deployments placed by the Control Node onto registered Docker-capable workers.	Control provisioner/action worker, dashboard, Raven, fleet commands
Operator	Platform owner/admin surface. Operator Raven owns powerful control commands; Operator Hermes runs as a first-class Control Node stack service, not a Captain ArcPod.	Operator Telegram/Discord, ./deploy.sh control ..., /upgrade, /action_status
Hermes Agent Runtime	Captain and Operator agent homes, plugins, skills, MCP, qmd, vault, memory synthesis, dashboard access, and command menus maintained by ArcLink installers.	bin/install-deployment-hermes-home.sh, rollout/upgrade rails

The Control Node still uses Docker Compose internally. The old ./deploy.sh docker ... public mode remains retired; use ./deploy.sh control ... so the Operator has one control center and ArcPods stay under fleet management.

The production web/control surface lives in web/ as the Next.js Control Node app. Do not add a parallel arclink-frontend/ checkout in this repo; that legacy Vite/Bolt app is not part of the deploy, build, or test lane.

Control Node Quick Start

git clone <arclink-repo-url> arclink
cd arclink
./deploy.sh control install

Install collects:

• product/site URLs and ingress mode (domain or tailscale)
• Stripe and hosted API settings
• Telegram/Discord Raven/public bot settings
• Operator Raven channel and allowlist
• fleet deployment style (single-machine, hetzner, akamai-linode, or control-plane only)
• LLM router defaults, allowed models, fallback models, and replacement policy

After install, verify:

./deploy.sh control health
./deploy.sh control ps
./deploy.sh control ports

Register and inspect workers:

./deploy.sh control fleet-key
./deploy.sh control register-worker
./deploy.sh control register-worker --hostname worker-1 --ssh-host 10.44.0.11 --bootstrap-remote --bootstrap-ssh-host 203.0.113.10 --bootstrap-ssh-user root --ssh-user arclink --json
./deploy.sh control inventory list
./deploy.sh control inventory health --json
./deploy.sh control inventory probe-all --json

The interactive worker flow asks for the inventory hostname and first-contact SSH host, then ArcLink derives the WireGuard endpoint, assigns the tunnel IP, publishes the private control URL, joins the worker, syncs the peer, and smoke-tests the private mesh. Set ARCLINK_FLEET_REGISTER_ADVANCED_PROMPTS=1 only for unusual networks.

Upgrades

Use Control Node upgrade for normal code deployments:

./deploy.sh upgrade

Pinned component upgrades still use config/pins.json as the source of truth:

./deploy.sh pin-upgrade-notify
./deploy.sh pins-check
./deploy.sh hermes-upgrade-check
./deploy.sh hermes-upgrade [--ref REF]
./deploy.sh qmd-upgrade-check
./deploy.sh qmd-upgrade [--version V]

Component apply commands commit/push the pin change when configured and then re-enter ./deploy.sh upgrade, which now means Control Node upgrade. Operator Raven mirrors this safely: /upgrade_policy [component] explains the contract, /pin_upgrade <component> confirm queues an active detector payload with concrete target pins, and /upgrade_sweep confirm queues all pending stateless detector payloads while holding stateful services for an explicit maintenance-window flag.

Retired Modes

These public modes are intentionally retired:

• ./deploy.sh install interpreted as a Shared Host/systemd/per-Unix-user installer
• ./deploy.sh upgrade interpreted as a Shared Host host-mutating upgrade
• ./deploy.sh docker ... as a Shared Host Docker control center
• old operator-led enrollment commands that provisioned per-user Unix accounts

Lower-level scripts for migration, tests, and installer reuse may still exist in the tree. They are not the public product install path.

Operator And Captain Boundaries

Captain-facing language uses Raven, Captain, Crew, ArcPod/Pod, and Agent. Operator is reserved for platform/admin/deploy surfaces.

Isolation goals:

• Captains receive isolated ArcPods and Hermes homes.
• Fleet workers are registered inventory controlled by the Control Node.
• Operator Raven can queue audited system actions such as upgrades and repairs.
• Operator Hermes is a single in-stack Control Node service set owned by the operator identity, not a Captain-style multi-agent bundle and not a Captain ArcPod placed by the sovereign worker.
• Shared vault, qmd, Notion, dashboard, plugin, terminal, code, and drive access must stay scoped through ArcLink’s generated credentials and MCP rails.

Organization Profile

arclink-ctl org-profile is the shipped operator CLI for the build, validate, preview, apply, and doctor workflow:

./bin/arclink-ctl org-profile build
./bin/arclink-ctl org-profile validate
./bin/arclink-ctl org-profile preview
./bin/arclink-ctl org-profile apply --yes
./bin/arclink-ctl org-profile doctor

Private organization profiles belong under arclink-priv/config/; public examples must stay fictional.

Validation

Focused checks:

python3 tests/test_deploy_regressions.py
python3 tests/test_documentation_truths.py
python3 tests/test_arclink_operator_raven.py
python3 tests/test_arclink_operator_agent.py

Broad checks:

./bin/ci-preflight.sh
./test.sh

Live proof remains credential-gated. Local tests and dry runs must not be reported as live customer provisioning proof.