| name | hive-control |
| description | Use when operating, configuring, auditing, or publishing an owner-consented AI laptop control plane: local terminal/files/browser/desktop control, messaging gateways, outbound relays, remote worker lanes, readiness canaries, and public-safe documentation. |
| version | 1.0.0 |
| author | Travis Curnutte |
| license | MIT |
| metadata | {"hermes":{"tags":["hive-control","computer-control","relay","gateway","macos","wsl","automation","security"],"related_skills":["hermes-agent","outbound-relay","pantheon-ide-debugging","shell-command-automation","github-repo-management"]}} |
HiveControl
Overview
HiveControl is the operating procedure for an owner-approved AI agent that can work on a real laptop. It covers local tools, browser/desktop automation, messaging gateways, outbound relay control, remote worker lanes, verification canaries, and public-safe packaging.
The skill's bias is simple: prove live capability before using it. Memory can say a machine has a relay, a gateway, or full access, but the agent must verify the current system with tools before claiming the route works.
When to Use
Use this skill when the user asks you to:
- control or audit their laptop
- run local terminal/files/browser/desktop tasks
- configure Hermes for mobile or Discord/Telegram control
- inspect or repair a relay/gateway/remote worker lane
- decide whether a remote machine should appear in a swarm
- publish the hive-control pattern as a public GitHub skill/project
- harden a personal AI control plane
Do not use this skill as permission to act outside the user's current request. It explains how to operate verified capabilities; it does not override user scope, safety rules, or platform policy.
Core Principles
- Owner consent first. The control plane exists because the owner intentionally grants access.
- Live state beats memory. Always check the actual machine for OS, processes, files, ports, services, and time-sensitive facts.
- Transport is not execution. Relay status or ACKs do not prove commands ran. Require shell output, file proof, or an exact Hermes canary.
- Degrade honestly. If a remote lane is offline, clamp capacity and continue local-only instead of pretending the lane exists.
- Keep public docs sanitized. Do not publish tokens, private hostnames, local auth values, relay URLs, private paths, or user-specific operational details.
- Leave an audit trail. For non-trivial work, log what changed, what was verified, and what remains degraded.
Capability Discovery Sequence
Run only the checks relevant to the task, but keep this order when diagnosing a full control plane.
1. Local identity and OS
date
uname -a
whoami
pwd
Use terminal tools for current facts. Never answer OS/time/process/ports from memory.
2. Hermes health
hermes doctor
hermes config check
hermes tools list
hermes gateway status
If Hermes is not on PATH, locate it with the user's known install path or shell profile, then verify with an exact command.
3. Local automation surfaces
Check only the surfaces required for the task:
- file operations: target path exists, permissions, git status
- terminal operations: command availability and versions
- browser operations: page loads, DOM state, console errors
- desktop automation: OS permissions for screen recording/accessibility if needed
- messaging: gateway connected and a real platform canary succeeds
4. Services and supervision
On macOS:
launchctl list | grep -E 'hermes|relay|gateway|pantheon'
On Linux/WSL:
systemctl --user --type=service --state=running | grep -E 'hermes|relay|gateway|pantheon'
A service listed as loaded is not enough. Check logs and run a canary through the service path.
Local Laptop Operations
File edits
- Inspect the target file with
read_file.
- Use
patch for targeted edits or write_file for full new files.
- Run syntax/tests.
- Re-read or run a verification command.
- Summarize only the files touched by this task.
Git work
Before changing a repo:
git status --short
git branch --show-current
git rev-parse --short HEAD
Do not overwrite unrelated dirty work. If the repo is already dirty, patch only the requested paths and report the pre-existing dirty state separately.
Browser and UI work
Use browser tools when a visual or runtime condition matters. A correct UI fix should usually verify:
- page loads
- DOM state matches expected labels/counts
- browser console has no new JS errors
- screenshot/vision confirms visible layout when visual styling matters
Desktop automation
Desktop automation is OS- and permission-dependent. Treat it as best-effort until proven. Use visible confirmation or app state as proof, not just a command exit code.
Messaging Gateway Control
Use gateways for owner-controlled mobile/chat access.
Production checklist:
- owner allowlist configured
- message-content/intents enabled where required
- platform command tested from the actual client
- high-risk slash commands are deterministic direct runners when possible
- terminal/relay commands return stdout, stderr, and exit code
- logs redact tokens
Gateway success means a real inbound message or slash command produced a real response. Command sync alone is not enough.
Outbound Relay Pattern
Use a relay for machines behind NAT, on a different network, or inside WSL2.
controlled machine -> outbound WebSocket -> relay hub <- owner/client
Relay connections must authenticate as type: "auth". Client connections authenticate as type: "client_auth". If a machine uses client_auth, it can appear authenticated but will not be counted as a relay.
Relay readiness proof
A remote lane is ready only after all of these pass:
status shows expected relay ID online.platform-info returns real remote platform fields.shell returns an exact stdout token.shell can write and read a proof file if filesystem access is required.hermes returns an exact response token if remote AI work is required.- service supervision confirms it can survive restarts/sleep where relevant.
Example canaries, replacing <RELAY_CLIENT> with your relay client command:
<RELAY_CLIENT> <relay-id> status
<RELAY_CLIENT> <relay-id> platform
<RELAY_CLIENT> <relay-id> shell 'printf REMOTE_SHELL_OK'
<RELAY_CLIENT> <relay-id> hermes 'Reply exactly: REMOTE_HERMES_OK'
If shell fails but status works, report the remote as connected but not executable. If Hermes fails but shell works, report the relay as executable but remote Hermes unhealthy.
Remote Worker Lanes
Remote workers are useful, but should not silently become co-owners of the local laptop.
Good default assignments:
- research
- review
- Windows/WSL validation
- long-running smoke tests
- artifact generation under a remote temp path
Avoid unless explicitly leased:
- editing local Mac repos
- changing shared memory/skills directly
- restarting local services from remote
- claiming local artifact completion without Mac-side verification
A good remote-worker instruction includes:
You are a remote worker lane. Do not edit the owner laptop's repo or shared skills. Write artifacts under a remote temp directory and return exact paths plus a summary. Mac/local orchestrator verifies before marking done.
Capacity and Swarm UI Rules
If this skill is used with a swarm UI, display usable capacity, not configured fantasy capacity.
- If the remote relay is live and can execute, show remote slots.
- If the remote relay is configured but offline, hide or zero the remote slots.
- Clamp default swarm count to the live capacity.
- Manual remote selection should either fall back safely or report a structured unavailable state.
- Role planning should not mention remote lanes while remote capacity is zero.
Public Documentation Sanitization
Before publishing a hive-control repo, run a sanitization pass.
Remove or replace:
- API keys and bearer tokens
- Discord/Telegram/Slack tokens
- relay auth tokens
- exact private relay URLs
- local bearer values
- private hostnames
- private IPs unless they are documentation-only examples from reserved ranges
- personal paths that are not needed by public users
- screenshots with notifications or private content
Use placeholders:
<CONTROL_AUTH_TOKEN>
<RELAY_URL>
<RELAY_ID>
<OWNER_USER_ID>
<PROJECT_PATH>
Common Pitfalls
-
Saying "I can talk to remote Hermes" because Tailscale ping works. Tailscale proves network reachability only. It does not prove a relay bridge or Hermes subprocess is running.
-
Trusting relay ACKs. {ok: true, note: received} proves only that a bridge received a message. It does not prove shell/Hermes execution.
-
Forgetting the relay auth type. A worker bridge must authenticate as auth, not client_auth, or it will not appear as a relay.
-
Publishing private operational notes. Public GitHub docs should teach the architecture with placeholders, not expose a working personal control plane.
-
Letting remote lanes edit shared state. Remote workers should propose changes or write artifacts. The orchestrator applies protected changes after review.
-
Skipping UI verification. For browser/desktop changes, tests can pass while the visual surface remains wrong. Use DOM and screenshot checks.
-
Assuming service restarts loaded code. After a restart, run the exact endpoint or canary that proves the new path is live.
Verification Checklist
One-Shot Recipes
Full local readiness report
Load hive-control. Check this machine's current local control readiness: OS, Hermes health, enabled tools, gateway status, relevant services, and any degraded routes. Redact secrets.
Remote relay diagnosis
Load hive-control. Diagnose why relay <RELAY_ID> is not usable. Check relay status, target presence, platform canary, shell canary, Hermes canary, service hints, and explain the first failing layer.
Public release cleanup
Load hive-control. Audit this repo for public GitHub release: scan docs/templates/scripts for secrets/private hostnames/private paths, validate skill frontmatter, run tests, and return a publish checklist.
