A small Rust agent runtime for applications doing non-coding knowledge work.
Pablo gives your application a model-and-tool loop with streaming output, cancellation, policy enforcement and tracing. Run tasks from the CLI, use the interactive terminal, connect an editor through the Agent Client Protocol (ACP), or embed pablo-core in a Rust application. Each interface uses the same runtime; your host owns the sandbox, approvals and application state.
Current version: v0.0.1 is available through the checksum-verifying installer for macOS and Linux on arm64 and x86_64.
Read the public documentation, or start in the repository with the introduction and getting-started guide. If you are adding Pablo to an application, the getting-started guide covers installation first, then helps you choose between an ACP child process and direct Rust embedding. The same Markdown powers both views, so examples remain reviewable in GitHub.
- Embed Pablo through ACP or Rust, or use the CLI and TUI for evaluation and operations.
- Configure deployments, providers and model routes, and tools and policy.
- Add subagents, MCP, Skills and A2A, structured output, and observability.
- Consult installation and release files, the resource benchmark, limits and outcomes, troubleshooting, and version and support.
- Work with files and tools: read, list and search a workspace, opt into revision-checked file writes and edits, and execute shell commands with deadlines and joined cancellation cleanup.
- Connect models: Vercel AI Gateway, OpenRouter and explicitly configured Open Responses endpoints, with named model profiles, ordered fallback, context compaction and optional reasoning controls.
- Extend tasks: configured MCP tools over stdio or Streamable HTTP, explicit local Skills, supervised local children and remote A2A tasks.
- Return usable results: streaming text or a JSON task envelope with outcome and accounting; validate final answers against a supported JSON Schema subset, with configurable single-attempt repair.
- Operate and inspect: composable TOML deployments, static tool and filesystem policy, offline diagnostics, native JSONL traces and OpenTelemetry export.
Pablo keeps each integration boundary explicit: application hosts drive Pablo through ACP or Rust, Pablo connects to tools through MCP, and Pablo delegates selected work to remote agents through A2A.
| Integration | Implemented surface | Guide |
|---|---|---|
| ACP | Stable ACP v1 over stdio for editors and application hosts, with streaming updates, cancellation, independent sessions and negotiated typed outcomes | ACP integration |
| Rust | Embed pablo-core::Runtime, supply host-owned tools, policy, telemetry and cancellation, or use the configured reference host |
Rust embedding |
| Subagents | Up to two concurrent depth-one local children with narrowed capabilities, shared root budgets, typed outcomes, independent cancellation and validated handoffs | Subagents |
| MCP | Client support for configured tool servers over stdio and Streamable HTTP, with qualified tool identity, schema validation, policy and bounded cleanup | MCP tools |
| A2A | Client-side A2A 1.0 JSON-RPC/SSE delegation using exact Agent Cards and endpoints, streamed task/status updates, one Artifact result and bounded cancellation | Remote A2A tasks |
| Agent Skills | Discover portable local SKILL.md packages from configured roots, explicitly activate instructions and read selected resources under host authority |
Portable Agent Skills |
| Model providers | Vercel AI Gateway, OpenRouter and explicitly configured Open Responses endpoints, with named profiles and ordered fallback | Models and providers |
| OpenTelemetry | Native traces and OTLP/HTTP export with W3C Trace Context across runs, models, tools, MCP and remote A2A work | Observability |
Pablo does not currently expose an A2A server or durable agent endpoint. Remote A2A peers remain untrusted client-side dependencies, while the application host retains sandboxing, credentials, policy and business state.
Use the pinned Rust 1.98.1 toolchain and a native build toolchain on macOS or Linux. Node is needed only for the TypeScript client and development tooling.
git clone https://github.com/calebjohn24/pablo.git
cd pablo
cargo build --release --locked -p pablo --bin pablo
./target/release/pablo demoThe offline demo prints Hello from pablo. without a provider credential. Commands below run from the checkout and use the built executable directly.
Install v0.0.1 for native Mac or Linux with one command:
curl -fsSL https://runpablo.pages.dev/install.sh | shThe script pins v0.0.1 and installs to $HOME/.local/bin/pablo; add that directory to PATH if needed. Repeating the command succeeds without changing an identical receipt-backed installation. The installer detects macOS/Linux and arm64/x86_64, downloads the matching archive and checksum from the Cloudflare R2-backed release route, verifies SHA-256 before extraction, and checks the binary’s reported version before installation. It never invokes sudo, package managers, Node or Python. Upgrade an unchanged receipt-backed installation to another exact version with --update; --replace explicitly overwrites another regular file at the selected path.
curl -fsSL https://runpablo.pages.dev/install.sh | sh -s -- --version v0.0.2 --updateRemove it with:
curl -fsSL https://runpablo.pages.dev/install.sh | sh -s -- --removeReview the installer source and archive layout, platform requirements, manifests and signing limits before running it. The archives are unsigned, and the macOS builds are not notarized.
For a real task, supply a gateway credential in your environment or an ignored .env in the directory where you invoke Pablo:
AI_GATEWAY_API_KEY=your-vercel-ai-gateway-keyThen run:
./target/release/pablo run "Read README.md and summarize what Pablo can do." --no-shellThis sends a task to Vercel AI Gateway. The default model is zai/glm-5.3-flash. Filesystem reads remain enabled with --no-shell.
For OpenRouter, supply OPENROUTER_API_KEY instead and select the provider:
./target/release/pablo run "Summarize README.md." --provider openrouter --no-shellOpenRouter defaults to z-ai/glm-5.3-flash. Use --model ID to select another compatible model. Reasoning stays provider-controlled by default; supported models can use --reasoning-effort low or --reasoning-budget-tokens N. See providers and credentials and reasoning controls.
Environment credentials take precedence over .env; --env-file PATH selects a different credential file. VERCEL_AI_GATEWAY is also accepted as a Vercel key alias. --workspace PATH changes the task workspace, independently of credential-file selection. Deployments using --config use explicit credential references instead of automatically reading .env.
# Work in another directory.
./target/release/pablo run "Explain this project." --workspace /path/to/project --no-shell
# Enable revision-checked filesystem writes and edits.
./target/release/pablo run "Write a summary of README.md to SUMMARY.md." --allow-write --no-shell
# Emit one JSON task envelope for a script or host application.
./target/release/pablo run "Summarize README.md." --json --no-shell
# Run a text-only task with explicit time and call limits.
./target/release/pablo run "Explain how a hash table works." \
--no-shell --no-filesystem --timeout 60 --max-model-calls 2
# Open the interactive terminal.
./target/release/pablo tuiThe TUI displays Markdown, tool activity and scrollable history. Page Up/Down or the mouse wheel scroll; Ctrl-End returns to the latest output. Each submitted task has fresh model context, even though earlier output remains visible. Press Ctrl-C to cancel active work and wait for cleanup. See terminal controls.
Shell and filesystem reads are enabled by default. Shell commands run with your user permissions and can modify files independently of --allow-write; the workspace is not an OS sandbox. Use --no-shell for filesystem-only work, add --no-filesystem for text-only work, and configure --policy PATH for tool, launcher and filesystem-root rules. Hosts provide isolation and approvals. See shell execution and filesystem behavior.
Runs default to a one-hour deadline and shell calls to 15 minutes. Model and tool call counts are unlimited unless you set --max-model-calls or --max-tool-calls; zero disables those calls. Payload, context and transport bounds still apply. Hard aggregate token/cost ceilings require attested provider bounds and are currently rejected by the live gateways. Runtime contracts describe limits and accounting.
--json wraps the answer in a task envelope; the output field remains a string. To require a structured answer, add --output-schema /path/to/schema.json. See supported schemas and optional output repair.
TOML deployments compose provider credentials, model routes, tool policy, Skills, MCP servers, child tasks, output settings and telemetry. Inspect them locally before running a task:
./target/release/pablo config validate --config presets/v1/production.toml \
--bind workspace=. --bind preset=./presets/v1
./target/release/pablo config explain --config presets/v1/production.toml \
--bind workspace=. --bind preset=./presets/v1These commands inspect configuration without model calls or service startup. The versioned deployment presets include base, production and development examples. Copy the whole bundle and replace its example MCP/A2A service URLs before execution; the bundled URLs are placeholders. The guide covers credentials, rendering, execution and migration.
| Configure | Reference |
|---|---|
| Composition, profiles and host policy | Deployment configuration |
| Ordered model fallback | Model routes |
| Context compaction | Compaction |
| Open Responses endpoint and capabilities | Provider example |
| MCP tools and explicit local Skills | MCP, Skills |
| Supervised children and validated handoffs | Local children |
| Remote agent delegation | A2A 1.0 client |
An ACP host launches the executable over stdio:
./target/release/pablo acp --stdioThe process supports successive independent sessions, with one prompt per session. Model connections and runtime setup can stay warm. Streaming updates, cancellation and typed task outcomes use the pinned stable ACP v1 protocol with negotiated Pablo extensions. See the ACP integration contract.
To try the included TypeScript client, use the Node version pinned in .nvmrc:
nvm use
npm ci
PABLO_BINARY="$PWD/target/release/pablo" node examples/acp-client.ts \
"Read README.md and summarize it." \
"$PWD"The client uses PABLO_BINARY when set, otherwise it falls back to target/debug/pablo, and it makes a real provider request. Rust applications can call pablo-core::Runtime directly; see the Rust embedding guide, runtime contracts and configured reference host.
./target/release/pablo --help
./target/release/pablo doctordoctor checks local setup and credential presence without model calls or MCP startup. Pass the same provider/configuration options as your task. Explicit --probe provider and --probe mcp opt into a provider request or MCP startup check; see diagnostics.
To record an offline demo trace, choose a new filename:
mkdir -p .pablo/traces
./target/release/pablo demo --trace .pablo/traces/demo.jsonlNative traces record metadata by default and preserve existing files. --capture-content explicitly includes task content in native traces. Network telemetry is off by default; OpenTelemetry configuration covers OTLP/HTTP export, incoming W3C context and privacy behavior.
cargo fmt --all --check
cargo clippy --workspace --all-targets --locked -- -D warnings
cargo test --workspace --locked
npm run typecheck
npm run test:acp
npm run test:telemetry
npm run test:deployment
node scripts/project.mjs checkThese development checks use offline fixtures. Live provider checks are separate, explicit commands documented in the gateway guide. The knowledge-work benchmark covers factual scoring, latency, memory, CPU and cost comparisons; npm run bench:knowledge previews its matrix without model calls.
Release packaging produces deterministic four-target archives with verified layout, checksums, dependency notices, source/build/target manifests and explicit-prefix installation through the R2-backed download route. See the release plan and product design.
For current progress and the next handoff, run node scripts/project.mjs context. Contributors should read AGENTS.md; project decisions and the backlog retain design rationale and deferred work.
Pablo is available under the MIT License. Release archives include this license plus a target-specific third-party dependency inventory and bundled dependency license texts.