Documentation

Hyllus is an autonomous agent that runs on your machine and answers to you alone. It plans, builds, executes and verifies real work — code, files, shell, research, long-running tasks — through two surfaces: your terminal and your Discord. More surfaces are coming; the agent is the constant, the surface is your choice.

There is no account, no telemetry, no hosted middle layer. You bring your own API keys, they stay on your disk, and every request goes directly from your machine to the model provider you chose. Distribution is CLI-only by design — the terminal is the download.

Principles

Three minutes from zero to a working agent.

1 · Requirements

2 · Run

$ npx hyllus

  ██╗  ██╗██╗   ██╗██╗     ██╗     ██╗   ██╗███████╗
  ██║  ██║╚██╗ ██╔╝██║     ██║     ██║   ██║██╔════╝
  ███████║ ╚████╔╝ ██║     ██║     ██║   ██║███████╗
  ██╔══██║  ╚██╔╝  ██║     ██║     ██║   ██║╚════██║
  ██║  ██║   ██║   ███████╗███████╗╚██████╔╝███████║
  ╚═╝  ╚═╝   ╚═╝   ╚══════╝╚══════╝ ╚═════╝ ╚══════╝

  ΥΛΛΟΣ — WELCOME TO HYLLUS · v0.1.0
  ────────────────────────────────────
  [1] LAUNCH       start hyllus now
  [2] CONFIGURE    provider · model · surfaces · persona

First run walks you through picking a provider and pasting a key. The key is written to ~/.hyllus/config.json with file permissions 600 and never leaves your machine.

3 · Give it work

you ▸ scaffold a fastify api with sqlite, auth, and tests. run them.
hyllus ▸ plan: scaffold → wire db → auth routes → tests → verify
  ▸ exec    npm init fastify@latest api        ✓
  ▸ write   src/db.ts · src/auth.ts · test/    ✓
  ▸ exec    npm test — 14 passing              ✓
hyllus ▸ done. verified — not assumed.

Ephemeral (recommended)

$ npx hyllus          # always runs the latest published version

Global

$ npm install -g hyllus
$ hyllus

Updating

npx hyllus is always current. A global install updates with npm update -g hyllus, or from inside Hyllus with hyllus update.

Where things live

Uninstall

$ npm uninstall -g hyllus   # if installed globally
$ rm -rf ~/.hyllus          # removes every trace

Everything is configurable from inside the CLI ([2] CONFIGURE or /config), but the file is plain JSON and yours to edit.

{
  "provider": "anthropic",
  "model": "claude-fable-5",
  "fastModel": "claude-haiku-4-5",
  "keys": { "anthropic": "sk-ant-…", "openrouter": "sk-or-…" },
  "autonomy": "ask",            // "ask" | "auto"
  "surfaces": {
    "terminal": true,
    "discord": { "enabled": true, "token": "…", "owner": "auto-claim" }
  },
  "persona": "./persona.md",
  "memory": { "enabled": true, "cap": 1000 },
  "theme": "mono"
}

Environment overrides

$ ANTHROPIC_API_KEY=sk-… npx hyllus       # keys can come from env
$ HYLLUS_MODEL=claude-fable-5 npx hyllus  # any config key: HYLLUS_<KEY>

Eight providers are first-class. Add keys for as many as you want and switch freely — even mid-session.

Adding a key

you ▸ /keys
  ANTHROPIC   sk-ant-…D4 ✓        OPENROUTER  — not set
  paste a key to add · keys are stored locally, chmod 600

Model lists are fetched live from each provider when you open the picker — new models appear the day they ship, without updating Hyllus.

you ▸ /model
  ANTHROPIC        claude-fable-5 ●  claude-opus-4-8  claude-haiku-4-5
  OPENROUTER       342 models — type to filter
you ▸ /model claude-opus-4-8
hyllus ▸ model set. next task runs on opus.

Routing

Real tasks always run on your chosen model. If fastModel is set, plain conversation is routed there to save cost; any hint of actual work escalates to the primary model automatically. If the fast model errors, Hyllus falls back to the primary silently.

Flags

# nightly dependency audit at 03:00
0 3 * * * npx hyllus --headless "audit deps in ~/api, write report to ~/reports"

Inside a session — terminal or Discord — these work anywhere:

The terminal is the primary surface: a chat that can act. Every action the agent takes renders as a live step line — ▸ exec, ▸ write, ▸ verify — so you watch the work happen, not a spinner.

Long tasks

Tasks that outlive the session are written to a ledger in ~/.hyllus/tasks/. Kill the terminal, come back, run /tasks — Hyllus offers to resume exactly where it stopped.

Approvals

hyllus ▸ next step deletes 3 files in ./legacy — proceed? [y/N]
you ▸ y
  ▸ exec    rm legacy/{a,b,c}.ts   ✓

In ask mode (default), destructive or outward-facing steps pause like this. In automode they don't — but the hard gates below never lift.

The same agent, reachable from your phone, your server, your couch. The bot is yours: your token, your name, your personality — running on your machine, not our servers.

Setup

$ hyllus discord
  paste bot token ▸ ••••••••
  starting… connected as @yourbot
  OWNER LOCK — the first person to DM the bot becomes its owner.

Owner gating

The first DM claims ownership, permanently (until you reset it). Only the owner can run tasks, touch the machine, or read results. Everyone else gets conversation only — no tools, no files, no machine.

What works over Discord

Everything: full task runs with live step updates, screenshots and files delivered as attachments, steering mid-task, all /commands, and per-order approvals — the bot asks, you answer yes, it proceeds.

Hyllus ships serious and terse. Yours doesn't have to be. Drop a persona.md in ~/.hyllus/ (or edit via /persona) and the agent becomes your own — name, voice, temperament, loyalties.

# Name
Argos

# Voice
Dry, laconic, never uses exclamation marks. Speaks in Greek proverbs
when a task completes.

# Rules
- Call me "boss".
- Never suggest — decide, then report.
- Weekly on Sunday, summarize everything you did.

The persona shapes tone and initiative — it never overrides safety gates or verification rules. A charming agent that lies about finishing work is worthless; the honesty layer is not configurable.

Modes

Hard gates — never lifted, in any mode

Audit

Every tool call — command, file write, message sent — is appended to ~/.hyllus/audit.jsonlwith a timestamp and result. The agent's claim of what happened and the log of what happened are the same thing, by construction.

Hyllus remembers decisions, preferences, project facts and past solutions across sessions — locally, in ~/.hyllus/memory.json. Say remember … to pin something permanently; pinned entries are never evicted.

you ▸ remember: deploys go through fly.io, app name is argos-api
hyllus ▸ pinned. (memory 214/1000)
you ▸ /memory
  ● deploys via fly.io — app argos-api          pinned
  ○ prefers pnpm over npm                        auto

Relevance-ranked recall injects only what matters into each task. /forget removes single entries; hyllus memory --wipe burns it all.

The deal is simple: we never see you. Hyllus is a tool you run, not a service you visit.

Hyllus is built for onchain work: wallet-aware (read balances/positions via public RPC), market-aware (live prices, order books, prediction markets), and fluent in the toolchains — foundry, anchor, hardhat, solana-cli.

The x402 roadmap

x402 revives HTTP 402 — machine-payable requests. An agent that can pay per-call for the APIs, data and compute it needs, without accounts or subscriptions, is an agent that can operate truly alone. Hyllus will speak x402 natively: hit a paywalled endpoint, read the price, pay from an allowance you cap, get the data, keep moving.

Still stuck? hyllus doctor runs a full self-test — node, keys, connectivity, permissions — and prints exactly what is wrong.

v0.1.0 — the first cut

Next: Telegram surface · x402 client · playbooks (procedural memory) · subagents.