竹子AI代理

First-run setup

Configure a provider + API key without hand-editing JSON:

```bash

verify the install (config present, provider keyed, server reachable)

bamboo doctor

build & run from the workspace

cargo run --bin bamboo -- serve

or install then run

cargo install --path . bamboo serve ```

Arguments supported by bamboo serve (all override the config file): --port, --bind, --data-dir, --static-dir, --workers (plus --parent-pid, a sidecar orphan-guard: the process exits when that PID goes away).

Frontend build contract

Normal Bamboo builds require the staged frontend package owned by crates/app/bamboo-server/frontend_package. The build validates the sidecar manifest, the matching manifest inside the zip, portable archive paths and payload integrity, the index.html entry, and the manifest hash shape. Missing or invalid assets stop the build with an actionable staging instruction instead of silently producing an API-only server. Refresh the committed package explicitly with:

node scripts/frontend-package.cjs stage

Cargo never runs that staging command implicitly. This removes the previous ignored child-process status: explicit local and GitHub Actions callers receive the stager's nonzero exit status before build.rs validates the resulting crate-owned bytes.

An intentionally frontend-free binary remains available for infrastructure that supplies only Bamboo APIs. Select it at build time (never as an implicit fallback):

BAMBOO_FRONTEND_BUILD_MODE=api-only cargo build --bin bamboo

PowerShell:

$env:BAMBOO_FRONTEND_BUILD_MODE = "api-only"
cargo build --bin bamboo

That setting disables only the compiled-in package. Existing runtime frontend discovery remains unchanged: --static-dir, BAMBOO_FRONTEND_PACKAGE, or a legacy package candidate beside the working directory/executable can still provide a frontend.

Other subcommands (bamboo --help / bamboo <cmd> --help for the full list):

TUI bindings are context-aware and configurable with --keymap; see TUI keybindings for the JSON schema, safety rules, and terminal fallbacks.

The admin commands (health / status / sessions / stop / history / respond / session / schedules) are thin HTTP clients over a running bamboo serve; point them at a non-default server with --server-url / --port / --data-dir. The read commands (skills list / mcp list) work offline against --data-dir (default ~/.bamboo); the other mcp verbs are server-backed and take the same connection flags. (bamboo subagent-worker also exists but is an internal worker process spawned by the server — not for interactive use.)

A global --log-level <error|warn|info|debug|trace> sets the default log level for any command when RUST_LOG is unset (RUST_LOG still wins when present). bamboo serve defaults to info in every build profile. Embedded debug builds keep debug on stdout while date-rotated files default to info; at startup, strictly matching historical files are retained by both count and a 128 MiB total byte budget. Daily rotation continues during long-running processes, and startup limits are enforced again on the next process start. Use --log-level debug, -v, or RUST_LOG to opt into more detail; target-specific directives such as RUST_LOG=h2=debug override the dependency-noise defaults while leaving each sink's root default unchanged.

Defaults (verified against code):

• HTTP API: http://127.0.0.1:9562/api/v1 (port defaults to 9562, bind defaults to 127.0.0.1)
• Health: GET /api/v1/health
• Data dir: BAMBOO_DATA_DIR or ${HOME}/.bamboo
• Default provider: anthropic

Search-index upgrade: Before upgrading session_search.db from schema 3 to 4, stop all older Bamboo servers, workers, and embedded writers that share the data directory. Startup migrates this derived search cache in one atomic transaction; a failed migration preserves the previous schema and cache contents. Running old and new writers together during a rolling upgrade is unsupported because older writers can reset the schema version and do not preserve the new search row identities. Canonical session data is unchanged; do not delete it to perform or recover this upgrade.

Docker

cd docker && docker compose up -d --build
curl http://localhost:9562/api/v1/health

docker-compose.yml publishes to the host loopback only (127.0.0.1:9562:9562), runs as a non-root user, drops all capabilities, and uses an isolated named volume. Do not widen the publish to expose the agent directly on a network: a fresh instance is unauthenticated, and the server treats every private-LAN (RFC1918) peer as trusted-local and skips the password check by design — so LAN exposure is unauthenticated even after you set a password. To reach it from other machines, keep the loopback publish and front it with an authenticating reverse proxy on a trusted network. It also sets BAMBOO_DATA_DIR=/data, BAMBOO_PORT=9562, BAMBOO_BIND=0.0.0.0 (in-container bind; exposure is controlled at the publish layer).

Quick Start & Development

Building Bamboo from source requires Rust 1.95 or newer.

token usage, and completion arrive as they happen.

curl -N "http://127.0.0.1:9562/api/v1/events/$SID" ```

On POST /api/v1/chat, message and model are the only required fields; useful optionals are session_id (continue a conversation), system_prompt, selected_skill_ids, workspace_path, provider, images. Note that chat only persists the turn — you must then POST /api/v1/execute/{session_id} to actually run the loop. Besides the per-session GET /api/v1/events/{session_id} feed, there is an account-wide, resumable change feed GET /api/v1/stream (SSE, resumable via ?since=<seq> or the Last-Event-ID header) that streams events across all sessions — handy for multi-session sync.

POST /api/v1/chat and POST /api/v1/execute/{session_id} accept an optional Idempotency-Key header. Bamboo keeps up to 1,024 completed responses in memory for 10 minutes: an equivalent retry replays the first response without duplicating the message or run, while the same key with a different payload returns 409. Keys are scoped independently to chat and execute, and a server restart clears these short-lived receipts. POST /api/v1/sessions has a separate durable recovery contract documented in docs/session-create-idempotency.md.

Example configuration

The easiest way to create this is bamboo init (see First-run setup), which writes it for you and encrypts the key. The equivalent file at ${HOME}/.bamboo/config.json:

{
  "provider": "anthropic",
  "server": {
    "port": 9562,
    "bind": "127.0.0.1"
  },
  "providers": {
    "anthropic": {
      "api_key": "sk-ant-...",
      "model": "claude-sonnet-4-6"
    }
  }
}

Config precedence: file < environment variables < CLI arguments. Environment variables include BAMBOO_DATA_DIR, BAMBOO_PORT, BAMBOO_BIND, BAMBOO_PROVIDER, BAMBOO_WORKERS, BAMBOO_CORS_ALLOW_ORIGINS, and per-provider keys BAMBOO_OPENAI_API_KEY / BAMBOO_ANTHROPIC_API_KEY / BAMBOO_GEMINI_API_KEY (supplied at runtime, never persisted to disk — for Docker/CI/secret-manager deploys without a plaintext key in config.json). This is a minimal example. For every key (multi-provider instances, MCP servers, memory/auto-dream/gardener, sub-agents + the claude_code executor, the IM connect bridge, plugin_trust, notifications, keyword masking, and the full env var list), see docs/config-reference.md.

field (model/provider/skill_mode/reasoning_effort/…) is an optional override.

EXECUTE_KEY=$(uuidgen) curl -s -X POST "http://127.0.0.1:9562/api/v1/execute/$SID" \ -H 'Content-Type: application/json' \ -H "Idempotency-Key: $EXECUTE_KEY" \ -d '{}'

interactive — prompts for provider + API key (uses a default model unless --model is given)

bamboo init

{ "session_id": "...", "stream_url": "/api/v1/events/<id>", "status": "streaming" }

CHAT_KEY=$(uuidgen) SID=$(curl -s http://127.0.0.1:9562/api/v1/chat \ -H 'Content-Type: application/json' \ -H "Idempotency-Key: $CHAT_KEY" \ -d '{"message":"List the files here and tell me what this project does.","model":"claude-sonnet-4-6"}' \ | jq -r .session_id)

Use it as a Rust SDK (in-process)

No server needed — the same agent loop runs in-process. The bamboo_sdk crate is an ergonomic facade over the engine: you supply a model and an instruction, .with_defaults_for_data_dir wires the eight runtime dependencies (storage, persistence, attachment reader, skills, metrics, config, provider, default tools) from ~/.bamboo, and then agent.run(&mut session, input) drives one turn (draining events internally) while agent.run_stream(session, input) streams AgentEvents back over an mpsc channel. To interrupt a streaming run, use run_stream_cancellable(...) which also returns a CancellationToken (call .cancel() to stop the loop); run_with_cancel / run_session_with_cancel accept a caller-owned token for the non-streaming path. Select the provider ergonomically with .provider_name("openai") on the builder (a following .api_key(...) applies to it). Every call funnels into the engine's single canonical execution path — the facade never forks the loop. The ergonomic types live in bamboo_sdk::agent (Agent, AgentBuilder, ExecuteRequestBuilder, CancellationToken, plus re-exported AgentEvent, Session, …).

use bamboo_sdk::agent::{Agent, Session};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let home = dirs::home_dir().unwrap().join(".bamboo");

    // Build the agent. One call assembles storage, persistence, skills,
    // metrics, the provider (from ~/.bamboo/config.json), and the default
    // built-in tool set — no manual dependency wiring.
    let agent = Agent::builder()
        .model("claude-sonnet-4-6")
        .instruction("You are a helpful coding agent.")
        .with_defaults_for_data_dir(home)
        .await
        .expect("wire runtime deps")
        .build()
        .expect("agent fully configured");

    // Stream one turn: `run_stream` appends the user message, runs the loop on
    // a background task, and hands back a receiver of AgentEvents.
    let session = Session::new("demo-session", "claude-sonnet-4-6");
    let mut rx = agent.run_stream(
        session,
        "List the files here and tell me what this project does.",
    );
    while let Some(event) = rx.recv().await {
        println!("{event:?}"); // assistant text, tool calls, tool results, token usage, completion
    }
    Ok(())
}

Precondition: with_defaults_for_data_dir reads ~/.bamboo/config.json (the same config bamboo serve uses) and needs the active provider configured with a non-empty api_key — otherwise provider creation returns an error (here surfaced by .expect). A fresh data dir with no config.json defaults to anthropic with no key and will fail; copilot is the only provider that authenticates keyless (cached OAuth). Fix it with bamboo init (or bamboo config set providers.<p>.api_key …), or pass .api_key("sk-…") on the builder before with_defaults_for_data_dir.

Don't need the event stream? agent.run(&mut session, input).await? drives the turn to completion and leaves the answer as the last message on session. For full control over per-request overrides (split fast/background/summarization models, skill selection, provider handles, …) build an ExecuteRequest with ExecuteRequestBuilder (both re-exported from bamboo_sdk::agent) and call agent.execute(&mut session, req) — the same canonical engine path run / run_stream funnel into.

Approval / clarification + resume. A run can pause mid-loop waiting for input — a conclusion_with_options clarification, or a gated tool call under a configured PermissionChecker — surfaced as AgentEvent::NeedClarification / ToolApprovalRequested. Resolve it with agent.answer(session_id, "Approve").await? (the in-process equivalent of the HTTP POST /sessions/{id}/respond endpoint — same use-case function under the hood, so behavior matches exactly), then continue with agent.resume_stream(outcome.session) / agent.resume(&mut session) — or do both in one call with agent.answer_and_resume_stream(session_id, "Approve").await?. AnswerOutcome also carries any plan-mode transition and the permission grants an approval implied (auto-applied to the builder's .permission_checker(...), if one was configured). When the approved question was a gated tool call, resuming also re-executes that tool for real — against the agent's own tool executor — and writes the genuine output back over the synthetic placeholder before the loop continues, matching the HTTP server's behavior exactly (no extra call needed). > > A separate mechanism, AgentEvent::ChildApprovalRequested, covers an out-of-process CHILD sub-agent's gated tool (only reachable if you've also wired the engine's actor/broker transport — with_defaults_for_data_dir does not). Answer those with agent.answer_child_approval(child_session_id, request_id, approved) instead of agent.answer.

Permission and tool policy. .permission_mode(PermissionMode::Plan | AcceptEdits | DontAsk | Default | BypassPermissions | Auto) installs Bamboo's standard permission stack. Auto emits no approval prompts while retaining explicit policy and platform denials; the typed BypassPermissions mode still honors forced confirmations. .permission_checker(custom) supplies a custom implementation. In contrast, the SDK-specific .bypass_permissions() shortcut explicitly selects its historical no-checker, fully ungated behavior; it is not equivalent to .permission_mode(PermissionMode::BypassPermissions). These three setters are last-call-wins even across with_defaults_for_data_dir(...).await?. Leaving .tools(...) unset exposes the assembled built-in (+ MCP) surface, while .tools([]) or .no_tools() intentionally creates a zero-tool agent; any explicit tool selection has final precedence over assembled or injected default executors. A fully injected .default_tools(...) executor owns its own permission behavior and is not wrapped by the SDK policy setters.

Session ergonomics. agent.new_session(id) creates a session from the explicit builder model or effective provider-config model, while agent.load_session(id), agent.list_sessions() (most-recently-updated first), agent.session_history(id), and agent.delete_session(id) cover the common persistence operations. agent.get_session(id) remains a compatibility alias for load_session. list_sessions needs the concrete session-index handle with_defaults_for_data_dir assembles.

MCP. .mcp_server(config) / .mcp_servers([...]) on the builder connect MCP servers (in with_defaults_for_data_dir) and merge their tools into the built-in tool surface via CompositeToolExecutor — each server's initialize instructions are folded into the tool guidance automatically.

Dependency override order. Explicit .provider(...), .config(...), and .default_tools(...) injections override defaults whether called before or after with_defaults_for_data_dir; an injected provider present before defaults also skips redundant config-driven provider creation. Explicit .tools(...) / .no_tools() remains the final tool-executor policy.

Typed errors. with_defaults_for_data_dir / build / answer / the session-ergonomics methods all return Result<_, SdkError> — a thiserror enum (ProviderInit, UnsupportedApiKeyProvider, ModelNotConfigured, StoreInit, SkillInit, McpServerStart, SessionNotFound, NoPendingQuestion, InvalidResponse, …) instead of a bare String, so callers can match on the failure kind. UnsupportedApiKeyProvider makes .api_key(...) on copilot/unknown providers fail explicitly instead of warning and continuing; ModelNotConfigured prevents new_session from fabricating an empty model. SdkError also wraps AgentError (#[from]) so it composes with run/run_stream's existing typed error in a function returning Result<_, SdkError>.

Add the facade crate as a dependency (path or git):

[dependencies]
bamboo-sdk = { git = "https://github.com/bigduu/Bamboo-agent" }
tokio = { version = "1", features = ["full"] }
dirs = "5"
anyhow = "1"

Prefer not to manage these dependencies yourself? Run bamboo serve and use the server APIs above — they drive the exact same loop. The full SDK type reference is the rustdoc at docs.rs/bamboo-agent (the published crate re-exports the facade as bamboo_agent::agent); docs/guides/API.md covers the HTTP/WebSocket/SSE surface.

Selected API routes

REST prefix /api/v1: chat, execute/{session_id}, stream, sessions, skills, tools, tools/execute, models, commands, workflows, metrics/*, mcp, servers, stop/{session_id}, health. The shared live transport is WebSocket /v2/stream; /api/v1/stream and /api/v1/events/{session_id} remain the legacy SSE feeds. There are also provider-compatible endpoints: /openai/v1, /anthropic/v1, /gemini/v1beta, /v1/{chat/completions,responses,messages}.

Tools, Workflows, Schedules, MCP

• Tools (bamboo-tools, 22 built-in, registered in executor.rs::register_builtin_tools): Bash, BashOutput, KillShell, Read, Write, Edit, NotebookEdit, Glob, Grep, GetFileInfo, Workspace, WebFetch, WebSearch, JsRepl, Task, Sleep, EnterPlanMode, ExitPlanMode, RequestPermissions, SessionNote, ConclusionWithOptions, and more. Tools come with usage guides injected at runtime, a permission/policy-aware execution path, and parallel execution support (parallel.rs).
• Workflows — declarative loading (bamboo-server/src/workflow/loader.rs), exposed via /bamboo/workflows.
• Schedules — a cron-style trigger engine and store (bamboo-server/src/schedules/: manager, trigger_engine, session_factory, store).
• MCP — Model Context Protocol client (crates/infra/bamboo-mcp/: manager, protocol, transports, tool_index), managing external tool servers via the /mcp, /servers routes.

---