Product identity: HiveControl

Central ecosystem site: https://hive.neural-forge.io

Product page: https://hive.neural-forge.io/hivecontrol

HiveControl

Owner-consented, capability-gated AI control for a real laptop.

Created by Travis Curnutte

---

What this is

HiveControl is a public, reusable pattern for giving an AI agent practical control over a personal laptop while keeping that control explicit, inspectable, and recoverable.

It packages the workflow we built from real use:

• terminal and filesystem operations
• browser automation and visual QA
• desktop/app automation where the OS allows it
• messaging gateway control from mobile or chat apps
• outbound relay control for machines behind NAT
• remote worker lanes for secondary machines
• canary-based readiness checks before claiming anything works
• durable skills and memory so the agent gets better every time

The goal is not "an agent with vague access." The goal is an owner-operated control plane where every capability is proven before use and every risky surface has a documented boundary.

---

The one-sentence architecture

A local Hermes agent runs with owner-approved tools on the laptop; optional relay clients connect outbound to a relay hub; every command path is gated by auth, process supervision, canary checks, and a clear rule: do not claim control until the machine proves it executed the command.

Owner
  │
  ├── CLI / IDE / Discord / Telegram / API
  │       │
  │       ▼
  │   Hermes Agent on laptop
  │       │
  │       ├── terminal + file + browser + vision tools
  │       ├── OS automation adapters
  │       ├── local services under launchd/systemd
  │       └── optional outbound relay client
  │                 │
  │                 ▼
  │            Relay Hub
  │                 │
  │                 ├── remote Mac/Linux relay
  │                 └── Windows/WSL relay worker
  │
  └── Audit trail: logs, canaries, Memory Hive, skill updates

---

Why this exists

Most "computer control" demos stop at a browser or a toy shell. Real laptop control needs more:

1. The agent must know which machine it is controlling.
2. It must verify the live system instead of trusting stale memory.
3. It must distinguish transport success from execution success.
4. It must survive restarts, sleeps, dropped WebSockets, and remote workers going offline.
5. It must never publish secrets or private host details when turned into public docs.
6. It must gracefully degrade. If the remote machine is offline, show fewer slots and keep working locally.

HiveControl is the skill and documentation layer for that reality.

---

Quick start for Hermes users

Clone the package, run its self-tests, then copy the skill into your Hermes skills directory:

git clone https://github.com/TJCurnutte/hive-control.git
cd hive-control
python3 scripts/test-package.py
mkdir -p ~/.hermes/skills/devops/hive-control
cp skills/devops/hive-control/SKILL.md ~/.hermes/skills/devops/hive-control/SKILL.md

The support docs, scripts, and templates stay in the cloned repo. The SKILL.md is the installable Hermes skill; the repo is the operator handbook.

Then start a new Hermes session and load it:

hermes -s hive-control

Ask for a capability check:

Load hive-control and run the readiness checklist for this machine. Redact secrets.

Expected result: the agent checks OS, current user, tools, browser availability, service state, relay status if configured, and returns a capability matrix instead of guessing.

---

What the skill teaches the agent

The skill tells an agent how to:

• bootstrap safely on a laptop
• discover live machine state
• use local tools without hallucinating file/process facts
• operate browser and desktop UI workflows
• route remote commands through an outbound relay
• prove remote readiness with executable canaries
• degrade when remote workers disappear
• document changes and update durable memory/skills
• avoid publishing private operational details

It is written for Hermes, but the principles apply to any tool-using agent.

---

Capability matrix

Capability	Local laptop	Remote relay	Proof required
Shell command	Yes	Optional	stdout/stderr/exit code
File read/write	Yes	Optional	read-back or checksum
Browser automation	Yes	Optional	DOM/console/screenshot evidence
Desktop automation	OS-dependent	OS-dependent	visible UI state or app response
Messaging gateway	Optional	Optional	real inbound/outbound canary
AI subagent spawn	Yes	Optional	exact response token
Background service	launchd/systemd	launchd/systemd	service status + restart proof
Remote worker lane	Optional	Yes	status + platform + shell + Hermes canary

The key rule: status alone is not enough. A relay that is connected but only ACKs messages is not executable. The skill requires command output, file proof, or an exact Hermes response before using that route.

---

Install patterns

1. Local-only control

Use this when the agent only needs the current laptop.

hermes doctor
hermes tools list
hermes config check

Recommended Hermes toolsets:

• terminal
• file
• browser
• vision
• session_search
• skills
• memory
• cronjob when scheduled work is needed

2. Messaging/mobile control

Install the Hermes gateway and enable your messaging platform:

hermes gateway install
hermes gateway setup
hermes gateway restart
hermes gateway status

Production checklist:

• require an owner allowlist
• enable only the needed platform(s)
• test a real message from the actual client
• keep tokens in .env, never in public docs
• log every terminal/control command with timestamp and platform

3. Outbound relay control

Use an outbound relay when a controlled machine is behind NAT or WSL2.

Controlled machine -> outbound WebSocket -> relay hub <- client/owner

Relay clients authenticate as type: "auth"; browser/API clients authenticate as type: "client_auth". This distinction matters. If a machine connects with client_auth, it may receive auth_ok but it will not appear as a relay or receive targeted commands.

4. Remote worker lane

A remote worker should be a bounded lane, not a second unsupervised editor of the owner laptop.

Good remote work:

• research
• review
• Windows/WSL checks
• long-running validation
• artifact generation in a remote temp directory

Avoid by default:

• editing the laptop's active git repo
• changing shared skills or memory directly
• using remote results as "done" without verification

---

Readiness checklist

Before an agent says "I have full access," it should run checks like these.

Local checks

date
uname -a
whoami
pwd
hermes doctor

The agent should also verify the specific task surface it needs:

• files: read target paths before editing
• git: check branch/status/diff before committing
• browser: load page, inspect console, verify DOM/screenshot
• services: check process/service state before restarting

Relay checks

Replace <RELAY_CLIENT> with your relay client command, for example a local script, npm binary, or platform-specific bridge client.

# status: is the relay present?
<RELAY_CLIENT> <relay-id> status

# platform: did the remote executable answer?
<RELAY_CLIENT> <relay-id> platform

# shell: did the remote execute a command?
<RELAY_CLIENT> <relay-id> shell 'printf REMOTE_SHELL_OK'

# Hermes: did the remote agent answer exactly?
<RELAY_CLIENT> <relay-id> hermes 'Reply exactly: REMOTE_HERMES_OK'

Expected evidence:

• relay appears with the expected ID
• platform fields come from the remote machine
• shell stdout contains the exact token
• Hermes returns the exact token

If any step fails, route around that capability and report the degraded state.

---

Security model

HiveControl assumes the owner intentionally grants local control, but it still treats the laptop as a high-trust environment.

Non-negotiables

• Do not publish secrets.
• Do not claim remote execution from ACK-only responses.
• Do not run destructive commands without an explicit owner request and current-scope verification.
• Do not let public docs include private hostnames, relay tokens, bearer tokens, API keys, tunnel URLs, or personal paths.
• Keep remote workers in worker lanes unless a lease explicitly grants broader scope.

Recommended boundaries

• Store secrets in .env, keychain, or platform secret stores.
• Use owner allowlists on gateways.
• Use separate tokens for relay hub, IDE API, and messaging platforms.
• Keep relay services under launchd/systemd with restart policies.
• Log control-plane commands with enough context to audit later.
• Prefer exact canary tokens over subjective "it works" checks.

---

Relationship to MemoryHive and HiveSwarm

HiveControl is the control layer. It pairs naturally with:

• MemoryHive: durable memory and learning across agents. HiveControl writes lessons back after non-trivial work.
• HiveSwarm: hardware-aware orchestration. HiveControl can expose verified local and remote lanes for HiveSwarm to schedule.

A simple mental model:

MemoryHive   = what the agents remember
HiveSwarm    = how work is distributed
HiveControl = what the owner-approved machines can actually do

---

Repository layout

hive-control/
├── README.md
├── SPEC.md
├── LICENSE
├── .gitignore
├── manifest.json
├── skills/
│   └── devops/
│       └── hive-control/
│           └── SKILL.md
├── docs/
│   ├── ARCHITECTURE.md
│   ├── SECURITY.md
│   ├── TROUBLESHOOTING.md
│   └── GITHUB_PUBLISHING.md
├── scripts/
│   ├── doctor.sh
│   └── sanitize-check.py
└── templates/
    ├── control-plane.config.example.yaml
    ├── launchd.relay.example.plist
    ├── relay.env.example
    └── systemd.relay.example.service

---

Common failure modes

Relay appears online but commands fail

Cause: the relay may only be acknowledging messages, or the client/server message type is wrong.

Fix: require shell and Hermes canaries. Do not treat status as execution proof.

Remote machine is on Tailscale but not in the relay

Cause: network reachability does not mean the relay bridge is running.

Fix: restart the bridge service on the remote machine and verify it authenticates as type: "auth" with the expected stable relay ID.

Agent uses stale memory about the machine

Cause: memory describes previous environments; the live execution environment may be different.

Fix: the skill requires live tool checks for OS, ports, processes, files, and time.

Public docs leak private implementation details

Cause: copying operational notes directly into GitHub docs.

Fix: run python3 scripts/test-package.py and python3 scripts/sanitize-check.py --self-test, then replace private values with placeholders.

---

Publishing checklist

Before making a repo public:

• Run python3 scripts/test-package.py.
• Run python3 scripts/sanitize-check.py --self-test and python3 scripts/sanitize-check.py.
• Confirm all tokens are placeholders.
• Confirm no private hostnames, private IPs, or personal local paths are required for use.
• Confirm templates use <PLACEHOLDER> style values.
• Confirm README explains owner consent and safety boundaries.
• Confirm the skill file passes Hermes frontmatter validation.
• Create the GitHub repo.
• Push only the public package, not local runtime files.

Suggested repo name:

gh repo create hive-control --public --source . --push --description "Owner-consented AI laptop control skill and relay control-plane pattern"

---

License

MIT. Use it, fork it, adapt it, and keep the safety model intact.