English | Chinese

PawnLogic

PawnLogic is a terminal-first autonomous AI agent with multi-provider model routing, persistent memory, real local tool execution, MCP integration, and a CTF-oriented toolchain. The current public release is 0.3.1.

System Requirements

• Linux or WSL2
• Python 3.10+
• pip
• git only for source checkouts, development, or git-backed skill packs
• ~/.local/bin in PATH when using the global pawn launcher
• Optional: Docker for container tools, browser dependencies for Patchright / Scrapling, and CTF packages for pwn workflows

Quick Start

Option A: install from PyPI

pip install pawnlogic
pawn

The first run opens the API key configuration flow. Runtime files are created under ~/.pawnlogic/, not inside the project directory.

Option B: one-line installer

curl -fsSL https://raw.githubusercontent.com/john0123412/PawnLogic/main/install.sh | bash
pawn

The installer creates an isolated venv under ~/.local/share/pawnlogic, installs the official PyPI package, and writes ~/.local/bin/pawn.

Option C: source checkout for development

git clone https://github.com/john0123412/PawnLogic.git
cd PawnLogic
python3 -m venv venv
source venv/bin/activate
pip install -e ".[dev]"
pawn

Optional extras:

pip install "pawnlogic[docker]"    # Docker SDK integration
pip install "pawnlogic[browser]"   # Scrapling + Patchright browser tools
pip install "pawnlogic[ctf]"       # pwntools, ROPgadget, ropper
pip install -e ".[dev,ctf]"        # source checkout with tests and CTF tools

pawnlogic[ctf] installs CTF tooling dependencies only. CTF skill packs are optional extension assets that users install explicitly, for example with /sp install <repo_url> into ~/.pawnlogic/skills. Third-party skill packs are not bundled into PyPI distributions unless their upstream license and notices have been reviewed for redistribution. Skill-pack manifests are runtime discovery metadata only; they do not authorize redistribution without a matching THIRD_PARTY_NOTICES.md entry. Git-backed skill-pack installs accept only https://, ssh://, or git@host:owner/repo.git remotes.

Source-checkout launcher fallback:

./pawn.sh

CLI entry points:

pawn
pawn --debug
pawn --eval "summarize this repository"
pawn --eval "summarize this repository" --json
python -m pawnlogic --help

Default pawn uses user-friendly output and hides raw tool-call internals, parser diagnostics, detailed reasoning streams, and low-level API errors. Use pawn --debug or /mode when you need detailed diagnostics. With --json, each line is an independent NDJSON record. Existing text, chunk, and json records remain stable; versioned Agent lifecycle records use the additive {"type":"event","data":{...}} envelope.

What's New

Version 0.3.1 hardens runtime streaming, file discovery, and tool-execution safety while preserving existing public contracts:

• SSE readers tolerate up to two transient empty readline() results from chunked transports; a third ends the stream to prevent an unbounded polling loop.
• find_files uses a default 10-second monotonic traversal deadline and marks results as partial when the deadline expires.
• Active network probes require a valid Engagement Scope before an authorized private target can be allowed.
• The host executes only complete, owned ToolSpecs through its policy seam; metadata-less handlers fail closed. Public delegated tasks now run through the serial orchestrator with cooperative cancellation and shared budgets.

See CHANGELOG.md for the full release history.

Key Capabilities

Supported Models

PawnLogic ships with preconfigured model aliases. Only active providers with a configured API key are shown in /model and Tab completion.

Custom provider model descriptions come from ~/.pawnlogic/custom_providers.json. Re-running /provider update <name> refreshes selected models and writes English fallback descriptions for fetched models when the provider does not supply a useful description.

Delegated tasks automatically prefer an eligible fast worker when no model request is supplied; they do not automatically reuse the current conversation model. /worker lists every model currently visible through /model, including eligible custom-provider aliases. /agent policy can allow or deny aliases, select the default routing mode, and cap cost or concurrency. Explicit model requests are preferences: provider visibility, user policy, capability, and budget checks remain authoritative. Structured tasks and results carry task/parent IDs, deadlines, usage, and failure records. Shared orchestration budgets are reserved atomically, and cancellation is cooperative. The current core orchestrator is deliberately serial: a persisted max-concurrency value of 2 is a policy ceiling for a future isolated executor, not permission to run the current shared Workspace and RuntimeContext concurrently.

Provider Management

/provider                         # open the provider TUI
/provider add <name> <base_url> <ENV_KEY> [anthropic]
/provider fetch <name>            # fetch available models and select aliases
/provider update <name>           # re-fetch provider models
/provider activate <name>         # show selected provider models
/provider deactivate <name>       # hide provider models
/provider list                    # show provider and key status
/provider test <model>            # test connectivity for a model alias
/setkey                           # run key setup again
/keys                             # show configured key status

API keys are stored in ~/.pawnlogic/.env. Provider configs, model aliases, and descriptions are stored in ~/.pawnlogic/custom_providers.json without secret values. Provider setup does not write keys into shell startup files.

Plain http:// provider endpoints are allowed for local relays and lab setups, but user-friendly mode prints a trust-boundary warning because requests and API keys are not protected by TLS.

Unstable custom providers can be tuned through environment variables in ~/.pawnlogic/.env: PAWNLOGIC_API_RETRY_MAX controls total request attempts including the first attempt, PAWNLOGIC_API_RETRY_AFTER_MAX caps provider Retry-After delays, and PAWNLOGIC_API_CONNECT_TIMEOUT, PAWNLOGIC_API_READ_TIMEOUT, and PAWNLOGIC_API_NONSTREAM_TIMEOUT tune connection and response wait times.

Quick Command Reference

/model [alias]                    # switch model
/mode                             # toggle user-friendly/debug output
/chat find <keyword>              # search all sessions
/think <prompt>                   # run one deeper reasoning turn
/compact                          # summarize and compact context
/undo [n]                         # roll back recent turns
/deep                             # full-power mode
/init_project [desc]              # initialize project state
/pwnenv                           # check CTF toolchain integrity
/ctf init <name>                  # start CTF workspace metadata
/ctf solved [flag]                # mark a confirmed CTF flag as solved
/ctf writeup                      # export a CTF writeup draft
/sp install <repo_url>            # install a git-backed skill pack
/sp enable <name>                 # enable a skill pack
/sp disable <name>                # disable a skill pack
/sp status                        # show enabled/disabled status
/skills manage                    # interactive TUI for skill pack toggle
/extension list                   # list installed Extensions
/extension enable <name>          # explicitly enable an Extension
/extension disable <name>         # disable an Extension
/worker [alias|auto]              # inspect or set the preferred worker
/agent policy show                # inspect delegated-agent policy
/agent run <role> <objective>     # print a safe delegate_task request template

Run /help inside PawnLogic for the full command list.

Trust Boundary

PawnLogic is an agent execution tool, not a security sandbox. It intentionally executes real tools with the current user's permissions when you ask it to do so. Pattern filters, Docker boundaries, and capability profiles reduce accidents; they do not contain a determined attacker.

Web fetches and browser navigation evaluate HTTP(S) targets through the shared Network Policy before use. URLs are normalized; embedded credentials, cloud-metadata/internal targets, and loopback, link-local, multicast, unspecified, or reserved addresses are denied. Private-network targets require explicit authorization, and non-interactive requests fail closed when confirmation would otherwise be required. Redirect destinations are normalized, resolved, and evaluated again before they are followed, including any target-scoped authorization. Model-generated Tool arguments cannot grant private-network authorization, and confirmed private targets bypass remote reader services.

Docker bridge/host networking and legacy uvx mcp-server-fetch startup use capability-only authorization because no concrete URL is available at the gate. Authorize Docker networking with allow_network=true or PAWNLOGIC_DOCKER_ALLOW_NETWORK=true; authorize the legacy MCP network install with allow_network_install=true or PAWNLOGIC_MCP_ALLOW_NETWORK_INSTALL=true. These approvals grant only the named capability; they are not URL-target approvals.

User-friendly mode prints explicit trust-boundary notices for host shell execution, Docker container exec, browser/network-capable tools, private network URL access, delegated sub-agents, and plaintext HTTP providers. Use pawn --debug when you need lower-level tool arguments and diagnostics. Docker file mounts are workspace-bound by default, including read-only mounts; outside read-only challenge files require explicit allow_host_read_mount.

Host shell execution now passes through an operation policy before subprocess startup. Low-risk commands run normally, medium-risk commands are classified for audit, high-risk commands require explicit interactive confirmation, and critical operations are denied by default. Non-interactive execution, including pawn --eval, fails closed when a high-risk command would require confirmation. DANGEROUS_PATTERNS remains only one misuse/risk classifier; it is not a sandbox boundary and cannot stop a malicious local user.

Optional Extensions

Python distributions may advertise Extension metadata through the pawnlogic.extensions entry-point group. PawnLogic can list installed Extensions without loading their code. Installation never enables an Extension automatically.

/extension list
/extension status [name]
/extension enable <name>
/extension disable <name>

Enabled names are stored under ~/.pawnlogic/extensions/enabled.json. Extension startup failures are isolated from core startup, and contribution name conflicts are rejected instead of overwriting built-in Tools or commands. Dependency-heavy or security-sensitive Extensions must remain independently packaged and published. The core wheel contains no pawnlogic_security package, security console script, or security dependency; installing such a distribution would still require explicit /extension enable <name> authorization.

MCP Tool Integration

For pip or one-line installer users, PawnLogic creates editable templates in ~/.pawnlogic/ on startup:

pawn
cp ~/.pawnlogic/mcp_configs.example.json ~/.pawnlogic/mcp_configs.json
# edit ~/.pawnlogic/mcp_configs.json and add keys with /setkey or ~/.pawnlogic/.env
pawn

For source checkout users, the repository template can also be copied directly:

cp mcp_configs.example.json ~/.pawnlogic/mcp_configs.json

Supported example MCP servers include Tavily search, Playwright browser automation, and a filesystem bridge. External fetch MCP is disabled in the example because uvx mcp-server-fetch may contact PyPI during startup; use PawnLogic's built-in fetch_url unless you explicitly enable that MCP server.

MCP subprocess stderr is written to ~/.pawnlogic/logs/mcp/<server>.stderr.log by default. Set top-level "debug_stderr": true in mcp_configs.json when you want raw MCP stderr on the console. PawnLogic advertises MCP roots for the current working directory and ~/.pawnlogic/workspace.

Data Layout

All runtime data and API keys are stored in ~/.pawnlogic/.

~/.pawnlogic/
├── .env                    # API keys
├── custom_providers.json   # user provider configs, no keys
├── mcp_configs.json        # MCP server declarations
├── pawn.db                 # sessions, messages, knowledge base
├── global_skills.md        # GSA skill archive
├── skills/                 # optional user-installed skill packs
├── workspace/              # per-session working directories
└── logs/                   # audit logs

The project directory contains no secrets and is safe to commit or share.

Documentation

Support

• GitHub: github.com/john0123412/PawnLogic
• Issues: use GitHub Issues for bugs and feature requests.