- Go 100%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
|
All checks were successful
build / Build and publish (push) Successful in 4s
Reviewed-on: #37 |
||
| .forgejo/workflows | ||
| cmd/brainless | ||
| internal | ||
| .gitignore | ||
| brainless.json.example | ||
| cost_plan.md | ||
| go.mod | ||
| go.sum | ||
| LICENSE | ||
| README.md | ||
brainless
Headless Go agent harness: an ADK agent
(Go SDK: google.golang.org/adk/v2) that speaks
Agent Client Protocol (ACP, via
github.com/coder/acp-go-sdk) over stdio, so it can be registered as a Paseo
agent/provider.
Bare minimum: one ADK llmagent over an OpenAI-compatible (Responses API)
endpoint, bridged to ACP one session at a time.
Requirements
- Go 1.26.6+ (the ADK module requires it)
- An OpenAI-compatible endpoint implementing the Responses API (OpenAI, recent Ollama/LM Studio/vLLM), reachable with an API key
Configuration (config file)
Providers and models are declared in a JSON config file. By default brainless
looks for brainless.json next to the executable; point -config-file at a
different path to override.
{
"version": "v1",
"providers": {
"melious": {
"name": "Melious",
"baseUrl": "https://api.melious.ai/v1",
"apiKey": "${MELIOUS_API_KEY}",
"models": {
"deepseek-v4-flash-0731": {
"name": "DeepSeek V4 Flash 0731",
"input": ["text", "image"]
},
"deepseek-v4-reasoning": {
"name": "DeepSeek V4 Reasoning",
"reasoningEffort": ["off", "low", "medium", "high", "max"]
}
}
}
}
}
Key points:
versionmust be"v1".defaultoptionally names the model a fresh session starts on, asprovider/model. Omitted means the first configured model in sorted order. It does not restrict the selector: the ACP model config option always lists every model.- Providers are keyed by id (used in the ACP model selector as
provider/model);nameis an optional display label. - Each provider needs
baseUrl(an OpenAI-compatible endpoint) andapiKey. apioptionally names the OpenAI HTTP API a provider speaks:"responses"(the default, POST/v1/responses) or"chat_completions"(POST/v1/chat/completions). Responses calls are streamed over SSE — the endpoint some providers implement correctly only when streaming — and the harness reports the final aggregated answer. Set"chat_completions"for a provider whose Responses endpoint is broken or absent; tools, thinking effort, and usage accounting work identically on both APIs.- API keys and base URLs may reference environment variables with
$VARor${VAR}; unset variables expand to empty. Literal values without$are used as-is.apiKeymay be empty (local models). - Models are keyed by the wire model id;
nameis an optional display label.inputlists accepted content modalities (text,image,audio); unknown values are ignored and empty meanstext. reasoningEffortlists the selectable thinking levels (off,none,minimal,low,medium,high,xhigh,max). Empty means the model does not reason, so no reasoning control is offered at all.xhighandmaxare accepted but collapse tohigh: the ADK model bridge maps reasoning onto Responses effort and tops out athigh, so a model declaringmaxwould otherwise advertise a level that silently sendshigh.promptCompressionappends a compacted copy of the honey-for-devs AGENTS.md ruleset (https://github.com/Green-PT/honey-for-devs/blob/main/AGENTS.md — less code, less prose, denser agent-to-agent messages) to the model's system prompt. Off by default: the extra instructions cost tokens on every round, so they are opt-in per model.
MCP tools
brainless exposes Model Context Protocol (MCP) tools to the model on demand, so the schemas of tools the model has not asked for never bloat the prompt. Two sources are merged:
- The ACP client.
session/new,session/load, andsession/resumecarrymcpServers; brainless speaks thestdio(the transport every agent must support) andhttptransports, and advertisesmcpCapabilities.httpininitialize. Other transports (sse,acp) are ignored with a warning. - The config file. An optional
mcpServersmap, keyed by display name. A session server with the same name overrides the config-file one.
{
"mcpServers": {
"filesystem": {
"transport": "stdio",
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/work"],
"env": { "HOME": "/home/user" }
},
"remote": {
"transport": "http",
"url": "https://mcp.example.com/mcp",
"headers": { "Authorization": "Bearer token" }
}
}
}
transport is stdio (requires command, optional args and env) or
http (requires url, optional headers). MCP env/headers values are
literal (no $VAR expansion).
Trust boundary. A stdio server declared by the ACP client is launched as
a subprocess as soon as the session starts, with no confirmation step and no
model mediation. Anything able to reach the ACP endpoint can therefore run
commands in the brainless process by sending session/new with an mcpServers
entry. This is inherent to the ACP stdio transport, which every agent must
support, and is safe only when the ACP client is trusted — as it is when Paseo
spawns brainless as its own child process over stdio. If you expose brainless to
an untrusted client, restrict stdio servers to the config-file allowlist and
do not accept client-declared ones.
The model starts each turn seeing the built-in file, fetch, and execute tools
plus one more tool, tools. Calling tools returns a compact catalog of every available
MCP tool and loads the ones named in its load argument; those tools' full
schemas are then sent on the next round and the tools become callable. Loaded
MCP tools are cleared when the turn ends, so a later turn starts from the
catalog again unless it loads them anew. Tool calls and their results are
streamed to the ACP client as tool-call updates.
Built-in file tools
brainless ships nine built-in tools that need no MCP server: read, create,
edit, insert, list_directory, search_files, create_directory,
delete, and delete_directory. They exist so an agent can work with
files even when the ACP client connects no MCP server that offers file tools
(Paseo's injected workspace MCP exposes workspace management only, so without
them a brainless agent cannot read or modify a file at all). They are
always visible — their schemas ride in every request, with no tools
discover/load round trip — which for a small fixed set of tools is cheaper and
more reliable than routing them through the lazy MCP catalog.
read(path, head?, tail?)returns the file's contents as text, streamed and stopping early.headandtailare 1-indexed line bounds:headis the first line to include andtailthe last, so both together read a line range and a bounded read never loads the whole file.create(path, content)creates a new file or completely overwrites an existing one. Inside a git repository it refuses an existing file tracked by git —createis for new and untracked files, and precise changes to tracked files must go throughedit. A tracked file that is gone from the working tree is not refused: nothing is on disk to overwrite, andeditcannot bring it back because it needs the file to read. The guard shells out to git, socreateis only registered when git is present at startup; without git the tool is not advertised at all. A new file gets mode 0600; an existing file keeps its mode.edit(path, oldText, newText, count?)replaces an exact string. By default (or withcount: 1)oldTextmust appear exactly once, so the edit is never ambiguous; a negativecountreplaces every occurrence and a largercountreplaces up to that many. A missing match is always an error, andoldTextis matched within a single line, because the edit streams line by line. This mirrors the safe replace semantics of the reference MCP filesystem server (https://github.com/modelcontextprotocol/servers/tree/main/src/filesystem).insert(path, line, text)inserts text before a 1-indexed line:1inserts at the top,line count + 1appends at the end, anything else out of range is an error. Use it to add a section whereeditcannot match existing text.list_directory(path)lists a directory's entries likels, marking each as[FILE]or[DIR](the reference filesystem server's format)..gitis omitted, so repo discovery never drowns in git internals.search_files(pattern, path?, maxResults?)finds a literal substring across files likegrep -rn, returning matching lines aspath:line: textup tomaxResults(default 100)..gitand binary files are skipped.create_directory(path)creates a directory and any missing parents, likemkdir -p; it succeeds silently if the directory already exists.delete(path)deletes a file, anddelete_directory(path)deletes an empty directory (contents must be deleted first).
The three structural tools (create_directory, delete,
delete_directory) are confined to the session working directory: an absolute
path or a .. escape that lands outside it is refused. The read/write tools
keep the harness's documented posture of trusting the ACP client with no
allowed-directories jail.
Together list_directory and search_files cover repo inspection — seeing
what exists and where a symbol appears — and the structural tools cover
scaffolding and cleanup, so agents never need a terminal just to look around or
restructure a repo; a terminal remains for running commands (git, builds,
tests).
create, edit, and insert all write atomically: the new contents go to a
temporary file in the same directory, which is renamed over the original, so a
concurrent reader never sees a half-written file. read, edit, and insert
stream the file instead of loading it whole. Every operation takes the caller's
context and stops when it is cancelled. Relative paths resolve against the
session working directory (cwd from session/new); absolute paths are used
as-is. Like the rest of the harness, files are written without a permission
prompt and there is no allowed-directories jail: the ACP client is trusted, the
same posture as the stdio MCP servers the harness already launches.
Built-in fetch tool
brainless ships one more always-visible tool, fetch, so an agent has internet
access even when the ACP client connects no MCP server that offers it. It is
modelled after the reference MCP fetch server
(https://github.com/modelcontextprotocol/servers/tree/main/src/fetch).
fetch(url, maxLength?, startIndex?, raw?, timeout?) retrieves an http/https
URL and returns its contents as markdown:
- HTML is simplified to markdown with
JohannesKaufmann/html-to-markdown,
which drops scripts, styles and other non-content elements and keeps
headings, lists, links, code and tables. Relative links are made absolute
against the fetched page, so a URL that appears in the output can be fetched
directly.
raw: truereturns the body as fetched instead, and a non-HTML content type is always returned raw with a prefix saying so. - Content is windowed.
maxLengthdefaults to 5000 characters; a result cut short ends with thestartIndexto continue from, which is what makes it practical to read a long page in pieces. Indices count characters, not bytes, so a window never splits a multi-byte character. A body is read up to 8 MiB. - robots.txt is honored before the page is fetched: the origin's
/robots.txtis read and evaluated for thebrainlesscrawler token (RFC 9309 rules: longest matching pattern wins,Allowwins a tie). A disallowed path is refused, as is a site that answers 401, 403, or a 5xx server error for its robots.txt (a server error leaves the policy undefined, so the fetch fails rather than fetching unchecked); any other 4xx means there is no robots.txt to obey. The check runs again for every redirect the page takes, so a redirect cannot slip a disallowed path past it, and relative links in a redirected page resolve against the URL it actually came from. - Each request identifies itself as
brainless/0.0.1 (+https://git.norobo.chat/sam/brainless), follows redirects, and honors the proxy environment. - The fetch is bounded in time.
timeoutis the number of seconds the whole fetch may take, robots.txt check included; it defaults to 30 and may not exceed 300. A slow site therefore ends the fetch with a deadline error instead of holding the turn open, and a canceled turn still stops it immediately.
Like the file tools it takes the caller's context, so a cancelled turn stops the fetch, and it runs without a permission prompt: the ACP client is trusted, the same posture as the stdio MCP servers the harness already launches. Where the reference server also runs readability extraction (readabilipy) to strip a page's navigation and boilerplate, brainless only converts: the whole page's text comes back, which is noise rather than harm for an agent reading it.
Exposure. fetch is the first outbound network channel the model can
drive. It can reach any http/https URL, including addresses that are not
part of the public internet (localhost, RFC 1918 private ranges, cloud
metadata), and the page content — an untrusted prompt-injection vector — is
handed back to the model verbatim. This is acceptable only under the
trusted-ACP-client posture above; if brainless ever runs somewhere those
internal addresses are reachable from the same network, restrict what fetch
may target.
Built-in execute tool
brainless ships one more always-visible tool, execute, so an agent can run
commands even when the ACP client connects no MCP server that offers a
terminal tool. It is the model's sh -c: the command runs in the session
working directory (an absolute or relative cwd overrides it) and its
combined stdout/stderr plus exit code come back as the result.
execute(command, cwd?, timeout?)runscommandundersh -c, so pipes, redirection and compound commands work. A non-zero exit code is returned, not raised: the model reads the output to see what went wrong.- Output is capped at 100 KiB with a truncation note, so one noisy command cannot exhaust memory or drown the model.
- The command is bounded in time.
timeoutis the number of seconds the command may run; it defaults to 30 and may not exceed 300. A timeout kills the whole process tree (the command runs in its own process group) and reports exit code -1 with a note, so a runaway command cannot hold the turn open, and a canceled turn still stops it immediately.
Like the file tools and fetch it takes the caller's context, so a canceled
turn stops the command, and it runs without a permission prompt: the ACP
client is trusted, the same posture as the rest of the harness. It can reach
anything the paseo user can, which under that posture is the point — it is
how the agent builds and tests code.
Environment disclosure. The command inherits the harness's full process
environment — including provider API keys and tokens — and can read it via
env. There is no environment filtering; like every other capability this is
acceptable only under the trusted-ACP-client posture above.
Built-in memory tools
brainless ships six always-visible memory tools so an agent can keep and recall
facts across sessions, organised per repository: every operation is scoped
to the git repository root found by walking up from the session working
directory (the same anchor as the file tools), and directories outside any repo
share one default memory. The store implements the ADK
memory.Service interface
and is backed by SQLite (memory.db under the state dir, WAL mode), so two
agents working the same repo serialize writes through SQLite's file locks and
cannot lose each other's entries; -ephemeral keeps the store in memory only.
The two read tools are ADK's native memory tools, which search the same store the curation tools write:
load_memory(query)— the model explicitly searches the repo's memory; results are ranked by how many query words they match, at most ten.preload_memory— runs automatically at the start of every request and injects up to ten relevant entries into the system instructions, so facts the model wrote earlier resurface without being asked for.
The four curation and structured-read tools are modeled after the reference MCP memory server (https://github.com/modelcontextprotocol/servers/tree/main/src/memory), which stores a knowledge graph of entities (name, type, observations) and relations (active-voice connections between entities):
create_memory(entities?, relations?)— creates entities (with optional observations) and/or relations. Creating an entity or relation that already exists is a no-op, so the tool is safe to call repeatedly. A relation whose endpoint entity does not exist is an error.add_observations(observations[])— appends observations to existing entities; an observation already present is skipped.delete_memory(entities?, observations?, relations?)— deletes entities (cascading to their observations and every relation touching them) and/or exact observations and relations. Deleting something that does not exist is reported, not an error.read_graph(names?)— returns the repo's graph as JSON: withnames, those entities with their observations plus every relation touching either of them; without, the whole graph.
Stored content is deliberately curated only: AddSessionToMemory refuses to
ingest whole conversations, so memory never grows with raw session history —
the only records are the small facts the model writes with the curation tools.
Env expansion
apiKey and baseUrl may reference environment variables with $VAR or
${VAR}; unset variables expand to empty, so local models without an API key
boot fine. A malformed reference (an unterminated ${..., a bare $) is a
boot error, so a typo fails immediately instead of being used as a literal
credential; write $$ for a literal dollar sign in a key. API-key expansion is
the only env usage besides STATE_DIR (below) and the -prompt/-model
single-shot flags. The old MODEL/API_KEY/BASE_URL env provisioning is
retired.
Context compaction
Once a session's prompt grows past a token budget, brainless summarizes the
older turns and later prompts carry the summary instead of the raw turns, so
the prompt stays small as the conversation grows. Compaction is on by
default (ADK tail retention: one rolling summary plus the most recent events,
the strategy that puts a ceiling on prompt size); the block below only tunes
it, and "disabled": true turns it off.
{
"compaction": {
"defaultThreshold": 20000,
"compactionThreshold": {
"local/gemma4:e2b": 3000
},
"summarizerModel": "melious/deepseek-v4-flash-0731"
},
"timeouts": {
"promptTimeout": "10m"
}
}
defaultThresholdis the prompt token count at which older turns are summarized, for models with nocompactionThresholdentry. Zero uses the built-in default (20000 tokens).compactionThresholdoverrides the default per model, keyed byprovider/model— context windows differ, so the trigger should too. A small-context model (e.g. the local Gemma 4 E2B's ~4096 tokens) needs a threshold well below its window (3000 leaves room for the response and the always-visible tool schemas); a 128k-window cloud model can take 60000.summarizerModelnames the model that writes summaries, asprovider/model. Empty, the default, uses the session's own model — which is fine for large models, but a small model too small to summarize its own history needs this pointed at a model with a bigger context window. The summarizer call is bounded at 60s; a failure costs a bigger prompt later, never the user's answer (it is logged and the turn continues).
The most recent 10 events always stay raw, so the model keeps immediate
continuity. Invalid settings fail at boot: negative thresholds, non-positive
per-model thresholds, and compactionThreshold/summarizerModel keys that
name no configured model are all errors. The threshold applies to whichever
model the session is on; switching models rebuilds the runner's compaction
config for the new model.
Per-prompt timeout
A prompt that loops can burn your wall-clock long after it stopped being
useful. timeouts.promptTimeout puts a hard ceiling on how long one prompt
may run; it is off unless configured:
{
"timeouts": {
"promptTimeout": "10m"
}
}
- The value is a Go duration string (
"10m","90s","1h30m"). An unparsable or non-positive value fails at boot. - When the prompt passes half its budget, the clock block the model sees each
round gains a countdown (
prompt timeout: 10m; 5m10s left); past 90% it becomes a directive (prompt timeout nearly reached — report what you have), the last point where writing up what exists is still possible. - At expiry the turn settles with the partial answer already streamed and stop
reason
cancelled, and the in-flight model request is aborted — the same machinery assession/cancel.
Cost awareness
brainless can tell the model what its tokens cost, so cost joins wall-clock time as a second guide for how much work to spend on a task. Nothing is predicted: cost is computed from the provider's own usage report, and prices come from you.
Prices
Prices live in the config file, per model, as a pricing block. Rates are
per million tokens, named after the unit so a bare number cannot be misread:
{
"providers": {
"melious": {
"models": {
"deepseek-v4-flash-0731": {
"pricing": {
"currency": "EUR",
"inputPerMillion": 0.27,
"cachedInputPerMillion": 0.07,
"cacheWritePerMillion": 0.50,
"outputPerMillion": 1.10
}
}
}
}
}
}
currencyis a label, defaulting toEUR; nothing is converted, the harness reports in whatever unit you entered.inputPerMillionis the fresh (uncached) input rate.cachedInputPerMillionis the cache-read rate; omit it to assume no cache discount, so cache reads cost the same as fresh input.cacheWritePerMillionis the rate for input tokens written to the prefix cache, for providers that bill cache creation separately (Anthropic-style). Omit it to charge writes at the fresh input rate, the OpenAI convention where a cache write is an ordinary input charge.outputPerMillionis the output rate. Reasoning/thinking tokens are billed at the output rate on every provider brainless talks to, so they need no separate rate.- Absence means free. A model with no
pricingblock, or a block with no rates, costs nothing: it shows no money line and is steered by time alone. A negative rate is a boot error.
What the model sees
On a priced model, every round's <brainless-clock> block carries a cost line
measuring the last round, the current task, and the whole session:
cost: last round €0.0030; this task €0.0120 / 41k in (62% cached) / 3.2k out (2.4k thinking); session €0.0630
last round is the lever the model can pull at its next decision; this task
is the budget signal; session is the "this conversation has already cost me"
signal. The cache share and the thinking count are shown because they are the
two cost levers the model controls: keeping the cached prefix stable, and
choosing a reasoning level. The turn log reports the same figures (cost,
session_cost, plus cache_write_tokens and compaction_cost when non-zero)
so the operator can audit them against an invoice.
On a free model with a declared context window, the cost line is replaced by a context line — the real cost of a local model is prefill time, so the model should keep its prompt small instead:
context: 2k / 4k tokens
Budgets
budgets.maxTaskCost puts a hard money ceiling on one task, the money
counterpart of the wall-clock timeout. It is off unless configured, and it
only applies to priced models (configuring it when no model is priced is a
boot error rather than a silent no-op):
{
"budgets": {
"maxTaskCost": "0.50"
}
}
The value is a string so "0.50" cannot be misread as tokens. The model is
warned at half the budget and told to report what it has at 90%; at expiry the
turn is cancelled through the same context path as a timeout. A hard cost stop
can discard work that is nearly done and then be redone, which costs more —
set the budget from measured history (below), not a guess.
Measured history
history.lastTasks adds a line that tells the model what comparable tasks
have actually cost, computed from the persisted session events (grouped per
task; only completed tasks count):
{
"history": {
"lastTasks": 3
}
}
It is a measured average of the last N completed tasks, never a prediction, and it only appears when at least N completed tasks exist.
Context windows
contextWindow on a model declares its context window in tokens. It is the
steering knob for free local models: the clock block then shows how much of
the window the prompt uses, so the model can keep its prompt small where
prefill time is the real cost (see Wiring the local Pi model). A
negative value is a boot error; zero (unset) turns the line off.
Selecting a model
- ACP clients pick the model at runtime through the
modelconfig option (session/newadvertises amodelselector;session/set_config_optionswitches it). That is the only config option: reasoning is not a raw selector but is controlled entirely through session modes. - ACP clients switch reasoning behavior through
session/set_mode, which advertises three modes (fast,default,deep) as presets over the model's declared efforts:fastdisables reasoning,defaultturns reasoning on with no effort override so the provider applies the model's natural default, anddeepuses its maximum declared effort. The mode selector is only advertised for models that declare a reasoning effort other thanoff/none; a model that cannot reason offers no modes. - The same modes are also advertised as a
modeconfig option (categorymode). ACP conveysSessionModeStateonly insession/new/load/resume, so the config-option form is what lets the list change with the model: on a mode or model change, through eithersession/set_modeor a config option, the harness pushes aconfig_option_updateand acurrent_mode_update, and the client re-derives the mode selector. Without it, switching to a non-reasoning model would leave a stale mode selector. - The harness advertises
loadSessionand thesessionCapabilitieslist/close/resume/forkflags, so clients (Paseo) can list, load, resume, close, and fork persisted sessions;session/cancelsettles an in-flight prompt with stop reasoncancelled. -model provider/modelselects the model for single-shot (-prompt) runs.
State is persisted to disk by default. Where it lives:
| Control | Env var | Flag | Effect |
|---|---|---|---|
| State dir override | STATE_DIR |
-state-dir |
Directory for persistent state (sessions today; more later). Overrides the default. |
| Ephemeral | — | -ephemeral |
Keep all state in memory, persist nothing. |
The default state dir is the per-platform user config dir joined with
brainless: on linux $XDG_CONFIG_HOME/$HOME/.config/brainless, on macOS
~/Library/Application Support/brainless, on Windows %AppData%\brainless.
Boot fails if the platform has no config-dir convention or the location
cannot be determined (set STATE_DIR or pass -ephemeral to proceed).
Build & run
Prerequisites: Go 1.26.6+ (per go.mod minimum), and the module deps
(go build fetches them via the module proxy; a GOPROXY may be needed in
air-gapped environments).
# build the binary
GOOS=linux GOARCH=arm64 CGO_ENABLED=0 go build -o brainless ./cmd/brainless
# run it directly (spawned by an ACP client over stdio, or idle alone)
./brainless
Static cross-build (no CGO) so the same binary runs in the arm64 Paseo container:
CGO_ENABLED=0 go build -o brainless ./cmd/brainless
On its own (no ACP client attached) the process idles on stdio until the peer disconnects — which is the correct behavior for an ACP agent spawned by a client like Paseo. To smoke-test the ADK half without a client, run:
./brainless -prompt "What is 2+2?"
-prompt TEXT runs one turn through the ADK runner and prints the final text.
It uses the default model from the config file; pass -model provider/model
to pick another.
Registering as a Paseo agent provider
This walks through wiring brainless into Paseo as an ACP agent provider.
brainless is just an ordinary ACP-over-stdio process — Paseo launches it as
a provider declared in its config.json, so there is no server port or socket
to configure.
1. Build the binary
Build a static (no CGO) binary so it runs in the arm64 Paseo container:
CGO_ENABLED=0 GOOS=linux GOARCH=arm64 go build -o brainless ./cmd/brainless
Copy it onto the Pi host into a directory the Paseo daemon can execute, e.g.
/home/sam/bin/brainless. Make sure it is executable: chmod +x brainless.
2. Add the provider to config.json
Paseo reads providers from agents.providers in its config.json. A
brainless entry looks like this:
// In paseo/config.json, under "agents": { "providers": { ... } }
"brainless": {
"extends": "acp",
"label": "brainless (ADK)",
"description": "Headless ADK agent harness (OpenAI-compatible Responses API)",
"command": [
"/home/sam/bin/brainless",
"--config-file", "/home/sam/brainless.json",
"--state-dir", "/home/sam/data/brainless"
],
"enabled": true
}
Notes:
"extends": "acp"tells Paseo this provider is an ACP agent (same as theacpnative protocol), so it drives the stdio handshake for you.- The providers/models come from
brainless.json(see Configuration); the API key is read from the environment via$VARexpansion in the config file, so it never appears inconfig.json. Put the secret in the daemon environment (e.g.paseo.env). - Model switching happens at runtime over ACP:
session/newadvertises amodelconfig option listing every configured model, andsession/set_config_optionswitches it. Reasoning is controlled throughsession/set_mode(fast/default/deep), advertised only for models that reason. There is no need to declaremodelsin the Paseo provider entry — it is returned by the agent on each new session. - Pass
-model provider/modelto select the model for single-shot (-prompt) runs only; server mode is driven entirely by ACP config options.
3. (Optional) Choose where state is stored
State (sessions today) persists to disk by default; brainless uses a
directory under the user's config dir unless you pass --state-dir. To keep
conversations across restarts (session/load, session/resume) at a known
location, point it at a directory the daemon can write and create it if
absent (it is also created on first run):
mkdir -p /home/sam/data/brainless
brainless writes one shared SQLite database, sessions.db, in that
directory. Every brainless process pointed at the same directory shares it.
Pass --ephemeral instead to keep all state in memory and persist nothing.
4. Restart and verify
Restart the Paseo daemon so it picks up the new provider, then:
- In the Paseo agent picker,
brainlessshould appear with the model(s) listed inmodels. - Start a conversation and send a message — it should be answered by the configured model.
- If you are persisting state (the default), end the session, start a new one,
and use the session list/load UI (or
session/load) to confirm the earlier conversation is still available.
To smoke-test the ADK half of the harness without Paseo attached (a useful way to confirm the binary, config, and endpoint are all wired correctly):
./brainless -prompt "What is 2+2?"
Other ACP-compatible orchestrators
Any orchestrator that runs an ACP stdio agent can launch brainless the same
way — run the binary with stdio attached and drive
initialize → new-session → prompt. The -prompt flag is a convenient
one-shot smoke path for validating a given orchestrator's wiring.
Wiring the local Pi model (Gemma 4 E2B)
The pi-deploy stack runs a local inference endpoint (llm service) on the
Pi: an official ghcr.io/ggml-org/llama.cpp:server container serving
Gemma 4 E2B Q4 over an OpenAI-compatible API (both /v1/chat/completions
and /v1/responses) at http://llm:8080/v1. Because this llama.cpp build
serves the Responses API, brainless can talk to it directly — no chat
to-responses adapter needed.
Why it fits small/subagent prompts
The endpoint is small-context (~4096 tokens). Paseo's normal agent
context (system prompt + MCP tool schemas + session history) is ~31k tokens
and cannot fit, so the model is NOT registered as a normal Paseo agent model.
For brainless — which runs as a separate ACP harness you drive with small,
standalone prompts (e.g. subagents, quick Q&A, structured micro-tasks) — the
context stays small and the endpoint is a good fit.
Provider config
Add the local endpoint as a provider in brainless.json (see
Configuration). An empty apiKey is fine for a
local server:
{
"version": "v1",
"providers": {
"local": {
"name": "Local Gemma (llama.cpp)",
"baseUrl": "http://llm:8080/v1",
"apiKey": "",
"models": {
"gemma4:e2b": {
"name": "Gemma 4 E2B (local, Pi)",
"input": ["text"],
"contextWindow": 4096
}
}
}
}
}
Then register brainless in the Paseo daemon's config.json (under
agents.providers) pointing at that config file:
// In paseo/config.json, under "agents": { "providers": { ... } }
"brainless-local": {
"extends": "acp",
"label": "brainless local (Gemma 4 E2B)",
"description": "Local Gemma 4 E2B via llama.cpp Responses API",
"command": [
"/home/sam/bin/brainless",
"--config-file", "/home/sam/brainless.json",
"--state-dir", "/home/sam/data/brainless-local"
],
"enabled": true
}
Notes:
- The
baseUrlishttp://llm:8080/v1because thellmcontainer and the Paseo daemon (which spawnsbrainless) are already on the samelocalinferencecompose network — so the hostnamellmresolves inside Paseo. No API key is needed for the local server. - Reachability caveat: the
llmservice is published only on the internallocalinferencenetwork, not the host LAN.brainlessmust therefore run in a context that is on that network — i.e. spawned by the Paseo daemon (as here). If you runbrainlesson the Pi host or another container, expose the endpoint (e.g. publish100.64.0.1:8080:8080in pi-deploy'sdocker-compose.yml) and point thebaseUrlat the host-reachable address. - Keep the model key equal to the id the server reports (
/v1/modelsreturnsgemma4:e2b); the local OpenAI proxy accepts any model id but we pin it for clarity. It is selected per session via the ACP model config option. contextWindow: 4096declares the endpoint's small window, so the free model's clock block shows how much of it the prompt uses (context: 2k / 4k tokens) instead of a money line — the model's real cost is prefill time, and the line steers it to keep the prompt small. The per-modelcompactionThreshold(see Context compaction) should stay below the window too.- A separate
--state-dirkeeps local sessions distinct from cloud ones.
Verify
Smoke-test the ADK half without Paseo attached (run from a container/host that can reach the endpoint):
./brainless --config-file /home/sam/brainless.json \
--ephemeral -model local/gemma4:e2b -prompt "Write one sentence about paseo."
Or hit the endpoint directly to confirm it serves the Responses API:
curl -sS -X POST http://llm:8080/v1/responses \
-H 'Content-Type: application/json' -H 'Authorization: Bearer local' \
-d '{"model":"gemma4:e2b","input":"hi","max_output_tokens":16}'
Building for a different endpoint
The ADK openaimodel speaks the OpenAI Responses API, so every provider's
baseUrl must point at a Responses-API-compatible server (OpenAI, recent
Ollama/LM Studio/vLLM). Point baseUrl at your provider in brainless.json
and give the model its wire id as the map key.
What's a "bare minimum" and what's consciously missing
- No permission flow: ACP
session/request_permissionis not bridged to ADK's Human-in-the-Loop confirmation, so loaded MCP tools execute without asking. Tool calls and their results are surfaced to the client as ACP tool-call updates (see MCP tools). - Sessions map one at a time and live in a shared SQLite store (
sessions.dbunder the state dir) so they persist across process restarts by default;-ephemeralkeeps them in memory instead.session/list,session/load,session/resume,session/fork, andsession/closeare implemented;session/deleteis not and returns method-not-found.session/loadandsession/resumereplay the stored conversation as message updates, so a resumed session shows its history, andsession/forkbranches a session into a fresh one with a verbatim copy of the conversation. Each session records the working directory it was created with, sosession/listreports the rightcwdper row (Paseo feeds it back intosession/loadand its import UI) and the file tools resolve relative paths correctly even after a restart. - Model switching (
session/set_config_option) is applied to the next prompt for the whole process (one active session at a time), not persisted per session. Theinputmodality metadata inbrainless.jsonis not yet wired to ACP prompt capabilities, so image/audio inputs are not accepted even when a model declares them. - No streaming of partial chunks.
Next steps
The harness is deliberately minimal. Likely next steps, roughly in order of value:
- Multiple sessions per instance. Today the harness tracks one active
session id;
Promptroutes by the id carried in the request, falling back to the single active id. Supporting several sessions per process is a natural follow-up: replace the single cursor with a registry keyed by id — the SQLite store already supports many. - Per-session model selection.
session/set_config_optionsets the model for the whole process today (the harness holds one active session). When multi-session support lands, persist the selection per session id. - Input modalities. The
inputmetadata inbrainless.jsonis validated but not yet enforced: a configured image-capable model does not advertisepromptCapabilities.imageand the harness drops non-text prompt blocks.
Things that remain consciously out of scope for the bare-minimum harness: no human-in-the-loop permission bridging (tool calls run without asking), no streaming of partial chunks, and no memory/recall service.