Configure Agent¶

Host installations use /etc/obs-agent/config.toml. The installer creates this file. Back it up before editing, then validate it and restart the service. The file contains credentials. Keep ownership root:obs-agent and permissions 0640. Do not attach the complete file to a public issue.

Edit configuration¶

config_version = 1

[beak]
url = "https://beak.example.com"
agent_id = "replace-with-agent-id"
api_key = "replace-with-agent-api-key"

[llm]
# model = "auto"
# request_timeout = "5m"
# max_tokens = 0

[runtime]
working_dir = "/var/lib/obs-agent/work"
# http_allowed_domains = ["example.com", "api.example.com"]

[profile]
cache_dir = "/var/lib/obs-agent/profile-cache"

[logging]
level = "info"
# format = "text"

[update]
base_url = "https://releases.example.com/obs-agent"
# auto_enabled = true

[tools.browser]
# enabled = true

[tools.web_search]
# enabled = true

The installer writes required and explicit settings. Unset fields use known environment variables or built-in defaults. Uncomment an example field to set it explicitly. If update.socket_path is unset, the Agent uses update.sock beside update.state_path; no placeholder path is required.

Runtime and tool time limits¶

An 8-hour limit does not extend the 2-hour execution limit. Subagents inherit parent cancellation. A wait_for request that exceeds the parent's remaining time is rejected. To run longer tasks, set runtime.max_run_duration explicitly and keep suitable subagent and wait limits.

When the soft budget expires, the Agent waits for active model requests, including streaming and compaction requests, or tools to finish. It keeps valid final answers. If more work is needed, it starts no new tools and requests at most one summary. A failed summary returns a checkpoint. Actual duration can exceed the budget. If the context cannot hold a summary, or sensitive configuration can only be shown as structured output, the Agent returns a checkpoint directly.

When a time limit is enabled, each model request, including retries, ends with a temporary user message that gives the total, elapsed, and remaining time. This message is not stored in session history. It excludes tool counts, model call counts, and token usage. Call and token totals remain internal diagnostics and no longer stop a run. No budget message is added when the time limit is disabled.

In a connected obscli session, use:

Settings persist and affect the current and later runs. Each run starts a new timer. Runs that already entered the summary phase do not resume investigation. Active subtasks follow parent limit changes but keep shorter independent limits. The API is GET/PUT /api/v1/sessions/:id/max-run-duration; a PUT body can be {"duration":"+5m"}. Only session participants with write permission can change it. applied means the connected Agent acknowledged it. pending, offline, and unsupported do not mean it is active.

Approval waits count toward the budget. At expiry, waiting ends and unexecuted tools do not run. Late approval cannot restart a stopped action. Changing the run limit recalculates the wait deadline. Browser control approval still expires independently after 30 minutes; extending the run budget does not extend that approval. Manual cancellation, model request timeouts, and tool timeouts remain independent.

For example, set max_run_duration = "4h" in the existing [runtime] section to allow four hours, then validate and restart as shown below. Hosts and containers default to two hours. Containers can set AGENT_MAX_RUN_DURATION=4h.

Use true or false for booleans, unquoted numbers, arrays for lists, and duration units such as "5m". Unknown fields and tables are ignored, including old max_llm_calls and max_run_tokens. Known fields still require valid types and values. Invalid syntax and unsupported configuration versions are rejected. Old environment limits and the AGENT_MAX_TOOL_CALL_ITERATIONS alias are no longer read.

Configuration precedence¶

For host installations, precedence is TOML, known environment variables, built-in defaults. A present field overrides the environment even when its value is "", false, or 0. An invalid value causes an error; it does not fall back.

The default file is /etc/obs-agent/config.toml. If it is absent, the Agent falls back to the released agent.env format. It does not merge both files. Upgrades migrate the old file and keep a backup. Existing TOML settings and user comments remain.

For a TOML-capable Agent, the Linux installer creates a service that explicitly uses --config /etc/obs-agent/config.toml. Upgrade preflight uses the same file. The main service does not load the compatibility agent.env; old updaters still use it.

Delete or comment out a field to allow environment variables or defaults to supply its value. config_version = 1 is the configuration schema version, not the Agent release version. Unsupported versions are rejected.

Agent configuration tools change only permitted settings and preserve comments, blank lines, and other fields. Concurrent edits cause an outdated change to be rejected. Read the file again before retrying.

Validate, export, and restart¶

sudo cp -p /etc/obs-agent/config.toml /etc/obs-agent/config.toml.bak
sudo vi /etc/obs-agent/config.toml
sudo obs-agent --config-tool agent-export \
  --input /etc/obs-agent/config.toml --output /etc/obs-agent/agent.env
sudo systemctl restart obs-agent
sudo systemctl status obs-agent

Do not restart if validation fails. The export command writes only known settings to a file that old updaters can read. Do not edit the generated agent.env. Agent configuration tools synchronize this file.

To select another file, use obs-agent --config /path/to/config.toml. Do not combine this option with the old --env-file option.

If the service cannot start, restore the backup and regenerate the compatibility file:

sudo cp -p /etc/obs-agent/config.toml.bak /etc/obs-agent/config.toml
sudo obs-agent --config-tool agent-export \
  --input /etc/obs-agent/config.toml --output /etc/obs-agent/agent.env
sudo systemctl restart obs-agent

Upgrade from legacy configuration¶

The first host upgrade to a TOML-capable version converts and validates agent.env before switching. No manual conversion or field mapping is required. Valid known settings remain, including values equal to defaults. Empty legacy values retain their old meaning: unset.

Unknown variables do not enter TOML. The installer reports only their names and preserves the original file in a backup. Review these variables for their original purpose. There is no generic environment variable group.

Old updaters keep their existing command and need no new arguments or prior self-update. Idle protection remains. If migration or startup fails, the upgrade restores the old program, configuration, and service. A confirmed historical runtime without the idle protocol can interrupt work during its first transition. The upgraded runtime uses idle protection.

Configure container Agent¶

Containers use environment variables only. They do not read or generate config.toml and do not support Agent file arguments --config or --env-file. Use the environment settings provided by the Docker, Compose, or Kubernetes installation page.

Docker's --env-file argument still works: Docker injects variables into the container; the Agent does not read that file. See the container installation guide.

Upgrade compatibility¶

LocalProvider no longer reads or forwards agent_max_llm_calls or agent_max_tool_call_iterations.

Released installation protocols still accept and forward old limit fields for older Agents and installers. New Agents do not read or enforce these fields.

BREAKING CHANGE: New Agents no longer enforce cumulative call or token limits. Before deployment, check that cost controls do not depend on these fields. Upgrade Beak first, then Agents through the existing installation or automatic upgrade flow. Older Agents can connect and chat but do not apply session limits. The optional session_run_duration=v1 capability identifies support. Rolling back an Agent restores old limits and ignores session overrides. Keep session settings for a later upgrade. Do not remove the nullable run_duration column when rolling back Beak. Installer and updater invocation contracts remain unchanged.