Daemon & sessions

A session is one running conversation with an agent: its messages, tool calls, and state.

Sessions are not owned by your terminal. They are owned by a local daemon, and every client — the TUI, the web UI, Telegram — is a thin attachment to it. Close the terminal and the agent keeps working; reattach later and you pick up the live transcript, mid-turn.

The daemon speaks HTTP+SSE over a Unix socket, so it is local by default. It starts on demand the first time a client needs it.

Managing it


boba daemon status              # pid, uptime, live session count
boba daemon logs -n 200         # recent log
boba daemon logs -f             # follow
boba daemon restart             # stop + start
boba daemon stop                # graceful stop

stop and restart refuse while sessions are still running. Pass --force when you mean it.

To run the daemon in the foreground instead — useful when you want its output in front of you, or under a supervisor like systemd or launchd:


boba daemon

Config and extension changes need a restart. The daemon builds the runtime once at startup. After editing botbandit.config.yaml or anything in ~/.botbandit/extensions/, run boba daemon restart — otherwise you are still talking to the old wiring.

Working with sessions


boba                            # new session in the TUI
boba --profile coder            # new session on a specific profile
boba run "one-shot prompt"      # no TUI, prints the result
boba resume <sessionId>         # reattach to an existing session

One more session-shaped command worth knowing:


# Run a markdown document's body as a headless session (cron-friendly)
boba run-task ./daily-triage.md --profile coder

run-task is the building block for scheduled work: the document body is the prompt, a profile: in its frontmatter picks the model (--profile overrides), and --json emits raw session events for piping.

Where a session runs

Each session is bound to a working directory. A session launched from a project directory works there; one launched with no project lands in a neutral scratch home rather than wherever the daemon happens to have been started. That matters because the daemon is long-lived and its own cwd is an accident of how you started it.