Common operational procedures¶
Earlier technical reference
This page is retained from earlier documentation and has not been fully revalidated for the public 2026.10.19 release. Its revision-specific links and examples may describe older or development behavior. Start with the current public-release user guide; do not use this page alone to select installation commands, image tags, or security settings.
These recipes describe 2026.10.10.4 and assume the default native user installation. For containers, use the corresponding container commands. Replace example agent/session IDs with real values and run as the installation owner.
Start, stop, inspect¶
"$HOME/.burrow/bin/burrow" service start
"$HOME/.burrow/bin/burrow" service status
"$HOME/.burrow/bin/burrow" service logs -n 100
For a deliberate restart:
- Check active conversations and task executions before restarting; stop or wait for consequential work to settle.
- Run the restart and status commands, then check the health response and logs.
- Confirm the reported version is the intended release and the UI loads the expected agent registry.
Shutdown records interruption evidence, but recovery is not a guarantee that external actions can safely be replayed. If health fails, inspect service logs and the configured listener before repeatedly restarting. If authentication is enabled, use the authenticated UI or an authorized client for protected health details; do not disable authentication to make a probe pass.
Change listener settings¶
The installer owns the durable native host/port settings. Apply explicit values during installation or update:
This also performs the normal application update. It is not a settings-only operation. For a deployment that must retain its current app revision, review the existing environment and supervisor configuration using the configuration reference, then make an operator-controlled settings change and restart.
Do not switch to 0.0.0.0 without reviewing network exposure.
Inspect a completed run¶
Run CLI readers as the installation owner using the installed launcher. Current readers resolve the configured PostgreSQL lifecycle and managed socket; do not copy database settings from another installation. See managed reader connection.
"$HOME/.burrow/bin/burrow" trace \
--agent-id assistant --run-id RUN_ID --json
"$HOME/.burrow/bin/burrow" session-search \
--agent-id assistant --session-id default --query 'release decision' --json
Use an explicit run ID for incident investigation. --latest is useful for exploration but can select newer work than the incident being investigated. Keep tool-output/trace artifacts private until reviewed.
Stop a chat¶
- Open the intended agent and session; confirm the displayed run is the one to stop.
- Choose Stop response (square icon) or send
/stopin that conversation. Closing a tab is not cancellation. - Wait for active-run state to settle, then inspect the recorded tool activity and final/cancelled outcome.
- Before retrying, verify any external changes already made. If Could not stop run appears, recheck the active run rather than assuming the request succeeded.
If the intent is to correct work rather than stop it, send a follow-up while the run is active. Confirm whether it is pending, delivered to the run, or retained as an undelivered follow-up. A pending steering message waits for a model boundary. Sources: , .
Execute and verify a board task¶
- Open Tasks, create a project if needed, and create or open a task.
- Fill in the description and Assignee, then save. Execute uses only the saved task and rejects unsaved edits.
- Choose Execute on a task that is neither Done nor cancelled. Expect a running execution receipt and the Live execution panel.
- Follow progress; the UI polls active runs and reloads the task after execution ends. The assigned agent runs the task in its default conversation, with project context scoped to this task run.
- Inspect the default conversation and Archive → Proof for its final answer, blockers, and verification. Update the board status to reflect the reviewed outcome.
The dispatch lookup is awaited in this release; the former unassigned-task warning is obsolete. Execution success does not automatically move a task to Done. A progress panel may remain visible during a transient status-poll failure. Check runtime activity and the task's persisted execution before retrying; a disconnected browser does not prove dispatch failed. Project paths supply context, not filesystem authorization. Sources: , , .
Recover a prior decision or saved memory¶
- For an original conversation, open Archive → Chat, filter by agent and date or search text, and open the session.
- Choose Load earlier messages until the relevant passage is available. Copy loaded chat copies only what has been loaded. A load error or Earlier retained history is unavailable is not the beginning of history; retry or restart from latest as offered.
- Ask the owning agent to use
session_searchwhen you need historical decisions, reset snapshots, or an expanded original with neighboring messages. Check the returned date and source provenance. - For an explicit saved memory, open Brains, select Agent owner, and search. Open the entry to inspect its content, source references, origin, and revision.
- To correct it, edit and choose Save memory. On a conflict, preserve your intended wording elsewhere, Reload memory, compare, and reapply only the desired correction.
Brains records are agent-owned saved context, not verification of current runtime state. Legacy migration details explain origin; they do not certify present truth. Brains does not provide the old global knowledge, Recall, or purge controls. Sources: , , .
Delete saved memories deliberately¶
- Confirm the agent owner and exact memories. Save any recovery copy you require before deletion.
- Use Delete memory, or check selected entries and use Delete selected memories. Select page affects only that page.
- Inspect each bulk result: these are separate deletions, so some can succeed while others conflict or fail.
- Reload list and review current revisions before retrying failed entries.
These controls delete immediately without a separate UI confirmation. Memory deletion does not delete conversation originals, attachments, browser caches, or other retained evidence. The legacy Albdruck conversation-purge route adapter is not mounted in this release; its historical procedure is not a supported erasure workflow. Sources: , .
Retention maintenance¶
Use Settings → General → Trace retention for managed trace cleanup:
- Take a recovery backup if traces may be needed for incident review.
- Choose the maximum age and/or storage limit and a cadence between 15 minutes and 7 days. Enable managed cleanup only when those limits are intended.
- Choose Save policy. Expect confirmation that the policy was saved.
- Choose Preview cleanup and inspect the trace count and reclaimable bytes. The UI summarizes the plan; it does not display individual paths.
- If the saved, previewed policy is still the intended one, choose Run now. Any form edit requires saving and previewing again.
- Check the cleanup result, last-run status, next-run status, and any error. A zero count may simply mean no trace qualifies.
Managed cleanup is disabled until enabled with at least one limit. This surface removes trace data, not Brains records or a selected conversation. If a save/preview fails, resolve that error before proceeding. Do not use a different policy surface merely to bypass the guard. ]
CLI retention is a separate policy¶
The CLI reads environment/default retention values. It does not read the persisted Settings policy or its disabled flag. Defaults are 60 days for eligible main-kind sessions, 30 for task sessions, and 7 for subagent sessions; trace age/byte limits are unset unless configured. A disabled UI policy does not make CLI --confirm harmless.
With the correct database connection (use the managed subshell above when needed), preview the full target list:
Do not use --summary as the only deletion review: it hides individual candidates. Only after inspecting this CLI-specific plan and a recovery backup should an operator deliberately add --confirm to the same invocation with unchanged inputs. Avoid adding duplicate cleanup timers alongside the runtime scheduler.
Add a read-only database operator¶
For a running managed database, postgres-access creates dedicated SQL-reader roles. It requires the same OS owner and lifecycle environment as the server. This is privileged credential administration, not a harmless status check:
With deliberate authorization, create --name NAME, rotate --name NAME, and revoke --name NAME administer those roles. Create/rotate prints the new password once in JSON. Capture it securely, never in shared logs. The role can read sensitive application tables; read-only access is still data access. See CLI.
Remove the application¶
To remove the app and launcher while retaining durable state:
Full removal also destroys the installation's durable state. Back up first, then use uninstall --purge only when that destruction is intended. Noninteractive uninstall requires explicit --yes. Container volume deletion is a separate destructive operation.
Source evidence¶
Additional implementation evidence: , .