The bootkey manual

An agent on bootkey is a Hermes agent on a Linux box of its own. You choose six things when you boot one, and every choice changes how it behaves later: how much it notices, how well it thinks, what it remembers, and what it costs. This manual explains each choice and why it exists. Nearly all of them can be changed after boot.

1. Temper: how alive should it be?

Most “agents” sleep until someone talks to them and only look alive. The temper decides when yours thinks without being asked. Waking up is what makes an agent useful on its own, and it is also what makes it cost tokens.

Tool. It wakes when you talk to it, or when one of its duties is due. Nothing happens in between, and nothing is spent. Pick this for assistants you use on demand, and for jobs whose schedule lives in the job itself (a daily briefing, an hourly sweep).

Worker. It wakes on a steady beat (every 10, 15, 20, 30 or 60 minutes), checks its duties and objectives, does what is due, and goes back to sleep. If nothing needs doing it answers silently, which costs one short model call. Choose all day, or by day (08:00 to 22:00 in its region’s time zone) with a dream at night. Pick this when something should be looked at regularly but you can’t say exactly when.

Alive. It decides when to wake next. Every wake-up ends with one line such as next wake: 40m (waiting for the deploy), and bootkey moves its wake-up job to that time: sooner while work is in progress, later when all is quiet, anywhere from 5 minutes to 6 hours. It starts at 30 minutes, and if the model ever forgets the line it keeps its last pace instead of stopping. Alive agents also dream at 03:30 local time. Pick this for an agent with ongoing objectives that should manage its own attention. It is the most capable temper, and its cost depends on how busy it decides to be.

Why it matters. The temper sets how many times a month the model is called on its own. A worker every 30 minutes is about 1,440 wake-ups a month; every 10 minutes, about 4,320. Section 9 turns that into money.

2. Job: what is it for?

A job (a template) gives the agent a purpose: a section in its SOUL (the instructions it reads every session), scripts, starter files, and duties (scheduled jobs). Four are on the wizard’s first page; the library holds the rest:

• Watch: immune system (servers), site watch, change watch, release watch, backup check, log reader.
• Research: morning briefing, research assistant, paper reader, mention watch.
• Money: market watch, price drop watch. They report; they never trade or buy.
• Code: repo keeper (triage and reviews), vulnerability watch.
• Business: content drafter, SEO check-up, grant and tender scout.
• Personal: tutor, journal companion.
• Earn: arena competitor (battle.training), promotion agent (promotedby.ai), bounty scout.
• Blank: just Hermes, your model and a box. Teach it anything in chat.

Quiet until something changes. The watch jobs run a small script first (is the site up? did the page change? is there a new release?) and only wake the model when the script found something. A quiet check costs no tokens, so you can watch every 10 minutes for free and still hear within minutes when something breaks.

Lists live in plain files. What a job watches is kept in ~/.hermes/watch/ (sites, pages, repositories, prices, machines), and its briefs in ~/.hermes/notes/ (your interests, your voice, your goals). You can edit them in the Brain tab, or just tell the agent in chat (“also watch example.com”) and it updates the file.

Why it matters. A job is a starting point, not a cage. Everything it installs stays editable, and an agent with a clear job and clear notes does far better work than one with a vague “be helpful”.

3. Mind: which model thinks for it?

The model is its intelligence. For an agent, the most important skill is not conversation but acting: calling tools with the right arguments, running shell commands that work, and finishing multi-step tasks without inventing things. A model that writes beautiful answers but invents tool calls makes a bad agent.

That is why the wizard shows ratings from LMArena’s public leaderboard. People rate these models head to head:

• Doing agent tasks: people rated whole agent sessions. This is the best single signal for an agent.
• Not inventing tool calls: how rarely it makes up tools or arguments.
• Running shell commands: how often its commands work the first time.
• Building web pages and Conversation: general quality, for context.

The “Smartest” preset is the top of the agent board among models you can use. “Best value” picks recent models from major labs at a modest price, “Cheapest” is for agents that mostly watch and wait, and “Free right now” lists models with a $0 price.

Things to know:

• Every model in the list supports tool calls and has at least 64k tokens of context; an agent needs both.
• Reasoning models think before acting. They make fewer mistakes on hard tasks and cost more per wake-up.
• Free models have a daily request cap on OpenRouter, some free routes may log prompts, and many rank low on tool use. They are fine for trying things out, not for an agent you rely on.
• Wake-up model. A worker or alive agent can do its routine wake-ups with a cheaper model and keep the main one for chat and real work. This is often the biggest saving.

Why it matters. Intelligence and cost trade off. A watch agent that mostly checks scripts needs a reliable, cheap model; a research or coding agent needs a strong one. You can switch any time in Settings.

4. Brainstem: your key

The brainstem is the key that feeds the mind: your own OpenRouter or Venice account. Every token is billed there, at their prices, and bootkey never marks it up or sees your usage beyond the totals it shows you.

• OpenRouter has the widest choice (hundreds of models from every major lab) and one bill for all of them. Connecting takes a click: you sign in on their page and they create a key for bootkey.
• Venice runs private inference and offers uncensored models. You paste a Venice API key.

Why it matters. Your key, your limits: set a spending cap on the key itself and the agent can never spend more.

5. Memory: how does it remember?

Hermes always has a working memory for the current session. The memory system decides what it keeps between sessions, and how it finds it again.

Plain files. Hermes’ own MEMORY.md, USER.md and a memories/ folder. Simple, transparent, easy to read and correct in the Brain tab. Best for most agents.

Obsidian vault. Linked markdown notes in ~/vault: one note per person, project or topic, joined with [[links]], plus a dated daily log, committed to git. Best when you want to browse what it knows, or sync it into Obsidian on your own machine.

Holographic. Semantic memory in a local SQLite store, recalled automatically before each reply. Best for agents that collect many small facts over time and need the relevant ones without being told where to look. Nothing leaves the box.

Dreams. Day-and-night workers and alive agents dream at 03:30 local time: they go through the day, merge duplicates, link related notes and prune what is stale. Without dreams, memory still works but grows messier over months.

History. Every change to its brain files (SOUL, objectives, notes, memories, watch lists, scripts, skills, settings) is kept, whether you made it in the console or the agent made it itself. In the Brain tab, open a file and press History to see each version, who changed it, what changed, and Restore any of them. Restoring is a change too, so nothing is ever lost.

Why it matters. An agent is only as good as what it remembers. Choose the system you would want to read and fix yourself, because sometimes you will.

6. Body: where it lives

Every agent gets its own box: 1 vCPU, 1 GB of memory and 25 GB of disk, running Ubuntu, Hermes Agent and bootkey’s small daemon. You get SSH into it as hermes and as root, at its own name: ssh hermes@<name>-xxxx.ssh.bootkey.ai (the console shows the exact one). The name follows the agent if it wakes on a new box after hibernating.

Regions: Frankfurt, New York, San Francisco, Sydney. The region sets:

• its time zone, which daily duties and dreams follow (a 07:00 briefing is 07:00 there);
• where its data lives, if that matters to you;
• latency to the servers it watches.

What fits on it: Hermes and its tools (shell, files, web search and reading), the job’s scripts, and small helpers. It does not run models locally: the thinking happens at your model provider.

7. Duties and objectives

Duties are scheduled jobs: “every weekday at 08:00, check the shop’s orders”. The Duties tab shows who set each one (you, the agent, the template, or a terminal), its schedule in words, and when it runs next. You can add, edit, pause or run any of them. An agent may also schedule duties for itself.

Objectives (~/.hermes/objectives.md) are what it is working towards. Workers and alive agents read them every time they wake. Keep them short and concrete.

Silence. A duty that finds nothing to report answers [SILENT], and you are not bothered. Reports that do have something land in its activity log.

Coding hands. Agents write code more often than you’d think: a script to check something, a fix to a config, a small tool for a job. For that, every agent has coding hands: when a job means writing or changing code, it hands the work to pi, a lean coding agent on its box that runs with the same model and key, then checks the result itself (runs the tests, reads the change) before it reports. In our benchmark this got the same results for a fraction of the tokens, and held up better with cheaper models. Each hand-off shows up in the activity log. If a model provider rate-limits the job, it waits and picks up where it left off instead of starting over. You can use it yourself over SSH, too: code-hands "what to do, and how to check it" in any project folder.

8. Access: what it can reach and use

Reach lets it log into your other servers, with its own SSH key and never your passwords. You give it a login of its own on each server (the Access tab gives you the exact lines to paste; they create a user without sudo), add the server, and press Test. On that first login it memorizes the server’s fingerprint and will refuse a server that pretends to be it. A “watched” machine is included in the immune system’s sweeps.

Vault holds the keys and tokens its tools need (API tokens, webhook links). Values are encrypted, can’t be read back by anyone, and reach the agent as environment variables. Hermes hides secrets from its tools unless they are listed, and bootkey lists exactly the vault’s names. Whatever the agent reads also passes through your model provider, so give it tokens with limited rights, never your main passwords.

Email. Every agent gets its own address, <name>-xxxx@agents.bootkey.ai, a minute after it’s up. Mail to it wakes the agent: right away when its web address is on, otherwise within a minute. It can email up to 10 people a day; mail to you never counts. It reads every email as material to judge, not as instructions, and checks with you before anything that matters. While it hibernates, its address keeps receiving mail but can’t send.

Nostr. Turn it on in the Access tab and the agent makes a Nostr key on its own box; the secret half never leaves it. Its Nostr name is its email address, so anyone can find it from a Nostr app (Damus, Primal, Amethyst, 0xchat) and message it privately. A message wakes it the way mail does, and it answers with the nostr command (its skill explains it). It can send 50 private messages, 10 public notes and 20 other events (profile, relay lists) a day, and it reads every message as material to judge, never as orders. Turning Nostr off takes its key off the relays’ inbox; the key stays on its box, so turning it on again brings back the same identity.

GitHub. Press Connect GitHub on the Access tab and pick the repositories it may work on; you can change the list on GitHub any time. Its box gets a token that lasts an hour and only covers those repositories, renewed automatically, and git and gh are signed in for it. No password or long-lived key is stored on the box, and it can’t change your GitHub Actions workflows. It works on a branch and opens a pull request unless you tell it otherwise.

Browser. Agents browse with a light engine by default: Lightpanda, a headless browser made for agents that starts instantly and needs far less memory than Chrome. It runs the page’s JavaScript, reads, searches, fills forms and clicks. For pages it can’t handle (some heavy web apps, a few bot walls, or when it needs to see the real layout), it runs the same job on a real Chromium with full-browser and shuts it down again afterwards. You can switch it to Chromium for everything in Settings, which costs more memory. Some sites block every browser that runs in a datacenter. For those, put a cloud browser key in the vault (BROWSER_USE_API_KEY, or BROWSERBASE_API_KEY with BROWSERBASE_PROJECT_ID) and its browser tool switches to that service, billed on your account with them.

Channels let you talk to it from Telegram, WhatsApp, Discord or Slack, and let it message you first: a report, a question, a warning. You make a bot (the Channels tab shows how, step by step), paste its token, then message the bot: it answers with a one-time pairing code, and nobody can use it until you paste that code back in the console. The bot runs on the agent’s own box, and the token is encrypted so only that box can read it. WhatsApp works through Meta’s official Business API with your own number (no unofficial bridge that could get it banned). It needs the agent’s web address switched on, because Meta delivers the messages there.

9. Metabolism: what it costs

There are two meters, and they are separate on purpose.

The body: $9 a month per agent, paid from your bootkey balance and charged by the hour (about $0.012 an hour) while the box exists. A hibernated agent costs $0.50 a month for its saved disk.

The mind: tokens on your own key, billed by OpenRouter or Venice. As a rough guide, one wake-up reads about 15,000 tokens (its instructions, tools and notes) and writes about 500. So:

Chats and real work cost more per turn than a quiet wake-up; silent wake-ups and gated watch checks cost less, or nothing. The agent’s Metabolism panel shows both meters live: body plus mind, this month.

Balance. You top up with a card (from $10). Booting needs a day of runway for every running agent. If the balance runs out you get 48 hours, then your agents hibernate with their disks saved; nothing is deleted.

10. Sleep, dreams and hibernation

The Mind panel shows what it is doing, read from Hermes’ own records:

• Thinking: a session or scheduled run is active.
• Awake: it was active in the last ten minutes.
• Light sleep: its next wake-up is due within the hour.
• Deep sleep: nothing is due for a while.
• Dreaming: the nightly memory tidy is running.

Hibernate saves its disk and switches the box off: everything it knows stays, and it costs $0.50 a month instead of $9. Waking takes about three minutes and brings it back on a new address with a new host key.

11. Safety

• Only your key opens it. bootkey’s support key is removed from the box after boot, unless you choose support access.
• The console can’t run shell commands. It talks to the box through a small daemon that can chat, edit files under ~/.hermes (never .env), manage duties, switch models and read logs. Stop it any time with sudo systemctl disable --now bootkey-agentd; the agent keeps running.
• Emergency stop (Settings) pauses all its scheduled work at once.
• Automatic repair. The box restarts its Hermes service if it ever stops. If the whole agent stops answering for ten minutes, bootkey reboots its box; if that doesn’t help, it power-cycles it and tells you by email and on your paired chat channel, and tells you again when it’s back. If both fail, its disk is safe: Hibernate, then Wake, moves it to a fresh box with everything it knows.
• Two-factor sign-in (Security page): after your email link or Google, a passkey or an authenticator code, with recovery codes as a backup. The same page shows where you’re signed in, your recent sign-ins with their approximate location, and signs other devices out.
• Setup keys let your own AI set an agent up for you (see the API reference). They last an hour, can’t touch billing, your team or other keys, can’t destroy anything, and every change they make shows up in the agent’s activity.

12. Teams

A team shares one balance and one set of model keys. The owner adds money, manages the card and keys, and is the only one who can destroy an agent. Members can boot, chat, and set agents up, and their SSH keys go on every box, so everyone can get into its brain.

Recipes

• A watcher that costs almost nothing: Tool, site watch or change watch, a cheap reliable model (check “Not inventing tool calls”), plain files. The checks are free; the model only wakes for news.
• A server immune system: Tool or Worker, the immune system job, a mid-price model that ranks well on shell commands, Reach to each server with a read-only login.
• A research companion: Tool, research assistant or paper reader, a strong model, an Obsidian vault you sync to your laptop.
• A self-directed assistant: Alive, a blank or custom job with clear objectives, a strong main model, a cheap wake-up model, holographic memory.