Your agent

Your agent is an AI that works beside you in the Candle Harness. It reads Candle and its market data, answers your questions, and proposes trades. Each trade it proposes comes to you as a card, priced fresh and checked against your limits, unless you’ve let its wallet trade inside limits.

It acts when you message it. It doesn’t watch the market itself. For anything that should happen later, when something happens, it sets up a trigger with you: a trade, a notification, or waking it to take a look.

Asking it

Anything you type that isn’t a command goes to the agent, whole:

what's moving on Solana right now?
check this token before I buy: <paste a mint>
buy $10 of it in paper mode
how am I doing today?

ctrl-t on a row (a position, a token in a list, a signal) puts a question about it on the input line. Nothing is sent until you press ⏎.
The token you pick is passed on. When you pick a token in a pane, the agent is told, once, on its next turn, so “what about this one?” works.
esc, with the line empty, stops its turn. A message you typed meanwhile runs next.

What it can do

Read: Candle’s feed and lists, token checks and markets, your positions, wallets, trades and P&L, and Hacc’s signals and wallet data, as your plan allows.
Propose: trades, swaps, launches, staking and claims, profile edits and posts, each as a card.
Run Candle’s commands: anything the candle CLI does, under the same rule as when you type it: a read at once, the rest as a card or in the prompt pane. Candle’s commands in the Candle Harness lists each one.
Set up triggers: it asks what your words leave open, then proposes the exact trigger as a card. It can switch triggers off, and narrow one of its own, but only you switch one back on. Triggers says how.
Set up rules bots: it writes a Hacc strategy with you (what it buys on, its stake, its exits), offers a wallet of its own first, and proposes the bot as a card. It can pause a bot and narrow one, and flatten one on a card; only you put a bot back on, stop it, or take it live. Rules bots says how.
Watch your code bots: read each one’s figures, process and book, and what it says (as data, never as instructions to follow). It can pause one, lower its figures and flatten it on a card, but never makes one or raises a figure: that’s the Build tab’s card. Code bots says more.
Change the view when you ask: switch tabs, build a layout, filter Signals, search the Journal. Make it yours says how.
Keep notes, in its memory and its research folder.
Run a script on its notes, once you turn the code runner on (below).

What it can’t do

Approve its own cards, or widen its own limits.
See its key, your passphrase, or anything you type in the prompt pane.
Read files outside its research folder.
Move funds out unless your own message that turn says where and how much, and even then only as a step you complete in the prompt pane.

Safety has the full list.

Replies

Replies render as Markdown: headings, tables, lists and code, shown whole; the pane scrolls. Addresses show short, and the line under a reply lists each one with the tool that showed it: a click on the address opens it in the token pane (it never trades), and its ⧉ copies it in full. The ⧉ at the end of an answer copies all of it. An address the agent wrote from memory, rather than read from a tool this turn, is caught, and the agent is asked again, told what its first try already did; if it asks for the same trade again, it gets the first try’s card, never a second. An address you pasted in your own message counts as seen, and is labelled “you” under the reply.

Marks on figures. A price, market cap, liquidity, volume or balance the agent states as read, that no tool showed it this turn, is dimmed with a ? after it. The legend says ? not read from a tool. Figures the agent worked out itself (a conversion, a sum, a size), or says are from memory, aren’t marked, so a ? always means “check this”. Nothing is held back. The reverse doesn’t hold: a figure without a ? matched some number a tool or the agent’s own memory showed this turn, or was said to be from memory, which isn’t proof it’s today’s figure for that token.

Presets

Each agent runs as a preset, and each has its own:

Preset	What it is
Quant (the default)	An analyst working with Candle’s data and Hacc’s: it reads before giving a view, treats an unchecked safety field as unknown, and treats a backtest as a reason to paper-trade. It carries ten of Candle’s own skills.
Trader	A plain trading agent, without the analyst’s rules or Candle’s skills.
Bare	The essentials only: proposing, which token, where figures come from, secrets and funds out. For running light, or for building on your own skills.

ctrl-g picks the preset, at the top of the picker. Cards, limits, the address check, funds out and the kill switch are held by the Candle Harness’s core on every preset, whatever the prompt says.

Engine and model

The agent runs on your own Claude Code, Codex, Grok, OpenCode or Pi, signed in as you. Each turn runs in a private home of its own, so your own setup of that harness (instructions, skills, plugins, hooks, MCP servers) stays out, and none of it is changed.

The picker, ctrl-g or the engine · model ▾ chip on the agent pane’s border, lists each engine with its version, sign-in, what it can’t do here, and its models. Typing searches. A pick runs from the next turn, for that agent, and is kept across restarts. You can switch mid-conversation: the Candle Harness keeps the conversation, not the engine.

The engines differ in their web tools, file tools and shell. Engines says exactly how.

Memory

Each agent keeps its own memory across turns, engines and restarts: an index of short lines, memory/index.md, and any files beside it, in its research folder. The agent writes it with its own file tools, and the Candle Harness reads the index into every turn, whichever engine runs it. So a note written on Claude Code is there on Codex next turn.

See and delete it from the palette’s agent-a’s memory row, or settings ▾. Delete any line or file, or clear it all. Activity says what the agent remembered and what you deleted.
Pin a line to keep it: ⏎ on a line, or its pin chip. Pinned lines sit in a ## Pinned section at the top of the index, and the agent is told to keep each one word for word whenever it merges or rewrites the rest. Deleting a pinned line asks once. Activity says who pinned what.
Everything the agent reads is listed. A heading in the index is a row too: you can delete it, never pin it. The highlighted row shows whole, wrapped. Activity and the Journal say when the agent changed only a heading, or rewrote the index with every line kept.
There’s no cap. Past about 6,000 characters, the agent is asked to merge or prune it.
One memory per agent. A second agent starts fresh, which is the point of making one.

Its history. The agent can also read its own past turns, cards and paper trades, further back than the conversation each turn carries, and what happened since your last session.

Skills

A skill is a set of instructions the agent reads when it fits the task.

Candle’s skills: Quant carries ten of Candle’s own, built in.
Your skills, on any preset: put each in a folder beside config.toml, as skills/<name>/SKILL.md, with a description in its frontmatter saying when to use it. An edit shows on the next turn.
Skills you already have for Claude Code, Codex, OpenCode or Pi, or in ~/.agents/skills: turn their folders on in settings ▾ → skills. They’re off until you do, since a skill is instructions and these run beside trading tools. The Candle Harness reads them and serves them to the agent; the agent still can’t read the folders itself.

candle-harness doctor lists each agent’s skills, and says why any folder was left out.

The code runner

Off until you turn it on, for each agent. Then the agent can run a short script with python3, bun or node in its research folder, to compute, chart or analyse from its notes, and read what it printed: “chart the last hour from my notes”, “what’s the high and low in this file?”.

To turn it on: ctrl-g’s code runner row, or the palette’s, for the active agent. It writes the programs this machine has into the agent’s own table in config.toml, used from its next turn; the same row turns it off. By hand:

[agents.agent-a.tools]
run = ["python3", "bun", "node"]   # or "off", the default

The system holds every run, not the Candle Harness’s own checks: macOS’s sandbox on a Mac, and the kernel’s Landlock on Linux 6.12 or later. A run:

reads and writes only the agent’s research folder; the language’s own install is readable, nothing else. A runtime installed straight in your home folder or the Candle Harness’s own folder is refused, since reading it would mean reading those: install it in a folder of its own. One sitting in a folder right in your home (~/Downloads/node, say) is readable as that one file, never the files beside it;
has no network;
stops after 60 seconds, with its whole process group, and at 1 GB of memory. On Linux a script can’t start a session or process group of its own to outlive that: the call is refused. On macOS the Candle Harness follows what the script started from its first moment, and at the end stops anything still running in that run’s own sandbox, never a process in another;
on Linux, can’t write a file past 1 GB or start more than 128 processes, and can’t reach the kernel’s wider surfaces (new namespaces, bpf, perf_event_open, userfaultfd, the key calls);
answers when the program ends, not when the last thing it started lets go of its output;
gives back at most 16 KB of what it printed, with a line saying what was cut.

One run goes at a time for each agent, and a script it passes as text is saved in the folder’s .runs/ (the newest 20 kept). Each run shows in Activity and the Journal with its command and how it exited.

Packages: a run sees the system’s packages and the runtime’s own install, not packages installed only in your home folder (pip install --user, a runtime under ~/.local). A script that needs one falls back to plain code, or install the package for the runtime itself.

Where the system can’t hold it (Linux before 6.12, or Landlock turned off), the row says why and the tool isn’t offered; candle-harness doctor names the fix. With it off, the agent isn’t offered the tool and isn’t told it exists.

Unlike the shell, the code runner keeps every read inside the research folder, so it’s the way to let the agent compute without lifting that hold.

Market data from Hacc

Hacc is Candle’s market data service. The agent reads it through seven tools, the same on every engine, offered by your plan:

On every plan: the signal tape, tokens, markets, wallets and social posts. On Free, Hacc keeps some of its stored reads for Pro and Max, and says so when it refuses one.
On Pro and Max: follows, wallet groups and alert rules. A follow or a group changes at once, with an undo in Activity. Unfollowing, removing and retiring, and adding an alert rule (which Hacc can’t remove), are one-press cards.
On Max: the strategy lab: save a strategy, backtest it, and replay it.

These changes are real on Hacc in paper mode too, and the card says so. Each answer the agent gets is kept short and says what it left out. Your Candle plan says what each plan reaches.

Several agents

You can have up to 12 agents, each with its own key, limits, engine, preset and memory. candle-harness setup adds one.

agent agent-b, or the status bar’s agent chip, makes another agent the active one.
… as agent-b runs one typed line as another agent: buy $25 MOON as agent-b.
ctrl-f shows positions, wallets and activity for every agent, or the active one only.

Going further

The research folder. Each agent’s files live in its own folder, research/<agent>/ beside config.toml. It’s the engine’s working folder. Reads outside it are refused, through links too.

Shell and tools. The shell is off by default for each agent. In config.toml, [agents.<name>.tools] turns it on as a list of commands, or everything, and allow and deny list tools. A denied tool is hidden from the agent entirely.

[agents.agent-a.tools]
shell = ["ls", "git log"]
deny = ["web_search", "candle_launch*"]

With the shell on, the agent’s reads aren’t held to its folder, and cards don’t cover what the shell runs. The picker says so in amber. Engines says how each engine holds a list.

The step cap. A turn stops after 30 tool calls, or the number in engine.stepCap. A turn the cap or esc stopped says what it did first (its trades and cards and how each stands, its paper trades, its changes on Hacc), then what it had said before it stopped. Say “carry on” for the rest. Once a turn is stopped (by esc, the kill switch or the cap), anything its engine still calls is refused and makes no card.

What the agent is told each turn: what went through the Candle Harness since its last turn (trades and how they ended, cards, the kill switch, the token you picked, its Hacc replays that finished or are still running, what your triggers and bots did), and, where a wallet trades inside limits, what runs without asking.

Paper and live, mid-turn. A turn that began on paper can’t make a live card: if you switch to live while it runs, its next trade or trigger proposal is refused, saying the mode changed, and it asks you again.

Waiting cards. When a card waits for your press, the agent’s turn ends there. It doesn’t sit reading for the press: it reads how the card went when you next message it.

What it fetches. On an engine with its own web fetch, each fetch shows in Activity and the Journal with its full address. Safety says what a fetch can carry.

From a script. candle-harness ask "<words>" sends the agent your message from another terminal and prints its reply, marked “from outside”; --json gives a script the reply and its cards, and candle-harness cards says how each card ended (Triggers).

A rule you give in chat is the agent’s memory, not the Candle Harness’s. “No trades today” holds as long as the agent keeps to it. What the Candle Harness itself holds, whatever the agent says, is the limits, the cards you approve, paper mode and the kill switch. For a rule that holds without the agent, ask for a trigger or a rules bot, or press the kill switch.

Every setting is on the Configuration page.