hero_codescalers

Multi-user development session management for Linux servers, built on the Hero OS stack.

Overview

hero_codescalers manages Linux user accounts and SSH sessions across a fleet of nodes. State (nodes, admins, groups) is replicated peer-to-peer via iroh-docs. The dashboard UI is reachable over the mycelium overlay network.

Components

Binary	Role
hero_codescalers_server	JSON-RPC 2.0 backend (Unix socket rpc.sock)
hero_codescalers_ui	Web dashboard (Unix socket ui.sock + optional HTTP)
hero_codescalers	CLI — lifecycle management and direct API calls

---

Quick start

# One-time: build and install binaries
service_codescalers install --root

# One-time: set the shared KVS secret (any passphrase)
proc secret set SECRET_CODESCALERS "my shared passphrase"

# Start the service (instance 0, port 5000, mycelium auto-detected)
service_codescalers start --root

# Check status
service_codescalers status --root

---

Multi-instance support

Multiple instances can run side-by-side on the same machine — useful for staging/testing, or when you need isolated namespaces with different KVS secrets.

Port assignment

Ports are assigned automatically — no manual configuration needed:

Instance	HTTP port	Override
0	5000	service_codescalers start --port 9090
1	5001	service_codescalers start --instance 1 --port 9091
N	5000+N	--port <explicit>

Unix socket directories

Each instance gets its own socket directory under $HERO_SOCKET_DIR (default: ~/hero/var/sockets/):

Instance	Socket directory	Paths inside
0	hero_codescalers_server/	rpc.sock, ui.sock
1	hero_codescalers_server1/	rpc.sock, ui.sock
N	hero_codescalers_serverN/	rpc.sock, ui.sock

Hero proc names

Instance	Service name	Server action	UI action
0	hero_codescalers	hero_codescalers_server	hero_codescalers_ui
1	hero_codescalers_1	hero_codescalers_server_1	hero_codescalers_ui_1
N	hero_codescalers_N	hero_codescalers_server_N	hero_codescalers_ui_N

KVS data directories

Instance	Data directory
0	~/hero/var/hero_codescalers/kvs
N	~/hero/var/hero_codescalers_N/kvs

Example: two instances side-by-side

# Instance 0 — primary (port 5000)
service_codescalers start --root

# Instance 1 — secondary (port 5001)
service_codescalers start --instance 1 --root

# Status
service_codescalers status --root
service_codescalers status --instance 1 --root

# Stop secondary
service_codescalers stop --instance 1 --root

---

Mycelium network integration

All instances attach to the mycelium overlay network automatically when the mycelium daemon is reachable. The UI HTTP listener binds to the node's mycelium IPv6 address so the dashboard is accessible from any node on the overlay — not just localhost.

• Detection is attempted for every instance, regardless of --root.
• The mycelium address is in the 400::/7 range; the script validates this.
• If the daemon is unreachable, the service starts in Unix-socket-only mode (no HTTP listener). Pass --address <ipv6> to override.

# Auto-detect mycelium (recommended)
service_codescalers start --root

# Explicit address override
service_codescalers start --address 4f8:306f:d514:7dbd:: --root

# Explicit address + custom port
service_codescalers start --address 4f8:306f:d514:7dbd:: --port 5099 --root

---

UI Access Control

The admin dashboard HTTP listener can be restricted to a whitelist of Mycelium IPv6 addresses. The whitelist is stored in hero_proc secrets under the key ADMIN_SECRETS (context core) as a comma-separated list.

Unix-socket connections are always trusted — hero_router and local tooling are never blocked. Only direct TCP connections (from the Mycelium overlay) are subject to the whitelist.

If hero_proc is not running the whitelist feature is disabled and all TCP connections are allowed.

Managing the whitelist

Via the admin UI (recommended)

Open the dashboard → Admin tab → UI Access Control section:

• "Restrict to me" — adds your current Mycelium address and enables enforcement.
• "Add to whitelist" — manually enter any Mycelium IPv6 address.
• "Open access (allow all)" — clears the list and disables enforcement.

Via the CLI

# Add an address
proc secret set ADMIN_SECRETS "4f8:306f:d514:7dbd:b27c:28aa:d12d:bdb6"

# Add multiple addresses (comma-separated, no spaces around commas)
proc secret set ADMIN_SECRETS "4f8:306f:d514:7dbd:b27c:28aa:d12d:bdb6,4f9:1234:abcd::1"

# View current whitelist
proc secret get ADMIN_SECRETS

# Disable enforcement (clear the list)
proc secret set ADMIN_SECRETS ""

Important: Changes made via the CLI are picked up by the UI binary on the next ui.getAccessList RPC call (triggered automatically when the Admin tab is opened). Changes made via the admin UI are written to hero_proc immediately and take effect for the next incoming TCP connection.

Behaviour summary

hero_proc state	ADMIN_SECRETS value	Result
Not running	(any)	Open access — all TCP allowed
Running	absent or empty	Open access — all TCP allowed
Running	one or more IPs	Restricted — only listed IPs
Any	(unix-socket)	Always allowed (trusted local path)

---

KVS secret

The KVS secret is used to derive the iroh-docs namespace key. All nodes sharing the same passphrase replicate data automatically.

# Set the secret once (any passphrase)
proc secret set SECRET_CODESCALERS "my shared passphrase"

Resolution order on start:

1. HERO_CODESCALERS_KVS_NAMESPACE_SECRET in the caller's environment (used as-is — must be a 64-character hex string).
2. SECRET_CODESCALERS in hero_proc core secrets (fetched automatically, then SHA-256 hashed to the required 64-char hex key).
3. Neither found → hard error with setup instructions.

---

Commands reference

service_codescalers install [--root]

Clones/updates source from forge and runs cargo build --release. Copies binaries to ~/hero/bin (or /root/hero/bin with --root).

service_codescalers start [options]

--root (-r)          Manage root's hero_proc (requires passwordless sudo)
--instance N         Instance number, default 0
--port N             HTTP port, default 5000+instance (0 = auto)
--address <ipv6>     Explicit bind address (overrides mycelium auto-detect)
--reset              Force clean re-register + restart even when running

service_codescalers stop [--root] [--instance N]

Stops and unregisters the specified instance from hero_proc.

service_codescalers status [--root] [--instance N]

Shows the hero_proc service status for the specified instance.

---

CLI direct calls

The hero_codescalers binary also proxies commands directly to the server:

hero_codescalers health
hero_codescalers stats
hero_codescalers user-list
hero_codescalers user-create alice --forge-token TOKEN
hero_codescalers user-delete alice
hero_codescalers session-list
hero_codescalers session-kill alice

# Query a non-default instance
hero_codescalers --instance 1 health
hero_codescalers --instance 1 user-list

# Or point at a specific socket
hero_codescalers --server ~/hero/var/sockets/hero_codescalers_server1/rpc.sock health

Lifecycle via the binary directly

hero_codescalers --start                  # instance 0
hero_codescalers --instance 1 --start     # instance 1, port 5001
hero_codescalers --instance 1 --stop

---

Environment variables

Variable	Required	Default	Description
HERO_CODESCALERS_KVS_NAMESPACE_SECRET	yes	(from secret store)	64-char hex namespace key
HERO_CODESCALERS_KVS_AUTHOR_SECRET	no	auto-generated	64-char hex author key
HERO_CODESCALERS_KVS_SEEDS	no	—	Comma-separated iroh ticket URLs
HERO_CODESCALERS_KVS_DATA_DIR	no	~/hero/var/hero_codescalers/kvs	iroh-docs data directory
HERO_SOCKET_DIR	no	~/hero/var/sockets	Base directory for Unix sockets
HERO_CODESCALERS_SOCK_NAME	no	hero_codescalers_server	Socket subdirectory name
HERO_CODESCALERS_ADDRESS	no	—	UI HTTP bind address (IPv4 or IPv6)
HERO_CODESCALERS_PORT	no	5000	UI HTTP port

---

Build

make build     # cargo build --release
make install   # build + copy to ~/hero/bin
make run       # install + start via hero_proc (instance 0)
make runroot   # install to /root/hero/bin + start as root
make stop      # stop instance 0
make test      # unit tests
make test-kvs  # iroh-KVS integration tests