🔗 resource

Standalone host-pool resource SSOT — owns the .resource DSL format, the parser, the roster CRUD CLI, the lint/audit/selftest plumbing, and (in progress) the hexa:// URL scheme infrastructure.

.resource is the registry of reachable targets; hexa:// is the URL transport that invokes against that registry. Both live here so the two evolve together.

In addition to the registry layer, this repo ships:

• tool/resource_init.sh — one-shot bootstrap for a fresh Mac + ubu pool (binary wrappers, rsx deploy, ML stack, self-hosted WireGuard mesh).
• bin/{hexa-r,claude-r,py-r,rr,hxr,hexa-tcp,py-tcp} — offload wrappers for routing local invocations to a resource host.

Install

hx install resource

(Short form resolves via the default probe orgs — dancinlab is in hx orgs. Use hx install dancinlab/resource if your HX_ORGS is overridden to exclude it.)

Quick start — fresh laptop or new ubu peer

~/core/resource/tool/resource_init.sh ubu-1 ubu-2

Idempotent. Re-running is safe (skips anything already in place). What it sets up automatically:

Layer	Mac side	Per ubu
zsh / ssh ControlMaster	sources bin/aliases.zsh, ensures ~/.ssh/cm	—
binary wrappers	python3 / hexa / hexa_interp* / claude versions	—
offload symlinks	hxr / rr / claude-r / hexa-r / py-r → ~/.local/bin	—
rsx (cross-built ELF)	cross-compile via hexa build	scp → ~/.local/bin/rsx, verify
ML stack	—	uv (astral), torch nightly cu128, tool/host_deps.txt
WireGuard provisioning	brew install wireguard-tools, keypair, write wg-{ubu1,ubu2}.conf + -fb.conf	apt install wireguard, keypair, /etc/wireguard/wg0.conf, wg-quick@wg0
DuckDNS pusher	—	(designated host only) /etc/cron.d/duckdns 5-min IP push, token from secret CLI

WG operational lifecycle (up/down/health, audit emit, policy gate) belongs to dancinlab/ghost mk2.cond.1 — ghost wg-self up ubu1 etc. resource-init only handles provisioning: install + keygen + conf write + systemd enable. The Tailscale-rejection rationale lives in ghost cpre/scope.ai.md ("Operator infra coordination must not create fixed metadata leak").

1-time manual steps (can't be automated)

1. Router port-forward (admin page → NAT → port-forwarding):
   • UDP 51234 → ubu-1 LAN IP UDP 51820
   • UDP 52345 → ubu-2 LAN IP UDP 51820
2. DuckDNS (optional fallback when home IP rotates):
   • sign up at https://www.duckdns.org, add a subdomain, copy token
   • secret set duckdns.subdomain then secret set duckdns.token
3. SSH config (~/.ssh/config) — resource-init prints a Match-exec stanza you append manually (user-sensitive file, never auto-edited):

   Match host ubu-1 exec "ping -c1 -W1 192.168.50.119 >/dev/null 2>&1"
       HostName 192.168.50.119
   Host ubu-1
       HostName 10.142.0.1
       User aiden
   

   With this, ssh ubu-1 uses LAN IP at home, falls through to WG IP from outside — no alias change needed.

Skip the entire WG block: RESOURCE_INIT_SKIP_WG=1 resource-init …. Skip the ML provision block: RESOURCE_INIT_SKIP_PROVISION=1 resource-init ….

The topology table (WG_PEERS) at the top of tool/resource_init.sh is the single edit point for IP / external port mapping.

CLI surface

resource — host-pool registry

resource list                  # show host pool (reachable + load + mem + nexus)
resource status [host]         # detailed health (ssh + nexus + claude + slots)
resource add <host>            # probe + bootstrap disclosure
resource remove <host>         # unregister
resource fix <host>            # nexus shim auto-repair + claude bin probe
resource oauth-status <host>   # per-slot OAuth health
resource oauth-reset <host>    # slot-pool reset disclosure
resource sync <host> --tool <path>   # rsync local Mac canonical → host
resource patch <host> --tool <path> --content-b64 <b64>   # ssh + base64 heredoc
resource exec <host> --command "<cmd>" --c3 "<rationale>" # cross-host exec
resource bootstrap <host>      # zero-touch bootstrap (delegates to RM4)
resource log [tail-n]          # tail audit ledger
resource --selftest            # canonical-form sanity (no host I/O)

Universal kind registry (operates on $HIVE/spec/sync_registry.spec.yaml):

resource list <kind>           # dump rows for a kind
resource list kinds            # enumerate registered kinds
resource add <kind> <name> [k=v ...]    # register a row
resource remove <kind> <name>  # delete a row
resource verify [<kind>]       # child-exec each handler with --verify
resource apply  [<kind>]       # child-exec each handler with --apply

Offload wrappers (bin/)

Routes a local invocation to a resource host over ssh (or TCP for specific paths). All wrappers honor a global kill switch (touch ~/.resource-off) and a per-invocation bypass env var.

Wrapper	Routes	Bypass env
hexa-r <host> <subcmd> [args]	hexa run/parse/test/... to <host> (TCP for local *.hexa, ssh otherwise)	RESOURCE_LOCAL_HEXA=1
py-r <host> <args>	python3 invocation to <host>	RESOURCE_LOCAL_PY=1
claude-r <host> [args]	full Claude TUI session over ssh -t	RESOURCE_LOCAL_CLAUDE=1
rr <host> <command...>	generic ssh exec	(no bypass — explicit by definition)
hxr <args>	wildcard pass-through to hxr-r family	—
hexa-tcp <script.hexa> [args]	submit local .hexa to TCP compute server (tcp/server.py)	—
py-tcp <script.py> [args]	submit local .py to TCP compute server	—

After resource-init mac-side runs, all wrappers are symlinked into ~/.local/bin (PATH-visible). The binary wrappers (e.g. python3, hexa run) intercept invocations by all callers (agent Bash, scripts, launchd) — not just shell aliases — and route them via the wrappers above by default.

Pure-pull TCP compute

# server (run on a worker host)
python3 tcp/server.py --bind 127.0.0.1 --port 5555 --worker tcp.workers:echo_worker

# tunnel (Mac side)
./tcp/ssh_tunnel.sh ubu-1 5555

# clients
python3 tcp/client.py ping
./bin/py-tcp   path/to/script.py
./bin/hexa-tcp path/to/script.hexa

See doc/compute-pull-tcp.md and tcp/README.md.

Configuration

After install, edit ~/.hx/packages/resource/.resource to declare your host inventory. Replace the example blocks with actual SSH aliases, remote homes, capabilities, and scoring weights. Keep the resource state deferred until the entry is ready to participate in pool routing, then flip to live.

Path resolution

The shim self-locates the package root via $0 (POSIX-portable symlink walk), so it works for any user installing via hx install regardless of $HOME path layout.

Resolution priority:

1. $RESOURCE_ROOT env var (explicit override)
2. self-located via $0 — resolves to ~/.hx/packages/resource on hx install

Boundary with hive

This repo owns .resource format + parser + CLI + scorer/LB libraries + (in progress) hexa:// URL scheme. Hive (~/core/hive) keeps the runtime decisions on top: nexus-kick orchestration, zero-touch bootstrap chain, TS bridge, hexa://sync/* and hexa://gate/* verb bodies. See doc/boundary.md for the full contract.

Dependencies

• hexa interpreter (~/.hx/bin/hexa) — install via hx install hexa.
• wireguard-tools (Mac: brew, ubu: apt) — auto-installed by resource-init.
• secret CLI (~/core/secret/bin/secret) — used for DuckDNS token storage (token never lands on argv or shell history).
• ghost: optional, but recommended for audit + policy gate. See ghost mk2.cond.1.

License

MIT.