The user-facing surface is intentionally small: run a server, run the all-in-one dev rig, and wait on either.
serve(; host, port, public_url, auth, state_dir, working_dir) → Bonito.ServerStart the BonitoAgents dashboard server, in one of three ways (identity.jl): for this machine (LocalAuth, the default: localhost only, whoever reaches it is the one account, and so is every worker); for a trusted network (NetworkAuth: any host, still no login, workers join with a credential from "Add worker"); or behind the login proxy the installer sets up (ProxyAuth(...), from <state_dir>/proxy.json: localhost only, Caddy + Authelia authenticate every request and say who it is from).
Routes: / — dashboard (workers + projects) /p/<projectid> — chat UI for one project /install — OS-sniffing bootstrap (curl … | sh / irm … | iex) /install.sh — bash wrapper (Linux / macOS) /install.ps1 — PowerShell wrapper (Windows) /install.jl — cross-platform worker installer (used by the wrappers) /w (WS) — the ONE connection each worker holds open: a WorkerLink carrying its control channel, its agents' ACP sessions and its file transfers (see workerclient.jl)
public_url is the base URL workers see (and what the install script tells them to dial back); behind the proxy it defaults to https://<domain>. manage_harnesses sends workers the agent adapters to keep installed (harness_spec). Off by default, so a test or dev server never has its workers download Node and npm packages; the server processes (start_server, the desktop app) turn it on.
state_dir overrides where workers.json / projects.json are persisted (default: ~/.local/share/bonitoagents-server). apps the apps the server runs, by type ((BonitoTodo.TodoApp, MyApp); see apps.jl). Passing this is explicit; by default the built-ins plus installed opt-in plugins are used ([bonitoagents] plugin = true). working_dir overrides where canonical project copies live on the server. Each project lives at <working_dir>/<name> and is mirrored onto the worker at <worker.projects_root>/<name>. (default: ~/bonitoagents-server)
dev_server(; port=nothing, name="dev", auto_open=false) -> DevHandleBoot a self-contained BonitoAgents server + a local worker in this process. All state lives in mktempdir()-allocated directories and is removed when you call close(handle) (or when the Julia process exits — an atexit hook is registered).
The worker is a separate BonitoWorker.start() process: it dials the server's /w over loopback. No systemd, no install script.
proxy = DevProxy(...) puts the real login proxy in front, as an install has it: Caddy (with its own certificate authority) and Authelia, rendered from the same code, the worker coming in through Caddy with its credential, and handle.url Caddy's https://<domain>:<port>. The e2e items for the login use it.
network = true runs it the way a trusted network's server runs (NetworkAuth: no login, and the worker comes in with a credential "Add worker" issued, which the server checks itself), still on localhost.
manage_harnesses = true has the server declare the agent adapters, which the worker then installs (off by default, so a dev server's worker downloads no Node).
apps are the apps the server runs, by type, as for serve. Omit it to use the built-ins plus opt-in packages installed in the active environment; pass it explicitly for an isolated development rig.
If claude-agent-acp isn't on PATH the dashboard still works (worker registration, sidebar, project import, file pickers); only opening a chat session against the worker will fail at the agent spawn step.
h = BonitoAgents.dev_server(; port = 8138, auto_open = true)
# Click around in the browser...
close(h)Or as a do-block (recommended, cleans up on exception / Ctrl+C):
BonitoAgents.dev_server() do h
BonitoAgents.wait!(h) # blocks until Ctrl+C
endwait!(handle)Block until Ctrl+C, then return so the caller's cleanup runs. Useful from scripts and bin wrappers that start a dev_server and should stay up until interrupted; from the REPL just keep the handle and run other code in parallel instead.
AppUIStylesThe server's theme and shared control styles, for plugin-specific layouts using the public BonitoWidgets --bw-* theme variables. Components below include it automatically. Host theme overrides apply to plugin controls as well.
The apps a server runs unless told otherwise (serve(; apps)).
AppCallOne call of an app tool: the server (call.server), the chat whose agent called it (call.caller, a ProjectInfo) and the arguments (call.args, a NamedTuple by the tool's parameters).
Only the app's own chat gets the tool.
sourceAppContextWhat the server hands an app it starts, as MyApp(ctx): the server (ctx.server, for the platform functions like start_chat!) and the directory the app keeps its files in (ctx.dir, <state_dir>/apps/<app_id>, created on first write).
AppError(msg)A request an app cannot do as asked: no such item, a folder that isn't there. An agent gets msg as its tool's error; the server log does not, since nothing went wrong on this side.
The chats the app started with a key (see start_chat!) get the tool; in_scope checks the key with prefix.
AppTool(name, description, params = (;); scope = EveryChat())A tool an app adds to the agents' MCP: params is a NamedTuple of Params, scope a ToolScope. The name must be unique across the server's apps and BonitoMCP's own tools; prefixing it with the app's id keeps it so. A call runs call_tool(app, Val(name), call).
AppTool(:notes_add, "Add a note.", (text = Param(String, "The note."),))The composer: the message input with its attachments, send modes, queue, Stop and Send.
sourceChatFolderA folder chats run in: the worker (worker, a WorkerInfo, or nothing for one that was removed; worker_id either way), the folder on it (path), its chats with the most recently active first (chats, ProjectInfos) and when the last of them was active (last_active, unix time, 0 for never).
The chat's header: title, folder, session pills, menu and the lens bar.
sourceThe provider's warnings and errors about the chat's session, hidden until there is one.
sourceThe row below the composer, filled by the chat module.
sourceThe message list: the transcript with its rail, the busy, thinking and waiting lines under the last message, and the taskbar floating over it. Takes the space its parent gives it (a flex child that grows).
sourceEvery chat's agent gets the tool.
sourceMeshViewer(url, path; mode = InlineView())three.js viewer for the model at url (format from path), with its toolbar, status line, styles and driver, so it works in any session. PanelView() fills its container; InlineView() is a box of its own height.
Param(T, description)
Param(T, description, default)A parameter of an AppTool: an argument of Julia type T (String, Int, Float64 or Bool), required unless it has a default. The tool's JSON schema is made from it, and the call's argument is checked and converted to T before call_tool sees it.
ServerState(; state_dir, working_dir, auth = LocalAuth(), manage_harnesses = false,
apps = BUILTIN_APPS) → ServerStateConstruct a fresh state, loading workers + projects from state_dir (workers.json, projects.json). working_dir is created if missing. apps are the types of the apps the server runs (apps.jl), started here.
A person using the dashboard.
sourceAppButton(content...; variant=:primary, size=:normal, class="", attributes...)A server-styled button. variant is :primary, :secondary, :ghost or :danger; size is :normal or :small. Other attributes (including reactive disabled, onclick, and plugin data attributes) pass through to the button.
AppButton("Save"; onclick = js"e => $(saved).notify(true)")AppCard(content...; class="", tag=:div, attributes...)A themed surface using the server's shared border, radius and shadow. Padding and layout belong to the caller. tag may be :div, :section or :article.
AppModal(content::Function, open::Observable{Bool}; title="")The same BonitoWidgets modal used by the server. Its body is built afresh on each open and removed on close; Escape, the close button and backdrop dismiss it. Set open[] or notify it from a browser controller to open/close it.
AppModal(is_open; title = "Add account") do
DOM.div(account_form())
endapp_allowed(app, user) -> BoolMay user use app: see it on the dashboard, and have its tools in their chats? Admins only by default: an app's state is the server's, so a member's agent reading it would read everyone's.
app_briefing(app, key) -> StringThe briefing of the app's chat with key (see start_chat!): by default app_briefing(app) for the app's own chat (key "") and nothing for the chats it started.
Markdown appended to the system prompt of the app chat's agent.
sourceapp_chat(server, app) -> ProjectInfo | nothingThe app's chat: the newest one marked with its id and no key ("Continue on" leaves the original behind), or nothing before it was first opened.
A few lines about the app: its tile's details on the dashboard, and the setup dialog.
sourceapp_icon(app) -> String | nothingThe app's logo: the path of a square picture file that ships with the app (an SVG or a PNG, e.g. joinpath(@__DIR__, "logo.svg")), shown on its dashboard tile and as its chat's icon. nothing (the default) gives a tile with the first letter of its title.
app_id(::Type{<:AgentApp}) -> StringThe app's name for the machine: a short lowercase word, unique on the server. It marks the app's chat (ProjectInfo.app), names its directory and should prefix its tools' names. The one method an app must define, on its TYPE: the server needs it before the app exists, to find its directory.
What the app is called in the UI. Defaults to its id.
sourceatomic_write_json(path, data; mode = nothing)Write data (anything JSON can encode, structs by their field names) to path as indented JSON, all or nothing: a crash leaves the old file or the new one, never half of one. Makes the directory if it is missing.
caller_user(call) -> UserThe person whose chat made call. Always known: a chat whose owner has no account gets no app tools at all.
chat_file_url(view, path) -> StringThe URL a browser loads file path from, on the worker the chat view shows runs on: for a pane that shows files, e.g. as media_element(url, mime, is_video).
chat_folders(server, user) -> Vector{ChatFolder}The folders user's chats run in, the most recently active first. Apps' chats are left out: their folders are the apps', not the user's projects.
chat_key(view) -> StringThe key of the app chat view shows ("" for the app's own chat), for a chat_pane that lays out several chats of one app (see start_chat!).
chat_pane(app, view) -> DOM node(s)The open chat pane of one tab: what view (that tab's copy of the chat's model) shows, for a chat of app, or nothing for an ordinary chat. An app implements its own method to lay its chat out. What it returns, one node or a tuple of them, is placed in the chat's root: a flex column filling the pane, with data-app set to the app's id for its styles.
The pieces it can use are the ordinary chat's, as components: ChatHeader, ChatNotice, ChatTranscript, ChatComposer and ChatToolbar. Each can appear once per pane, nested as deep as the layout wants.
The title of chat pid, or nothing for a chat that is gone.
find_worker(server, user, name) -> WorkerInfo | nothingA worker user may use, by its id or its name (any case).
load_json_tolerant(path, label[, T]) -> value | nothingRead the JSON file path (as a T, a struct JSON maps by its field names, when given), or nothing when there is none. A file that does not parse (a crash before writes were atomic, a hand edit gone wrong) is moved aside as <file>.bad-<time> with a warning naming label, and also gives nothing: better to start empty than to refuse to start the server. Its counterpart is atomic_write_json.
Register an app type from an opt-in plugin package. Registering twice is harmless.
sourceThe app types registered by packages loaded as BonitoAgents plugins.
sourcerelative_time_label(t) -> StringHow long ago unix time t was, for a label: "just now", "5m ago", "3h ago", "2d ago".
send_message!(view, text; mode = :done)Send text to the chat as the user's message, as the composer does: queued until the agent is done with its turn by default.
show_chat!(view, pid)Show chat pid in the window view (a tab's view of a chat, as chat_pane gets it) is open in.
start_chat!(server, owner, worker, path; title = "", prompt = "", app = nothing, key = "") -> ProjectInfoA new chat in folder path on worker, belonging to owner, brought up and sent prompt as its first message. Throws AppError for a worker that isn't connected and for a path that isn't a folder there.
With app, the chat is one of that app's, told apart from its others by key (not empty: "" is the app's own chat): its pane is the app's chat_pane and its agent gets the app's briefing for that key (app_briefing) and the tools in scope for it (AppKeyedChats). The pane reads the key with chat_key.
switch_provider!(model::ChatModel, new_provider::BinAgent) -> Union{Nothing,String}Switch the agent backend for a chat. The switch is transactional: it starts a fresh session under new_provider and persists the choice only after that session is live. If startup fails, it restores the previous provider and its resumable session id; a previously live chat is brought back up on that provider. Returns the failed startup's concrete error text, or nothing on success.