English · 简体中文

pawbot

A self-hosted AI agent for your browser, terminal, and chat apps.

Choose your interface: run pawbot for the WebUI, or run pawbot agent for the native terminal UI (TUI).

Give pawbot a task and it can read and write files, run commands, search the web, call MCP tools, remember conversations, and run scheduled work. Use the WebUI when you want a visual workspace, the terminal when you want speed, or a chat app when you want your agent to be available wherever you are.

The feature that makes pawbot different is Record & Replay: record one real agent turn, then replay it offline while you change the code — without another model request, another token bill, or real tool side effects.

Start here

What can pawbot do?

• Work with files, shell commands, web search, web fetching, documents, images, and other tools.
• Connect to MCP servers and load extensions without changing the core agent.
• Keep session history and long-term memory across conversations.
• Run long tasks and scheduled automations.
• Use Anthropic, OpenAI-compatible endpoints, local models, fallbacks, and model presets.
• Reach the same agent from the WebUI, CLI/TUI, API, or supported chat channels.
• Expose a Python SDK and an OpenAI-compatible API for your own applications.

How a turn works

Every entry point reaches the same turn pipeline. The important boundary is between the orchestration loop and the provider/tool rails: the former can be budgeted, cancelled, checkpointed, and replayed without making the provider or real tools part of a regression test.

flowchart LR
    A[WebUI / CLI / API / chat channels] --> B[Gateway / Message Bus]
    B --> C[AgentLoop turn pipeline]
    C --> C1[Restore session]
    C1 --> C2[Compact context]
    C2 --> C3[Dispatch command]
    C3 --> C4[Build provider request]
    C4 --> D[AgentRunner ReAct loop]
    D --> E[Provider response]
    D --> F[Tool Registry]
    F --> G[Batch planner]
    G --> H[Call executor]
    H --> I[Tool observation]
    D --> J[Budget + checkpoint]
    J --> K[Session recovery]
    E --> L[LLM response rail]
    I --> M[Tool observation rail]
    L --> N[Record & Replay]
    M --> N
    N --> O[Offline replay + structural diff]
    D --> P[Turn delivery / UI events]

The result is one execution unit with explicit resource limits, recovery checkpoints, tool side-effect boundaries, and an offline evidence trail.

Why pawbot?

One agent, several ways to use it

The WebUI, terminal, API, and chat channels share the same conversations, tools, and configuration. Start in the browser and continue from the terminal; or keep the agent running behind a gateway and talk to it from a chat app.

Record an agent once, replay it as often as you need

LLM calls and external tools make agent bugs expensive and difficult to repeat. Pawbot records the model responses and tool observations of a turn. Replay then runs the current agent code against those recorded inputs:

• no new provider request;
• no new token cost;
• no network dependency;
• no real tool side effects;
• a structural diff when orchestration changes.

This is useful for debugging, regression tests, and safe refactoring of the agent loop.

Keep your data on your machine

Pawbot is designed for self-hosting. Sessions, configuration, workspaces, and recordings stay under your control. Shell commands, file access, network tools, and MCP servers are explicit capabilities with documented security boundaries.

Quick install

Published package

After the package is published, install and open the WebUI with one command:

macOS / Linux:

uv tool install --force --upgrade pawbot-ai && pawbot

After installation, update any existing Pawbot installation without repeating provider setup:

pawbot update

The update command upgrades the package through its detected installation manager and leaves provider credentials, channel settings, sessions, and the workspace untouched.

Windows PowerShell:

uv tool install --force --upgrade pawbot-ai; pawbot

The repository also includes isolated fallback installers. On a fresh desktop install they start the WebUI automatically; use pawbot agent when you want the terminal/TUI client explicitly:

• scripts/install.sh
• scripts/install.ps1

For a fresh macOS or Linux desktop, the installer can be run directly from GitHub:

curl -fsSL https://raw.githubusercontent.com/m2dumpling/pawbot/v0.4.0/scripts/install.sh | sh

If curl is not available, use wget instead:

wget -qO- https://raw.githubusercontent.com/m2dumpling/pawbot/v0.4.0/scripts/install.sh | sh

For native Windows PowerShell:

iex (irm https://raw.githubusercontent.com/m2dumpling/pawbot/v0.4.0/scripts/install.ps1)

The installer selects an active virtual environment, uv, pipx, or a dedicated ~/.pawbot/venv fallback, then opens the WebUI on a fresh desktop. Before creating the fallback environment it verifies that Python's venv and ensurepip support is available. If a minimal Debian/Ubuntu image is missing python3.x-venv, installation stops with the exact package command to run and does not print a misleading startup command. On success it runs pawbot --version; if the launcher is not on the current shell's PATH, it prints the verified launcher path and the command to use now. Configure the first Provider in Settings → Models before sending your first task. Quick Start and the WebUI probe a compatible provider's /models endpoint after credentials are entered, then enrich returned models with pawbot's capability table (context window and reasoning levels). If an endpoint does not publish a model list, the UI keeps manual model entry available.

From a source checkout

Requirements: Python 3.11+ and uv. Released packages download a checksum-verified native TUI for the current platform on the first pawbot agent launch; Bun is only needed when developing from a source checkout.

uv sync --all-extras --dev
uv run pawbot --help

Install optional channel dependencies when needed:

uv run --no-sync python -m scripts.install_channel_dependencies --all-channels

Quick start

WebUI

The browser workspace is the easiest first run:

uv run pawbot webui

Configure your first provider in Settings → Models; the model picker loads available models after credentials are saved. Start a new conversation and send Hello!. The first-run WebUI binds to localhost by default.

On a Linux server, localhost is intentionally private to the server. Bind the WebUI explicitly when you need to open it from another machine:

pawbot webui --remote --yes --no-open

Then open http://<server-ip>:8765 from your own computer and enter the channels.websocket.tokenIssueSecret value from the server's config file. Keep the gateway health port (18790 by default) private, allow only the WebUI port through the firewall, and use HTTPS/reverse proxy before exposing it to the public Internet. For a private setup, use an SSH tunnel instead:

ssh -N -L 8765:127.0.0.1:8765 <user>@<server>

Then open http://127.0.0.1:8765 on your own computer.

CLI

pawbot opens the WebUI. pawbot agent opens the native terminal UI (TUI). On a headless Linux server, pawbot keeps the WebUI on localhost and prints a ready-to-copy SSH tunnel command; use pawbot webui --remote --yes --no-open when you deliberately want to access it from another machine.

Run one request and exit:

uv run pawbot agent --message "Explain the top-level modules in this repository"

Start the gateway directly when you want a long-running process:

uv run pawbot gateway

Keep the gateway in the background:

uv run pawbot gateway --background
uv run pawbot gateway status
uv run pawbot gateway logs

Record & Replay

Pawbot separates three jobs that are easy to confuse:

• Live execution records are created automatically for every turn. They show stages, timing, status, and failures without copying full prompts or tool results.
• Regression samples are saved manually when you want to keep one complete run. They include the request, model responses, tool calls, and tool results across every session until capture is stopped.
• Offline validation re-runs the current orchestration against a saved sample. It does not call the provider or execute real tools, and reports whether the recorded path still matches.

Save a real turn as a regression sample:

uv run pawbot agent \
  --message "Inspect the repository and summarize the agent loop" \
  --record .pawbot/blackbox/demo

Replay it offline:

uv run pawbot agent --replay .pawbot/blackbox/demo

The concise equivalent is:

uv run pawbot replay .pawbot/blackbox/demo

Add --benchmark to print provider-free local replay timing and message/diff counts.

In the WebUI, Settings → Execution & regression provides the same workflow: use Save as regression sample, run tasks across as many chat sessions as needed, then click Stop saving. The capture window belongs to the agent, so all turns before Stop are stored in one sample. Incomplete samples stay visible with a reason and can be deleted from the UI instead of failing later.

For a running gateway, the same controls are available from the CLI:

uv run pawbot record start --name demo
uv run pawbot record status
uv run pawbot record stop
uv run pawbot record list
uv run pawbot trace list --filter errors
uv run pawbot trace show <trace-id>

After offline validation, expand a turn to see a readable execution trace: the user's request, model thinking when the provider returned it, model decisions, tool calls, tool-result previews, and the final answer in event order. Long values can be expanded in place. View raw record opens the complete JSON/JSONL turn data in a full-screen inspector; the green result only means that no observable difference was found under the recorded inputs and observations.

Pause after an iteration and inspect the reconstructed messages:

uv run pawbot agent \
  --replay .pawbot/blackbox/demo \
  --break-at 2

The recording contains the provider-response rail, the tool-observation rail, and the turn envelope. Replay checks tool ordering, result insertion, context governance, continuation, and the final message structure. See docs/record-replay.md for the format and privacy boundary.

Agent Harness Benchmark

Record & Replay checks one saved execution. The Agent Harness checks a stable catalog of success and failure scenarios against the real AgentRunner without calling a provider or touching the workspace. It covers normal tool use, tool failure and recovery, provider errors, LLM timeouts, user cancellation, and turn-budget boundaries, and human approval before a write-capable Tool runs.

Run it after an AI-assisted change:

uv run --no-sync pawbot harness run

The same behavioral check is part of the local quality gate:

uv run --no-sync python scripts/quality_gate.py

The Harness separates trajectory checks from simple task contracts such as final content and required successful tools. Domain-specific evaluators are a separate next step; a green replay or Harness result is not a general model-quality score. See the Agent Harness Benchmark guide.

When a WebUI chat uses Workspace access, write, execute, and network-capable Tools pause for an explicit approval. Full access remains the opt-in mode that runs those Tools directly. The same approval protocol is available to the native TUI.

When choosing a model in Settings → Models, pawbot also reads capability metadata from the provider's /models response when available. For known model IDs, the curated capability registry wins over stale or generic provider values; unknown models use provider metadata and remain manually editable. Context length and supported reasoning levels are shown before saving. See the curated model capability registry for the fallback table and context-window migration rules.

Inside the TUI, /model lists the current provider's discovered models and their known context/reasoning metadata. /model <model-id> pins a discovered or manually entered model to the current session; /model default returns to the configured default. The global configuration is not changed by a session pin.

Channels and integrations

Pawbot can be used from its WebUI, terminal, OpenAI-compatible API, Python SDK, WebSocket channel, and supported chat channels. MCP servers and extension points let you add capabilities without hard-coding them into the agent loop.

Architecture

User message
    ↓
Channel / WebUI / CLI / API
    ↓
AgentLoop: prepare the conversation and run one turn
    ↓
AgentRunner: ask the model, call tools, add results, repeat when needed
    ↓
Provider + ToolRegistry + MCP
    ↓
Answer, saved session, and channel response

The core source is organized around:

• pawbot/agent/loop.py — turn orchestration;
• pawbot/agent/runner.py — the model/tool loop;
• pawbot/agent/turn/ — turn state and stages;
• pawbot/agent/blackbox/ — Record & Replay;
• pawbot/agent/tools/ — tool contracts and execution;
• pawbot/session/ — conversations, memory, and recovery;
• pawbot/providers/ — model adapters and retries.

Documentation

• Documentation index
• Record & Replay
• Agent Harness Benchmark
• Release notes
• Publishing guide
• Changelog
• Contributing
• Security policy

Security and privacy

Pawbot can run shell commands, access local files, call network tools, and connect to MCP servers. Read SECURITY.md before enabling them.

Never commit:

• config.json, .env*, provider credentials, or certificates;
• .pawbot/ recordings and session data;
• work/, sessions/, run/, SQLite files, or private logs;
• prompts, tool results, or local paths containing personal information.

Replay artifacts can contain sensitive prompts and tool output. Sanitize them before sharing; use tests/fixtures/blackbox/ for repository-safe examples.

Development

uv sync --all-extras --dev
uv run --no-sync python -m scripts.install_channel_dependencies --all-channels
uv run ruff check pawbot
uv run basedpyright
uv run pytest -q
uv run --no-sync python scripts/quality_gate.py

For WebUI changes:

cd webui
bun install --frozen-lockfile
bun run test
bun run build

Project status

Pawbot is an Alpha/Experimental Preview project. It is ready for personal self-hosting, development, testing, and small single-node deployments. It does not currently promise multi-instance session consistency, durable distributed execution, automatic failover, or enterprise high availability.

License

MIT — see LICENSE and THIRD_PARTY_NOTICES.md.