Agents — create, govern, maintain

An agent in Hilo is a member of your organization with a name, a role, an instruction file and a history you can read. This page covers creating one, governing it, and the parts that decide whether a fleet is useful or exhausting.

Two ways to create an agent

From the admin area — Admin → Agents → + New agent. The “Hire an agent” flow asks who the agent is and what routine it owns. The answers are written into its instruction file, and the agent is ready when the form closes.

From the CLI, when you would rather it interview you:

hilo agent new <name> --owner <you>

A CLI-created agent is born carrying an interview section: its first conversations are spent working out what it is for, drafting its own standing instructions, and — the part that matters — asking for what it needs rather than granting it to itself. When you are satisfied:

hilo agent ratify <name>

This splices the interview section out — a deterministic edit, not a hand-cleanup. In the workspace the same act is the Confirm button on the agent’s card; the CLI verb keeps its name.

Why an agent never self-grants. A new agent is created by a human who does not yet know what it will be, talking to an agent that does not know either. That is precisely the moment to be strict, so everything an agent decides about itself — its purpose, its access, its authority — goes to a human.

Connecting an existing agent. In the workspace this is Connect existing agent: give Hilo the one directory the agent lives in — browse to it or type the path — and it previews the portable instructions, memory and skills it would copy. Nothing goes live until you press Confirm. Hilo copies; it never moves or alters the original, so you can always walk away with the agent you started with.

The same flow exists on the CLI as a proposal an operator reviews. The copying agent pipes its JSON report into the proposal command:

hilo adopt propose < adoption-report.json
hilo adopt list
hilo adopt ratify <name>

The brain file

Every agent has an instruction file describing who it is, what it owns, how it should work, and what it may decide without asking. It is a plain file on your disk, in your fleet’s home, readable and editable by you.

This is the thing that makes an agent a colleague rather than a prompt. A good one carries:

• Identity and role — what this agent is for, and what is explicitly not its lane.
• Standing rules — the corrections you have already made, written down so they are not relearned.
• The escalation line — what it decides alone, and what comes to you.

Keep it short enough that it is worth reading. An instruction file nobody maintains drifts into fiction, and an agent following stale instructions confidently is worse than one asking.

Permissions and access

dm_access governs who may message an agent one-to-one: admins only, selected members, or everyone. Group collaboration is always open to members. Every grant is recorded as a decision in the audit trail.

require-mention controls whether an agent responds to everything in a conversation or only when named. In any busy channel, mention-only is the setting that keeps a fleet affordable.

Both live in the admin area, per agent.

Credentials

Agents need API keys and tokens. Those live in the node’s credential store — never in a brain file, never in a repository:

hilo secrets list                        # names only, never values
printf %s "$TOKEN" | hilo secrets set NAME --agent <agent>
printf %s "$TOKEN" | hilo secrets set NAME  # node-wide
hilo secrets unset NAME
hilo secrets set-file NAME --file PATH   # a credential that must be a file

Hilo never redisplays a value. A scoped value is injected into an authorized agent turn as an environment variable, which means that agent code can read and use it — grant only the credentials you trust that agent with. Credential values are always excluded from Hilo backups; only names and scopes are recorded for recovery. See Backups.

What an agent should decide alone

This is the setting that determines whether a fleet saves you time. Two failure modes:

An agent that asks permission for everything is a slower version of doing it yourself. Every question costs you a context switch, and the fleet becomes a queue.

An agent that never asks is a liability the first time it is confidently wrong about something expensive.

The line most operators land on: anything irreversible, costly, outbound, or outside the agent’s stated lane comes to a human. Everything else gets decided, done and logged. Write that into the brain file rather than hoping it is understood.

Some things are worth making absolute — no production writes, no message to a customer without a human approving it, no spending.

Watching the fleet

hilo observe          # the local wallboard, in the foreground
hilo observe --url    # print the authenticated local URL and exit

The wallboard shows which agents are working, which are idle, and what the scheduled work is doing. The review feed in the admin area is the other half — it separates what is merely informational from what actually needs you.

The failure mode of automation is silence, not error. A scheduled job that stops running looks exactly like a quiet week. Anything you depend on wants something watching it.

Next: More computers · CLI reference

LAST UPDATED 2026-08-22