Skip to content

Getting Started

This page takes you from nothing to a running, persistent agent project. For a guided, example-first path, follow the Tutorials; this page is the quick linear version.

Prerequisites

  • Python ≥ 3.13.
  • An LLM API key for a provider LiteLLM supports (e.g. OPENAI_API_KEY, GEMINI_API_KEY, ANTHROPIC_API_KEY).

Install

The CLI ships as the boscli distribution. Run it without installing, using uv:

uvx boscli ask "how are you" --model openai/gpt-4o

Or install it permanently:

uv tool install boscli      # or: pipx install boscli

pip install bos-ai installs the library and provides no boscli command. That is the install to use when you are embedding BOS rather than running it — see Embedding BOS.

Install Adds
bos-ai The library: bos.core, bos.config, plugins
bos-ai[litellm] The built-in LLM provider. Without it, register your own with @ep_provider
bos-ai[gateway] The gateway process and the Telegram/Lark channels
bos-ai[search] The built-in web-search and page-fetch tools
bos-ai[lark] The Lark/Feishu SDK
bos-ai[cli] The CLI's dependencies — run it with python -m bos.cli
bos-ai[codex] The Codex external agent runtime (BEP 19), with the vendor's codex CLI binary
bos-ai[claude-code] The Claude Code external agent runtime (BEP 19), with the claude CLI bundled in the claude-agent-sdk wheel (~230 MB)
bos-ai[all] Every extra above except codex and claude-code, which each bundle a vendor CLI binary

The codex and claude-code extras let a BOS agent run on Codex or Claude Code — see External agents for declaring, configuring and logging in.

First run (no project)

OPENAI_API_KEY=<api-key> boscli ask "how are you" --model openai/gpt-4o

The model string is provider/model. The provider prefix selects a custom provider if one is registered under that name; otherwise it falls back to LiteLLM, which reads the matching *_API_KEY environment variable. For a DeepSeek model, for example:

DEEPSEEK_API_KEY=<api-key> boscli ask "how are you" --model deepseek/deepseek-v4-pro

Create a project

mkdir my-agent && cd my-agent
boscli init          # guided setup: purpose, archetype, provider/model
boscli gateway start # start the agent runtime
boscli tui           # connect the terminal UI

boscli init writes a runnable baseline under .bos/:

.bos/
├── config.toml      # your one config file
├── .env             # provider keys and secrets
├── agents/          # add specialist agents here (*.md / *.toml)
├── extensions/      # add custom tools here (*.py)
└── skills/          # add skills here (dirs with SKILL.md)

To see every option documented inline, run boscli init --minimal in an empty directory — it emits the fully-commented reference config.

Verify your setup

boscli inspect       # show the resolved harness, config, agents, and actors

Grow the project

Embedding BOS in your own application

pip install bos-ai is a library install — no console script, no terminal UI, no gateway process. Configuration is a plain dict, so it can come from a database, your environment, or a control plane rather than a TOML file on disk.

There are two ways to embed, and which one you want is a decision to make before you write code: call the agent from your own process (bos.sdk, BosApp), or mount the gateway's whole runtime inside your own web application (GatewayMount). Embedding BOS covers the choice, both modes, and the supported API surface.

Where to go next

  • Tutorials — a hands-on path from your first agent to a packaged, shareable extension.
  • Concepts — how the runtime, agents, actors, memory, and skills fit together.
  • Configuration — the complete config.toml reference.
  • Extending BOS — write tools, plugins, channels, and providers.