Anda Bot User Guide

July 5, 2026 · View on GitHub

Project README | 简体中文

Born of panda. Awakened as Anda.

This page is the practical guide for the anda binary. If you are deciding whether to use Anda Bot, start with the project README. If you are ready to run me, configure me, or connect me to your daily tools, you are in the right place.

Start Me

From the repository root:

cargo run -p anda_bot --

This opens the terminal chat UI and starts or reconnects to the local daemon. On first launch I create ~/.anda/config.yaml and the runtime directories I need.

If setup is incomplete, the UI will list the missing config fields. Edit ~/.anda/config.yaml, save it, then press Enter in the UI. Once chat is available, /reload also reloads the config.

Use a different home directory for a separate identity, profile, or test environment:

cargo run -p anda_bot -- --home /path/to/.anda

Local Launcher Development

For local launcher testing on macOS, build both binaries, install them side by side, copy the bundled skills, and register the menu bar launcher as a user LaunchAgent:

cargo build -p anda_bot --release --locked --bin anda --bin anda_launcher

mkdir -p "$HOME/.local/bin" "$HOME/.anda/skills"
install -m 755 target/release/anda "$HOME/.local/bin/anda"
install -m 755 target/release/anda_launcher "$HOME/.local/bin/anda_launcher"
cp -R skills/. "$HOME/.anda/skills/"

mkdir -p "$HOME/Library/LaunchAgents"
cat > "$HOME/Library/LaunchAgents/ai.anda.anda-bot.launcher.plist" <<EOF
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key>
  <string>ai.anda.anda-bot.launcher</string>
  <key>ProgramArguments</key>
  <array>
    <string>$HOME/.local/bin/anda_launcher</string>
  </array>
  <key>RunAtLoad</key>
  <true/>
</dict>
</plist>
EOF

launchctl bootout "gui/$(id -u)" "$HOME/Library/LaunchAgents/ai.anda.anda-bot.launcher.plist" 2>/dev/null || true
launchctl bootstrap "gui/$(id -u)" "$HOME/Library/LaunchAgents/ai.anda.anda-bot.launcher.plist"
launchctl kickstart -k "gui/$(id -u)/ai.anda.anda-bot.launcher"

Verify the installed launcher and daemon state with:

launchctl print "gui/$(id -u)/ai.anda.anda-bot.launcher"
"$HOME/.local/bin/anda" --home "$HOME/.anda" status

For a throwaway development profile, run the debug launcher directly. The launcher first looks for anda next to itself, so build both binaries before starting it:

cargo build -p anda_bot --bin anda --bin anda_launcher
ANDA_HOME="$PWD/.dev/anda-home" target/debug/anda_launcher

To build a Windows installer locally, run the packaging step on Windows because it depends on iexpress.exe:

cargo build --release --locked --target x86_64-pc-windows-msvc --bin anda --bin anda_launcher

New-Item -ItemType Directory -Force release | Out-Null
Copy-Item target\x86_64-pc-windows-msvc\release\anda.exe release\anda-windows-x86_64.exe -Force
Copy-Item target\x86_64-pc-windows-msvc\release\anda_launcher.exe release\anda_launcher-windows-x86_64.exe -Force

if (Test-Path release\anda-skills.zip) { Remove-Item release\anda-skills.zip -Force }
Compress-Archive -Path skills\* -DestinationPath release\anda-skills.zip -Force

pwsh -NoProfile -ExecutionPolicy Bypass -File scripts\build-windows-installer.ps1 -ReleaseDir release
.\release\AndaBotSetup-windows-x86_64.exe

Windows Authenticode signing is optional. When Microsoft Artifact Signing is configured, the GitHub workflow signs Windows binaries and the generated installer before checksums are generated. When it is not configured, the workflow still publishes unsigned Windows artifacts. To enable signing, create an Azure Artifact Signing account, complete identity validation, create a certificate profile, grant the app registration's service principal the Certificate Profile Signer role, and add a federated credential for this repository. Configure these GitHub secrets:

  • AZURE_CLIENT_ID: app registration client ID.
  • AZURE_TENANT_ID: Microsoft Entra tenant ID.
  • AZURE_SUBSCRIPTION_ID: Azure subscription ID.

Configure these GitHub repository variables:

  • AZURE_ARTIFACT_SIGNING_ENDPOINT: signing account endpoint, such as https://eus.codesigning.azure.net/.
  • AZURE_ARTIFACT_SIGNING_ACCOUNT_NAME: Artifact Signing account name.
  • AZURE_ARTIFACT_SIGNING_CERTIFICATE_PROFILE_NAME: certificate profile name.

SmartScreen reputation is tied to both the file hash and the signing identity; keep the publisher identity stable across releases so reputation can accumulate. Unsigned Windows artifacts may still show the SmartScreen unrecognized-app warning.

The release install script downloads published artifacts. For local launcher debugging, use the manual install flow above or the generated Windows installer.

Configure A Model

The generated template is assets/config.yaml. The active provider must include family, model, and api_base. Set api_key in the file, or leave it empty and export a matching environment variable before starting Anda.

model:
  active: "deepseek-v4-pro"
  providers:
    - family: anthropic
      model: "deepseek-v4-pro"
      api_base: "https://api.deepseek.com/anthropic"
      api_key: "YOUR_API_KEY" # optional when DEEPSEEK_API_KEY is set
      labels: ["pro", "brain"]
      disabled: false

Supported model key environment variables include OPENAI_API_KEY, ANTHROPIC_API_KEY, GEMINI_API_KEY, GOOGLE_API_KEY, DEEPSEEK_API_KEY, MINIMAX_API_KEY, MIMO_API_KEY, MOONSHOT_API_KEY, KIMI_API_KEY, BIGMODEL_API_KEY, and GLM_API_KEY. A value in config.yaml takes precedence over the environment.

Provider labels help me choose models for different jobs. A provider labeled brain is preferred for memory formation and recall support. If no provider has that label, I use the active model.

Useful top-level settings:

SettingWhat it does
addrLocal gateway address, default 127.0.0.1:8042.
sandboxRoutes shell execution through ~/.anda/sandbox when true.
https_proxyOptional proxy for outbound model and channel requests.
modelModel providers used by the agent and memory brain.
transcriptionSpeech-to-text providers for voice input and audio attachments.
ttsText-to-speech providers for spoken playback.
channelsOptional chat integrations.

Chat UI Controls

  • Enter sends the message.
  • Shift+Enter inserts a newline; use Ctrl+J in terminals that do not report Shift+Enter.
  • Up and Down move through multi-line input.
  • Ctrl+U clears the input.
  • Ctrl+A and Ctrl+E move to the start and end of the input.
  • /reload reloads config.yaml and reconnects.
  • /stop stops the current task and leaves the conversation idle.
  • /cancel exits the active conversation task.
  • /steer ... gives an in-progress response extra guidance.
  • Esc shows status.
  • Ctrl+C quits.

When a response succeeds, conversation turns are sent to Anda Brain for memory formation. I keep conversation state locally, so later prompts in the same workspace can continue with the right context.

Teach My Memory

Brain works best when important facts are stated clearly. You can speak naturally:

Remember that this project uses release branches, not trunk-based releases.
When I say staging, I mean the shared QA environment.
My preference changed: use concise answers by default, but include exact commands for deployment issues.
What do you remember about the last incident review?

The memory brain stores more than text snippets. It can form entities, relationships, events, preferences, and timelines, then recall them through the recall_memory tool when they are useful.

CLI Commands

CommandUse it when
cargo run -p anda_bot --You want the interactive terminal UI.
cargo run -p anda_bot -- updateYou want to update an install-script release.
cargo run -p anda_bot -- daemonYou want the daemon in the foreground.
cargo run -p anda_bot -- stopYou want to stop a background daemon on Unix.
cargo run -p anda_bot -- restartYou changed config or want a fresh daemon on Unix.
cargo run -p anda_bot -- agent run --prompt "..."You want a single prompt without opening the UI.
cargo run -p anda_bot -- user create aliceYou want to create a trusted channel/user key.
cargo run -p anda_bot -- voice --record-secs 8You want microphone input and optional spoken output.

Voice mode requires transcription.enabled: true. Playback requires tts.enabled: true; add --no-playback to keep voice input but print text output only.

Connect Chat Channels

Configure channels under channels in ~/.anda/config.yaml.

Supported channel families:

  • Telegram
  • WeChat
  • Discord
  • Lark / Feishu

To bind a channel to a trusted non-owner user, create a key first:

cargo run -p anda_bot -- user create alice

Minimal examples:

channels:
  telegram:
    - id: personal
      user: alice
      bot_token: "YOUR_TELEGRAM_BOT_TOKEN"
      username: anda_bot
      allowed_users:
        - "*"
      mention_only: false

  wechat:
    - id: personal
      username: anda-wechat
      allowed_users:
        - "*"

  lark:
    - id: work
      app_id: "cli_xxx"
      app_secret: "YOUR_APP_SECRET"
      platform: feishu
      receive_mode: websocket
      mention_only: true

Channel notes:

  • allowed_users restricts who can trigger me. Use "*" only when that is acceptable.
  • user chooses which trusted Anda caller owns the channel conversations, resources, and memory.
  • allow_external_users: true lets non-allowlisted IM senders talk to me as $external_user; they are treated as untrusted and are not the owner/partner.
  • Telegram and Discord require bot_token.
  • WeChat can use a saved token or QR login when bot_token is empty.
  • Lark and Feishu require app_id and app_secret; use platform: feishu for Feishu endpoints.
  • Audio attachments can be transcribed when transcription is enabled.
  • Channel routes are persisted, so replies continue in the original thread, room, or recipient when possible.

Local Files, Skills, And Cron

My file and shell tools use ~/.anda/workspace as the default working area. This keeps local agent work separate from the repository checkout and your home directory.

Runtime skills live in ~/.anda/skills. Put skill folders or skill documents there when you want me to learn specialized workflows.

Cron tools let me create, list, manage, and inspect scheduled jobs. A job can run a shell command or submit a future prompt back to the agent. Run history is persisted locally.

Shell Command Execution and Security

My shell tool executes commands natively and unsandboxed, with the full privileges of the user running the daemon. There is no container, chroot, or seccomp isolation; the ~/.anda/workspace default directory is a convention, not a boundary.

What stands between a prompt and a running command is the approval flow:

  1. Static policy. A built-in policy allows clearly safe commands and flags risky ones.
  2. Risk model. In the default on_risk mode, commands the static policy cannot clear are classified by the configured LLM; if the model is unavailable, the static policy's conservative answer is used.
  3. Human approval. Commands judged risky produce an approval action that you must confirm (in the chat UI, launcher, or browser extension) before they run. In request_approval mode every command asks; in full_access mode nothing asks.

Implications you should be aware of:

  • Content from connected channels (group chats, external users) reaches the same agent. External participants are tagged and scoped, but prompt injection is a real attack surface — prefer on_risk or request_approval mode when channels are open to people you do not fully trust, and never use full_access on such setups.
  • Because the risk gate is partly model-based, do not treat it as a hard security boundary. The hard boundary is your approval click and the OS user account the daemon runs as.
  • Run the daemon as a dedicated, least-privilege user if you want stronger containment.

Home Directory Layout

~/.anda/
  config.yaml
  anda-daemon.pid
  channels/
  db/
  keys/ # legacy or explicit file keys
  logs/
  sandbox/
  skills/
  workspace/

What lives there:

  • config.yaml controls models, proxy, channels, voice, and sandboxing.
  • db/ stores memory, conversations, channels, cron jobs, and object state.
  • keys/ stores legacy or explicitly exported signing-key files. New identity private keys live in the OS secure credential store by default.
  • logs/ stores daemon and CLI logs.
  • channels/ stores channel-specific runtime state.
  • sandbox/ is used for shell isolation when enabled.
  • skills/ is loaded by the skill manager.
  • workspace/ is the default file and shell workspace.

Troubleshooting

  • The UI stays in setup mode: fill every field it lists in ~/.anda/config.yaml, save, then press Enter.
  • The daemon is unreachable: run cargo run -p anda_bot -- restart on Unix, or start cargo run -p anda_bot -- daemon in a separate terminal.
  • Voice mode fails: enable and configure transcription; also enable tts unless you pass --no-playback.
  • A channel ignores messages: check allowed_users, mention_only, and the channel credentials.
  • A command touches the wrong files: check ~/.anda/workspace; that is my default working area.

License

Copyright © LDC Labs

Licensed under Apache-2.0. See the repository-level LICENSE.