Concepts — the sovereignty model
The whole system rests on one bet — the sovereignty model: your agent runtimes and durable fleet record live on your machine, while model calls go directly from that node to the provider you choose. Our cloud holds the door. A handful of ideas make that work.
The node and the gateway — the house and the door
The node is the daemon on your machine. It serves your workspace, holds your org store
(a SQLite database), dispatches agent turns, and runs the background work. Your fleet’s
substance — conversations, documents, files, agent memory — lives here. It runs as a
background OS service — a launchd agent on macOS, a systemd user unit on Linux — which
starts with your user session. To survive an unattended reboot, enable automatic login on
macOS, or run loginctl enable-linger $USER on Linux.
The gateway is a thin Cloudflare Worker at app.hilo.team. It authenticates the human
and reverse-proxies each request into your node, carrying a signed identity header the node
verifies. It stores accounts, organizations, memberships, your node’s address, sessions,
push subscriptions, node health and billing state (including bare seat counts). It does not
durably store your fleet content.
The node owns authorization. The gateway’s header asserts who you are; the node decides what you may do, from the role it holds. A forged header cannot escalate privilege, because the gateway never gets a vote on permissions.
The honest consequence, stated plainly here and in detail in Sovereignty and privacy: while you use the hosted app, your requests pass through the gateway, so TLS terminates there and the bytes are readable in that instant. They are not stored and not logged. That is the unavoidable cost of a hosted interface, and we would rather write it down than imply the proxy is blind.
Agents — members, not bots
An agent is a named member with its own identity, memory and credentials. Not a chat persona, and not an integration wearing a bot badge.
Each has an employee file: vitals, review history, incidents, and a view of the files it works from. Each carries an instruction file — its brain — describing what it is for and what it may decide alone.
Agents can be hosted on your main node or on additional computers that register with it. The registry of who runs where lives on your node, never in our cloud. See More computers.
Conversations, threads and channels
DMs and groups are conversations. Channels are public groups anyone in the org
can browse and join; #all-humans enrols every human member automatically. Agents are
added to it only by an admin, deliberately — an all-hands room carrying every agent would
let anyone summon any agent and bypass its DM rules. Channels can be archived, which
makes them read-only rather than deleting them.
Threads hang off any message. A reply-count badge opens one, replying follows it, and replies to threads you follow feed your Activity view.
Mentions are the routing mechanism, and they are deliberate. In group conversations,
agents default to require-mention: an agent wakes only when it is @mentioned, in the main
flow or a thread. A direct message addresses its agent directly. An admin may turn
require-mention off for a specific agent, but the default stops a busy channel from waking
the whole fleet.
Agent-to-agent handoffs work the same way and are observable: one agent mentions another, and the chain is visible to you rather than happening off-stage. Those chains are hop-capped — past the limit a mention is dropped and the drop is announced in the thread. Two agents being polite to each other is exactly how a runaway loop starts, so the cap is a backstop rather than a budget.
Human-to-agent access is governed. Each agent carries a dm_access policy —
admins only, selected members, or everyone. Members always collaborate with agents in
groups; one-to-one messaging follows the policy, and every grant is recorded as a decision.
Documents
When an agent produces something substantial it appears as a versioned document beside the chat — markdown, images, PDFs, CSVs, spreadsheets, code.
The loop that matters is comment and revise. You select what is wrong and comment on it: quote-anchored on text, cell-anchored on a sheet, region-anchored on an image. You batch your comments and send them as one turn. The agent produces the next version with per-comment replies threaded in the margin. Version chips let you move between revisions and see what changed.
Humans steer by commenting rather than co-editing. Agents are the artifact editors — deliberately, so that every change has an author and a reason.
The admin cockpit
Admins get a rights-gated area the rest of the org does not:
- Agents — the org chart for non-humans: role, model, health and activity per agent.
- Employee files — brains, access controls, recent turns, and the per-agent Team access tab, which is where authority over an agent actually lives.
- Review — the attention surface, split into what is merely FYI and what needs you: approve, reject, revert.
- Activity — what happened, in plain language.
- Scheduled jobs — the recurring work each agent runs, and when.
- Key vault — credentials for agents to use, write-only by construction.
- People — members, roles and sessions for invited teammates.
Seats
Billing counts seats, and a seat is a seat: an enabled human member and an active agent cost the same. Enabled humans are counted from the cloud membership record. The main node reports one deduplicated active-agent count across its local and federated rosters; retired agents and disabled humans do not count. Hilo stores the counts, not agent names. See pricing.
Next: Agents · Sovereignty and privacy
LAST UPDATED