Boba

Run your own crew.

Run agents across terminal, web, and chat — on your machines, with your models and tools.

Boba is the operator's seat for AI agents. It coordinates and runs agents, connects them to your terminal, browser, and Telegram, works with whatever models you point it at (hosted or local), and keeps you in control of your machines, models, data, and workflow. It's sharpest today for coding work, but it isn't limited to it.

Early preview. Boba is under active development and interfaces may change between releases.

npm install -g botbandit
boba

Quickstart

1. Install (single self-contained binary, no Node/Bun required at runtime):

   npm install -g botbandit

   This installs the boba command (and botbandit as an alias for it).

2. Run it.

   boba

   With no config on disk, the first run opens a setup wizard. It detects agent CLIs already on your PATH — claude (Claude Code) and codex — and builds a config around them, so if you have one you need no API key. Otherwise it walks you through a provider: a ChatGPT subscription via OAuth, OpenAI, OpenRouter, Alibaba, or Ollama (it probes your local models).

   The wizard writes ~/.botbandit/botbandit.config.yaml and starts your first session. Re-run it later with boba init.

3. Or run a one-shot prompt:

   boba run "Summarize what this repo does."

4. In the TUI:

   • /exit or /quit to leave
   • Esc interrupts a running turn; Ctrl+C twice force-quits

Embedding the CLI

The package also exports its platform launcher for Node-based wrapper CLIs. It preserves the real terminal streams required by the interactive TUI and returns Boba's exit status.

import { runBoba } from "botbandit";

process.exitCode = runBoba(process.argv.slice(2));

Wrapper CLIs can isolate every Boba-owned path and process-external resource:

process.exitCode = runBoba(process.argv.slice(2), {
    appHome: "~/.my-app",
    configPath: "~/.my-app/config.yaml",
    namespace: "my-app",
    commandName: "my-app",
});

With these options, config discovery is pinned to the explicit file, durable state lives below appHome, tmux sessions use the supplied namespace, and an unreachable configured daemon is an error instead of silently creating a local runtime.

What you get

• A terminal UI (TUI) — the primary way to drive agents interactively.
• Multiple agents & sub-agents — coordinate a crew, not just one chatbot.
• Tools with approvals — agents read/write files, run shell, and more; risky actions can require your sign-off.
• Memory, tasks, and scheduling — agents that remember, track work, and run on a timer.
• A live terminal and diff view — watch what your agents are doing.
• Telegram and a web UI — reach your agents from outside the terminal (the web UI is self-hostable and currently alpha).
• Any model, your infra — hosted or local, your data stays on your machines.

Configuration

boba init writes a working config, so you normally start from that rather than a blank file.

Boba loads botbandit.config.yaml (or .yml) from the first of:

1. BOTBANDIT_CONFIG_PATH, if set (missing file = hard error)
2. The current directory — so a project can carry its own
3. The application home, ~/.botbandit/ (where the wizard writes it)

The first file found wins; they are not merged. Within a run, values resolve environment variables → the YAML file → defaults. BOTBANDIT_HOME relocates the application home.

Common environment variables:

• BOTBANDIT_PROVIDER — e.g. codex, alibaba
• Codex: BOTBANDIT_CODEX_MODEL
• Alibaba/DashScope: ALIBABA_API_KEY (or DASHSCOPE_API_KEY), BOTBANDIT_ALIBABA_MODEL, optional BOTBANDIT_ALIBABA_BASE_URL
• OpenAI-compatible: provider config with baseProvider: openai-compatible, baseURL, apiKey, and models
• OpenRouter: OPENROUTER_API_KEY, with models under providers.openrouter.models in the config file

Secrets in config values support two schemes:

• plain:<value> (default)
• env:<ENV_VAR_NAME>

License

Licensed under FSL-1.1-ALv2.