Node guide

1 · Deploy & verify

Deploy with Coolify (Docker Compose stack or standalone Dockerfile.coolify — see the repository's docs/COOLIFY-DEPLOYMENT.md), or run the binary directly on your own machine (loopback by default, no token needed).

curl https://your-domain/v1/health
# {"status":"ok","uptimeSeconds":…,"nodeVersion":"…","protocolVersion":"1"}

Health and version are the only unauthenticated endpoints — metadata only, safe for orchestrator probes.

2 · Secure remote administration

1. Generate a high-entropy token on the server: openssl rand -hex 32
2. Set it as environment variable HOMICORE_NODE_ADMIN_TOKEN (Coolify: environment variables of the stack) and redeploy.
3. Use HTTPS for your domain — the token only works over TLS.
4. Open /admin remotely: the sign-in screen takes a username (a local label only — the server never records it) and the admin token, which is the actual credential. The session lasts for the browser session; use Sign out to end it.

Wrong tokens are rate-limited (10 failures → 5-minute lockout). Lost token: generate a new one and redeploy — there is deliberately no unauthenticated recovery path. From the machine itself, http://127.0.0.1:7441/admin needs no token.

3 · Add a local model runtime

The node never downloads models and never exposes the runtime's port. Install the runtime next to the node:

• Own machine: install Ollama (or LM Studio / llama.cpp), pull a model, and let guided setup detect it on loopback.
• Container deployment: run Ollama as a service in the same Docker network (compose block is in docker-compose.yaml), pull the model in the Ollama container terminal, and point the node at it:

HOMICORE_NODE_ALLOW_PRIVATE_NETWORK_RUNTIMES: "true"
HOMICORE_NODE_CONFIG: '{"runtimes":[{"id":"ollama","kind":"ollama","endpoint":"http://ollama:11434"}]}'

Endpoints must be loopback, Unix sockets, or (opted-in) same-host private networks. Public addresses are refused even when opted in, and hostname resolution is re-validated on every connection — the endpoint can never drift to the public internet (ADR-0023).

4 · Guided setup & certification

In the console click Run guided setup: it detects the runtime, selects a model, runs a bounded test inference (must return schema-conformant JSON), then runs certification against the synthetic corpus (tiers R1 read-only / R2 structured / W1 proposal-eligible).

• Certification binds to the model digest — replacing a model requires re-certification.
• Callers can demand a tier via bounds.minTier; the node enforces it against the live certification view (stale digest = uncertified → 422 certification_below_minimum).

5 · Pair devices (phones, apps)

1. Console → Pair device — a one-time code appears (short expiry, single use, rate-limited).
2. Enter the code on the device. Verify the node fingerprint the device shows against the server certificate — out-of-band if possible. Pairing is only as trustworthy as this check.
3. The device receives its own client certificate. Every request authenticates with it; revoke any client anytime from the console list.

6 · Link the HomiCore gateway (HRP)

The HomiCore cloud connects through Pair HomiCore gateway — the same one-time-code flow with role gateway. The cloud is never more trusted than a phone: no database access, no bearer tokens, no connector secrets exist on this node (ADR-0011).

• The gateway calls /v1/infer, optionally demanding bounds.minTier.
• The node returns bounded, schema-conformant results. Grounding, evidence checks, and safety stay in HomiCore — the node has no household facts.
• Wire contract: docs/protocol/ai-node-protocol-v1.md (until Program A10 reconciliation).
• No silent fallback: if the node is unreachable, that is the gateway's decision to handle. The node contains no cloud-inference client at all.

7 · Away from home (relay)

Remote device access uses the outbound relay: the node dials out to your relay over WebSocket — nothing listens publicly, no router port forwarding ever.

HOMICORE_NODE_RELAY_ENABLED=true
HOMICORE_NODE_RELAY_URL=wss://relay.example.com/ws
HOMICORE_NODE_RELAY_NODE_ID=my-node-1

The relay sees only encrypted tunnel bytes. Status: console "Remote access" card or /v1/relay/status.

8 · Day-to-day operations

9 · Troubleshooting

10 · What this node will never do

Store the household database · hold bank credentials · execute PendingActions or smart-home controls · give the model shell, filesystem, or internet access · silently fall back to cloud inference. A request for any of these is a boundary violation, not a missing feature (docs/planning/product-boundary.md).