Metadata-Version: 2.4
Name: polyrob
Version: 1.7.4
Summary: POLYROB — autonomous AI agent framework
Author: The POLYROB Authors
License-Expression: MIT
Project-URL: Homepage, https://github.com/theselfruleorg/polyrob
Project-URL: Repository, https://github.com/theselfruleorg/polyrob
Project-URL: Issues, https://github.com/theselfruleorg/polyrob/issues
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pydantic-settings>=2.0.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: openai>=1.26.0
Requires-Dist: tiktoken>=0.7.0
Requires-Dist: aiohttp>=3.14.4
Requires-Dist: aiofiles>=23.0.0
Requires-Dist: aiosqlite>=0.19.0
Requires-Dist: requests>=2.30.0
Requires-Dist: certifi>=2026.10.19
Requires-Dist: cryptography>=50.0.0
Requires-Dist: pyjwt>=2.15.1
Requires-Dist: rich>=13.0.0
Requires-Dist: prompt_toolkit>=3.0.43
Requires-Dist: click>=8.0
Requires-Dist: colorama>=0.4.6
Requires-Dist: markdown>=3.5.0
Requires-Dist: markdownify>=0.11.0
Requires-Dist: pillow>=13.0.0
Requires-Dist: httplib2>=0.32.0
Requires-Dist: pyasn1>=0.6.5
Requires-Dist: multidict>=6.9.1
Requires-Dist: pyyaml>=6
Requires-Dist: packaging>=23.2
Requires-Dist: h2>=4.4.1
Requires-Dist: httpx>=0.27
Requires-Dist: beautifulsoup4>=4.12
Requires-Dist: yarl>=1.9
Provides-Extra: gemini
Requires-Dist: google-generativeai>=0.8.0; extra == "gemini"
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.20.0; extra == "anthropic"
Provides-Extra: server
Requires-Dist: fastapi==0.141.1; extra == "server"
Requires-Dist: starlette==1.6.0; extra == "server"
Requires-Dist: uvicorn[standard]==0.38.0; extra == "server"
Requires-Dist: Jinja2==3.1.6; extra == "server"
Requires-Dist: python-socketio>=5.11.0; extra == "server"
Requires-Dist: python-multipart>=0.0.6; extra == "server"
Requires-Dist: watchfiles>=1.0.0; extra == "server"
Requires-Dist: argon2-cffi>=23.1.0; extra == "server"
Requires-Dist: python-magic>=0.4.27; extra == "server"
Provides-Extra: docs
Requires-Dist: pypdf>=6.21.4; extra == "docs"
Requires-Dist: python-docx>=0.8.0; extra == "docs"
Provides-Extra: anysite
Requires-Dist: anysite-cli>=0.3; extra == "anysite"
Provides-Extra: browser
Requires-Dist: playwright>=1.64.1; extra == "browser"
Requires-Dist: psutil>=5.9.0; extra == "browser"
Provides-Extra: memory-vector
Requires-Dist: sentence-transformers>=3.0.0; extra == "memory-vector"
Requires-Dist: apsw>=3.46; extra == "memory-vector"
Requires-Dist: sqlite-vec>=0.1.6; extra == "memory-vector"
Requires-Dist: numpy>=1.24.0; extra == "memory-vector"
Provides-Extra: media
Requires-Dist: numpy>=1.24.0; extra == "media"
Requires-Dist: imageio>=2.37.0; extra == "media"
Requires-Dist: qrcode>=7.4; extra == "media"
Provides-Extra: crypto
Requires-Dist: web3>=6.0.0; extra == "crypto"
Requires-Dist: eth-account>=0.10.0; extra == "crypto"
Requires-Dist: eth-utils>=2.0; extra == "crypto"
Requires-Dist: eth-abi>=4.0; extra == "crypto"
Requires-Dist: x402>=2.13.0; extra == "crypto"
Requires-Dist: fastapi-x402>=0.1.8; extra == "crypto"
Requires-Dist: hyperliquid-python-sdk>=0.21.0; extra == "crypto"
Requires-Dist: py-clob-client-v2>=0.1.0; extra == "crypto"
Provides-Extra: solana
Requires-Dist: solders>=0.21; extra == "solana"
Requires-Dist: x402[svm]>=2.16.0; extra == "solana"
Requires-Dist: solana<0.40,>=0.36; extra == "solana"
Requires-Dist: httpx2>=2.12.0; extra == "solana"
Requires-Dist: httpcore2>=2.10.0; extra == "solana"
Provides-Extra: telegram
Requires-Dist: aiogram>=3.17.0; extra == "telegram"
Provides-Extra: twitter
Requires-Dist: requests-oauthlib<3,>=2.0.0; extra == "twitter"
Requires-Dist: oauthlib>=4.0.1; extra == "twitter"
Requires-Dist: urllib3>=2.0; extra == "twitter"
Requires-Dist: chatxdk>=0.5.0; extra == "twitter"
Provides-Extra: voice
Requires-Dist: faster-whisper>=1.0.0; extra == "voice"
Provides-Extra: feishu
Requires-Dist: lark-oapi<2,>=1.4; extra == "feishu"
Provides-Extra: hf
Requires-Dist: huggingface_hub>=0.20.0; extra == "hf"
Provides-Extra: modal
Requires-Dist: modal>=0.73; extra == "modal"
Provides-Extra: daytona
Requires-Dist: daytona>=0.21; extra == "daytona"
Provides-Extra: vercel-sandbox
Requires-Dist: vercel>=0.3; extra == "vercel-sandbox"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
Requires-Dist: pytest-xdist>=3.5; extra == "dev"
Requires-Dist: pytest-timeout>=2.3; extra == "dev"
Requires-Dist: ruff>=0.6; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Provides-Extra: all
Requires-Dist: polyrob[anthropic,anysite,browser,crypto,daytona,docs,feishu,gemini,hf,media,memory-vector,modal,server,solana,telegram,twitter,vercel-sandbox,voice]; extra == "all"
Dynamic: license-file

<div align="center">

<img src="https://raw.githubusercontent.com/theselfruleorg/polyrob/main/docs/assets/polyrob-logo.png" alt="POLYROB" width="440">

### A self-hosted AI agent that works toward your goals, on your own machine.

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![PyPI](https://img.shields.io/pypi/v/polyrob.svg)](https://pypi.org/project/polyrob/)
[![CI](https://github.com/theselfruleorg/polyrob/actions/workflows/ci.yml/badge.svg)](https://github.com/theselfruleorg/polyrob/actions)
[![Stars](https://img.shields.io/github/stars/theselfruleorg/polyrob?style=social)](https://github.com/theselfruleorg/polyrob)

**[Quick Start](#quick-start) · [Docs](#documentation) · [Examples](docs/examples.md) · [Comparison](docs/comparison.md)**

</div>

POLYROB is an AI agent you run yourself. Give it a task or a standing goal in plain language: it
plans the steps, uses tools (web, files, code, a shell, mail, MCP servers), recovers from its own
errors, and reports back — in your terminal, a web console, a REST API, or a chat app such as
Telegram or email.

It is for people who want an agent that keeps working between messages and whose data stays on
their own box. The agent loop and the LLM layer are native code (no third-party agent framework),
memory and state are local SQLite files, and anything that spends money waits behind caps and your
approval.

> **Self-hosted, not a SaaS.** There is no hosted version. Your keys, your data, your machine;
> only the LLM calls (and the tools you turn on) leave it.

---

## Quick Start

Python 3.11 or newer, on Linux, macOS or WSL2:

```bash
curl -fsSL https://polyrob.dev/install.sh | bash
```

The script clones the source into `~/.polyrob/src`, builds a virtualenv, puts `polyrob` on your
`PATH` and starts the setup wizard. To read it first (recommended):

```bash
curl -fsSL https://polyrob.dev/install.sh -o install.sh && less install.sh && bash install.sh
```

Or from PyPI:

```bash
pipx install polyrob          # or: pip install polyrob   ("polyrob[all]" for every extra)
polyrob setup                 # provider key, model, persona, owner, autonomy, chat surface
polyrob doctor                # preflight: keys, the model it will pick, memory, health
polyrob                       # talk to the agent
```

Where things live:

| What | Where |
|---|---|
| Configuration and keys | `~/.polyrob/.env` |
| Data (memory, goals, sessions, skills) | `~/.polyrob/data`, for every process — set `POLYROB_DATA_DIR` to move it |
| Source and virtualenv (install script only) | `~/.polyrob/src`, `~/.polyrob/venv` |

Keep it running after you close the terminal:

```bash
polyrob service install       # a systemd user unit or a launchd agent
polyrob service restart       # or /restart from chat; it finishes the current work first
```

Update a git install with `polyrob update --apply` (snapshot, migrate, verify, automatic rollback);
for pip or pipx, `polyrob update` prints the command to run. Coming from 1.7.0? Read the
[1.7.1 note](docs/guide/upgrading.md#upgrading-to-171) first. Remove it with `polyrob uninstall`.
Full walkthrough: **[getting started](docs/guide/getting-started.md)** ·
**[upgrading](docs/guide/upgrading.md)**.

---

## What it does

**Works toward goals.** A durable goal board and scheduled jobs (`"every monday 09:00"`, `30m`,
cron syntax) keep work going between your messages and across restarts. Every unattended run stops
at one step cap and one spend cap and says why it stopped. When it needs you, it raises an action
card; once you decide, it carries on. → [Jobs, goals, decisions and pauses](docs/guide/streams.md)

**Learns from use.** It keeps cross-session memory, writes and retires its own skills, and wakes
itself to follow up on unfinished work. The CLI turns on the interactive tools by itself; the
learning and self-directed loops need one more switch, `polyrob autonomy on`. Every skill or
identity edit the agent writes waits in quarantine for your review.
→ [Skills](docs/guide/skills.md) · [the autonomy dial](docs/guide/configuration.md#6-the-autonomy-dial)

**Uses real tools.** Core ships web reading (`web_fetch`, no browser needed) and Playwright
automation, files, coding tools, git and GitHub, a persistent shell with background jobs, opt-in
code execution, the agent's own mailbox, an MCP client, and sub-agents with a narrowed toolset.
First-party **packs** add more and ship inside the same install: `discovery` (AnySite structured
data, Perplexity search), `x` (the agent's X account), `markets` (Polymarket, Hyperliquid) and
remote sandbox backends. → [Packs](docs/guide/packs.md) · [Architecture](docs/guide/architecture.md)

**Meets you where you are.** The terminal (`polyrob`), a web console, a REST API with SSE, an
OpenAI-compatible `/v1` endpoint, the A2A agent protocol, an MCP server (off by default), and chat
surfaces: Telegram, email, WhatsApp, Discord, Slack, Signal, Feishu / Lark and DingTalk. Run every
enabled chat surface in one process with `polyrob gateway`.
→ [CLI](docs/guide/cli.md) · [Chat commands](docs/guide/chat-commands.md) · [API](docs/guide/api.md)

**Any model.** OpenAI, Anthropic, Google Gemini, DeepSeek, OpenRouter and NVIDIA NIM built in, plus
a catalog of other providers, OAuth subscription plans and any OpenAI- or Anthropic-compatible
endpoint you declare in `~/.polyrob/providers.yaml`. It fails over between providers, caches the
stable prompt prefix, and switches model live with `/model <name>` from the next step.
→ [Providers and models](docs/guide/configuration.md#4-providers-and-models)

### The console

<p align="center">
  <img src="https://raw.githubusercontent.com/theselfruleorg/polyrob/main/docs/assets/console/chat-running.png" alt="POLYROB Console showing a completed app build waiting for owner approval" width="100%">
</p>

Chat, Inbox (only what needs you), Work (running, next, scheduled, apps), Money and Agent (identity,
memory, capabilities, health) in one owner surface over the same goal board, approval queue and
ledger as the CLI. Start it with `polyrob dashboard` and open `http://localhost:5050`.
→ [Console guide](docs/guide/console.md)

---

## Safety, as mechanisms

- **Untrusted input is data.** Web pages, mail and tool results reach the model inside an
  untrusted-content frame, never as instructions.
- **Strangers cannot steer it.** On a chat surface only the owner steers. A third party the agent
  contacted can only return data, and while that data is in the session the high-impact tools
  (money, outbound messages, code execution, delegation) are off until the owner's next turn. Group
  rooms get a read-only toolset. → [Owner controls](docs/guide/owner-controls.md) ·
  [Groups](docs/guide/groups.md)
- **Least-privilege sub-agents.** A delegated worker gets a narrowed toolset — no money, wallet,
  shell, code execution, raw HTTP or self-modification tools — and cannot delegate again.
- **Self-edits wait for review.** New skills and identity edits go to quarantine first.
- **Code execution needs a sandbox on a server.** It is off by default; the local subprocess
  backend is a convenience for your own machine, and a server refuses any backend that is not a
  sandbox (set `CODE_EXEC_BACKEND=docker`). Child processes never inherit your API keys.
- **A shell command guard.** Every shell line is classified: a floor nothing lifts, a dangerous
  class that waits for you, and unattended runs refuse it.
- **Bounded runs.** Step and spend caps on every autonomous run, sub-agents included.

The full model, including what each gate does not do: **[security model](docs/guide/security-model.md)**.
Defaults for every flag: **[docs/CONFIGURATION.md](docs/CONFIGURATION.md)**.

---

## Money and crypto *(optional)*

The agent can hold a wallet, pay for resources over x402, send invoices and detect their settlement
on-chain, read token and wallet data, and trade within a mandate you set. Read-only token data is on
by default; nothing that spends or signs is. Every outward payment is capped and goes through an
approval rail you control.

> ⚠️ **The crypto code is unaudited.** The wallet, signing and payment code (the `crypto` extra)
> has had no independent security audit, ships with no warranty, and can lose funds. Prefer
> testnets. See [SECURITY.md](SECURITY.md#crypto--wallet--payment-features).

→ [Payments](docs/guide/payments.md) · [Wallet](docs/guide/wallet.md) · [On-chain](docs/guide/onchain.md)

---

## Self-hosting

Three postures, chosen from how you bind the console: `local` (loopback), `own_ops` (a public host
with owner login) and `multitenant` (wallet sign-in and billing). `docker compose up` builds the
server, the browser and vector memory, and keeps data in a volume.
→ [Self-hosting](docs/guide/self-hosting.md) · [Deployment postures](docs/guide/deployment-postures.md)

---

## For developers

```bash
git clone https://github.com/theselfruleorg/polyrob
cd polyrob
bash install.sh                      # installs this tree: venv, editable install, wizard
# or by hand:
python -m venv venv && source venv/bin/activate
pip install -e ".[dev,all]"
pytest tests/unit -q
ruff check .
```

The layers: `agents/` (the agent loop), `modules/` (LLM, memory, database), `tools/`, `surfaces/`
(chat apps), `api/`, `cli/`, `webview/` (console), `cron/` (scheduled runs), `core/` (config,
policy, identity), `packs/` (first-party packs) and `polyrob/` (the pack SDK).
→ [Architecture](docs/guide/architecture.md) · [AGENTS.md](AGENTS.md) (contributor guide) ·
[CONTRIBUTING.md](CONTRIBUTING.md)

---

## Documentation

**Start**

| Page | What it covers |
|---|---|
| [Getting started](docs/guide/getting-started.md) | Install, first run, extras, where data lives |
| [CLI](docs/guide/cli.md) | Every `polyrob` shell command |
| [Chat commands](docs/guide/chat-commands.md) | Slash commands on the terminal, chat apps and the console |
| [Configuration](docs/guide/configuration.md) | Providers, memory, the autonomy dial, tools, surfaces, preferences |
| [FAQ](docs/guide/faq.md) | Short answers, and troubleshooting by the exact text you see |

**Use**

| Page | What it covers |
|---|---|
| [Jobs, goals, decisions and pauses](docs/guide/streams.md) | Standing work, the goal board, the inbox |
| [Owner controls](docs/guide/owner-controls.md) | Stop, pause, resume; approvals; first contact |
| [Conversation](docs/guide/conversation.md) | One conversation across phone, console and terminal |
| [Skills](docs/guide/skills.md) | Install, author and manage skills |
| [Packs](docs/guide/packs.md) | First-party and third-party packs |
| [Groups](docs/guide/groups.md) | Group chats: allowlist, roles, per-chat policy |
| [X (Twitter)](docs/guide/x-twitter.md) | The agent's X account |
| [Feishu / DingTalk](docs/guide/feishu-dingtalk.md) | The Feishu / Lark and DingTalk surfaces |
| [Console](docs/guide/console.md) | The web console |

**Run**

| Page | What it covers |
|---|---|
| [Operate the service](docs/guide/operate-the-service.md) | Start, stop, restart and update the background service |
| [Upgrading](docs/guide/upgrading.md) | Updates, snapshots, rollback, version notes |
| [Self-hosting](docs/guide/self-hosting.md) | Servers, Docker, units |
| [Deployment postures](docs/guide/deployment-postures.md) | `local`, `own_ops`, `multitenant` |
| [Profiles](docs/guide/profiles.md) | Several isolated agents on one machine |
| [Instances](docs/guide/instances.md) | Identity: SOUL, character, avatar |
| [Migration](docs/guide/migration/README.md) | Moving from another agent framework |

**Money**

| Page | What it covers |
|---|---|
| [Payments](docs/guide/payments.md) | Invoicing, settlement, credits, the ledger, the arming ladder |
| [Wallet](docs/guide/wallet.md) | The agent wallet, signer, caps, paying over x402 |
| [On-chain](docs/guide/onchain.md) | Token data, guarded transfers and swaps, the trading mandate |

**Reference**

| Page | What it covers |
|---|---|
| [API](docs/guide/api.md) | REST, A2A, OpenAI-compatible `/v1`, MCP server |
| [Architecture](docs/guide/architecture.md) | How the parts fit together |
| [Security model](docs/guide/security-model.md) | Each gate, and the OS or container boundary behind it |
| [Rails verification](docs/guide/rails-verification.md) | What counts as proof that a send landed |
| [docs/CONFIGURATION.md](docs/CONFIGURATION.md) | Every environment flag and its default |
| [Comparison](docs/comparison.md) · [Examples](docs/examples.md) | Other frameworks; real usage |
| [CHANGELOG](CHANGELOG.md) · [SECURITY](SECURITY.md) | Changes; reporting a vulnerability |

---

## Contributing and license

Contributions are welcome — see [CONTRIBUTING.md](CONTRIBUTING.md). Report vulnerabilities as
[SECURITY.md](SECURITY.md) describes. MIT licensed ([LICENSE](LICENSE)); name and brand use in
[TRADEMARK.md](TRADEMARK.md); third-party attributions in
[THIRD-PARTY-NOTICES.md](THIRD-PARTY-NOTICES.md).

<div align="center">

**POLYROB** — by [The Selfrule Organization](https://theselfrule.org)

</div>
