Configuration

Besydr reads one TOML file. The first command that needs it writes it from a built-in template, so you start from a complete file and edit what you want to change. Run besydr config to see where everything is.

Where the file and the data live

Item Location
Data directory ~/.local/share/besydr on Linux and macOS, %LOCALAPPDATA%\besydr on Windows. Set BESYDR_DATA_DIR to move it.
Config file <data directory>/config/config.toml. Set BESYDR_CONFIG_PATH to use another file.
Key file <data directory>/config/.env (optional, see below)
Socket <data directory>/besydr.sock, or the path in [server]

Besydr keeps its state in the data directory: lessons in learning/, saved sessions in sessions/, the logs hook.log, server.log and activity.jsonl (described below), the licence file and trial date, and the logs hindsight.jsonl and advise.jsonl that the two optional checks write. Besydr deletes a saved session after the retention window set by retention_days in [sessions] (7 days by default); the check runs when the server starts and every five minutes after. Setting BESYDR_DATA_DIR moves the state, the config file and the key file together; use it to run a second copy of Besydr in isolation.

Three files tell you what Besydr did or why it failed:

File What it holds
hook.log One line for each time a hook did nothing, with the reason. Cut to its newest half above 1 MiB.
server.log What the server prints to standard error when a hook or connect starts it in the background. Without it that output would be lost. Colour codes are off. Cut to its newest half above 1 MiB, each time a server is started this way. A server you start yourself with besydr serve prints to your terminal instead.
activity.jsonl One JSON line for each event the server handled (client, session, event name, time taken in milliseconds, names of the effects in the answer, and the error message if the handler failed) and one for each model call it made (session, what the call was for, tokens, cost in US dollars, time taken, and whether the agent waited for it). It holds names, ids and numbers only: no prompts, no tool output and no file content. It stays on your machine. Cut to its newest half above 8 MiB. Only besydr serve writes it; read it with besydr stats.

besydr config prints the config file path, the data directory, the model and the decision model, and for each model whether the key variables it reads are set. It never prints a key.

The file is strict. Every key must be present, an unknown key is an error, and version must be 1; a file with another version is refused, not converted. A typo therefore fails at start instead of being ignored. Besydr reads the file when it starts, so restart the server after an edit: stop it, or wait for it to exit when idle (see [server]).

Environment variables

Variable Effect
BESYDR_DATA_DIR Data directory. An empty value counts as unset.
BESYDR_CONFIG_PATH Config file path.
BESYDR_LICENCE Licence text. Overrides the config file and the licence file. See Licence.
OCTOMIND_DATA_DIR Where Besydr looks for octomind's data, for the carry-over below.
OCTOMIND_CONFIG_PATH Octomind's config file, when you keep it outside octomind's data directory. Besydr reads it only for the carry-over below.
HF_TOKEN Access token for a private [hindsight] model repository on Hugging Face.
Provider key variables Listed in the next section.

Models and keys

Besydr makes its own model calls. It uses two models:

  • The model in [model] writes text: the checklist, the completion check, plans and lessons.
  • The decision model in [decision] answers short typed questions about a text, such as "does this lesson apply to this request" or "does this part of a tool result report a failure". It writes no text. A decision call is one attempt with a 5 second timeout and no retries. When it is unavailable, the check that asked takes its fallback; for the lesson relevance filter that means keeping every candidate.

Both default to octohub:auto, the OctoHub model gateway that octomind uses. The key for it is found in this order:

  1. The environment variable OCTOHUB_API_KEY of the process.
  2. OCTOHUB_API_KEY in <data directory>/config/.env.
  3. The key that octomind login stored in .env in octomind's config directory (<octomind data directory>/config/.env).

A variable that is already set is never replaced by a later file. If you are logged in to octomind, you set nothing.

To use your own provider, change name in [model] and model in [decision] to a model of that provider and set its key variable:

Provider prefix Key variables
octohub OCTOHUB_API_KEY
typesafe TYPESAFE_API_KEY
cloudflare CLOUDFLARE_API_KEY and CLOUDFLARE_ACCOUNT_ID
openai OPENAI_API_KEY
openrouter OPENROUTER_API_KEY
ollama none

Examples of model names: ollama:<model>, typesafe:jev-latest, cloudflare:typesafe/jev. A decision model is required: an empty [decision] model is an error.

Carry-over of octomind settings

When Besydr writes its config file for the first time, it looks for the settings you tuned for octomind's built-in supervisor and copies them in. It reads, in this order, the first of:

  1. besydr-carry/supervisor.toml in the folder of octomind's config file, a file octomind writes when it upgrades its own configuration. That folder is <octomind data directory>/config, or the folder of the file that OCTOMIND_CONFIG_PATH names.
  2. Octomind's config file itself, when it has a [supervisor] table.

Octomind named these tables supervisor.model, decision, supervisor.learning, supervisor.learning.evolution, supervisor.gate, supervisor.authorizer, supervisor.hindsight, supervisor.advise, supervisor.plan and supervisor.condense. Besydr copies each value into the table of the same function: model, decision, learning, learning.evolution, gate, authorizer, hindsight, advise, plan and condense. Only keys that exist in Besydr's template are taken, and only when the value has the same type as the template's. Two values are not copied: a decision model of cloudflare:typesafe/jev, which octomind shipped as its unused default, and recall, which octomind shipped off and Besydr ships on. The first line of the resulting file is # Settings carried over from octomind on first run.

A file that cannot be read or does not give a valid configuration is skipped with a message on standard error, and Besydr writes the plain template. Carry-over happens once. It does not run again when the file exists.

Lessons that octomind already learned are imported separately; see Learning.

Settings

Defaults are those of the template. Switches that turn a mechanic on or off are described in Mechanics.

Top level

Key Default Meaning
version 1 Layout version of the file. Besydr refuses any other number.
log_level "info" none: no log output. info: important operations and status. debug: detail. Log lines go to standard error.

[model]

The model for everything that writes text.

Key Default Meaning
name "octohub:auto" Provider-qualified model name.
reasoning_effort "medium" Hint for models that can reason: low, medium, high, xhigh or max.
max_tokens 8192 Output limit. 0 means the provider's default.
temperature 0.0 Sampling temperature.
top_p 1.0 Sampling top_p.
top_k 0 Sampling top_k.
max_retries 1 Retries after a failed call.
retry_timeout 30 Base delay of the exponential backoff between retries.
request_timeout_seconds 300 Total deadline for one request attempt. 0 turns it off.
stream_timeout_seconds 0 Longest silence in a streamed response. 0 turns it off. It does not extend the total deadline.
request_transport "websocket" websocket keeps one connection open for octohub and chatgpt models; http opts out. Other providers ignore it.

[decision]

Key Default Meaning
model "octohub:auto" Decision model. Required.
recall true Ask the decision model whether each recalled project lesson applies to the request, and drop those that do not. This costs one decision call per request. false turns the filter off.

[server]

Key Default Meaning
socket "" Socket path. Empty means besydr.sock in the data directory.
idle_exit_minutes 60 The server exits after this many minutes with no open connection and no background work. 0 keeps it running until stopped.

[sessions]

Besydr saves each session, with its transcript, in sessions/ after every event.

Key Default Meaning
idle_extract_minutes 30 Minutes without an event before lessons are extracted from a session whose client has not reported its end. 0 turns this off. See Learning.
retention_days 7 Days a saved session is kept after its last event, then deleted. 0 deletes a session once it has ended and its lessons are extracted; a session that is still open, or whose lessons are not extracted yet, is kept.

[licence] and [instance]

Key Default Meaning
licence.key "" Licence text. Empty means none. See Licence.
instance.url "" Team server address.
instance.token "" Team server token.

The [instance] keys are accepted in the file, but no part of this release reads them.

[learning] and [learning.evolution]

Key Default Meaning
learning.enabled true Extract lessons from sessions and add them to later sessions.
learning.evolution.enabled false Generate skills and rules from lessons and test them in trials (see Learning). Off by default.
learning.evolution.min_samples 10 Completion-check results needed in each group before a trial compares them.
learning.evolution.noise_margin 0.15 Smallest gain in pass rate worth promoting. Also the loss in pass rate a cheaper behavior may have.
learning.evolution.cost_allowance 0.10 Relative increase in model calls tolerated when the gain is negligible. Also the saving that promotes a behavior whose pass rate stays within the noise margin.
learning.evolution.cost_per_gain 2.0 Extra relative increase in model calls allowed for each unit of pass-rate gain.
learning.evolution.max_trial_uses 40 Uses after which an undecided trial is retired as inconclusive.

[gate]

Key Default Meaning
enabled true Run the completion check at the end of a turn.
unsettled_advisory true When the evidence is thin, offer one note per user turn and check again, instead of passing or failing at once.

[authorizer], [hindsight], [advise], [plan], [condense]

Key Default Meaning
authorizer.enabled false Check each tool call against your intent and the agent's role.
hindsight.enabled false Score each handed-back turn for the chance that you will correct it.
hindsight.model "muvon/hindsight" A Hugging Face repository (model files under onnx/) or a local folder with the export.
advise.enabled false Let a model write the note sent when the agent loops or keeps failing.
plan.enabled true Keep an external plan for work with dependent phases.
condense.enabled true Narrow oversized tool output to the lines the task needs.
condense.adaptive false Adjust the size trigger during a session from the savings seen so far. false keeps the fixed value.
condense.tokens_threshold 5000 A single text result above this estimated token count is a candidate for condensing. 0 turns condensing off.

When condense.adaptive is true, the trigger is the configured value times a factor that starts at 1.0 and stays between 0.5 and 2.0.

[inject]

Sections of project documents that are put into the conversation when the agent works on a file they name. See Mechanics.

Key Default Meaning
enabled false Turn the mechanic on.
max_depth 2 How many references deep to follow, starting from AGENTS.md or CLAUDE.md.
max_files 200 Most documents kept for one session.
max_file_bytes 65536 A larger file is not read.
max_unit_tokens 600 A section longer than this (estimated tokens) is cut into parts of this size.
max_units_per_injection 3 Most sections added at one point of the conversation.
max_tokens_per_injection 1200 Most tokens added at one point, counting the lines around each section.
max_tokens_per_turn 3000 Most tokens added during one turn.
max_live_tokens 12000 Most tokens of added sections that may be in the conversation at once.