# PawFlow Agents > PawFlow (Platform for Agentic Workflows) Self-hosted agent runtime for real infrastructure. Run durable AI agents against your own files, tools, browsers, desktops, services, and workflows with relay-backed execution, shared context, multi-provider agents, and deterministic flows. - **Type:** MCP server - **Install:** `agentstack add mcp-allcolor-pawflow-agents` - **Verified:** Yes โ€” security-reviewed for prompt injection and unsafe behavior - **Seller:** [allcolor](https://agentstack.voostack.com/s/allcolor) - **Installs:** 0 - **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [allcolor](https://github.com/allcolor) - **Source:** https://github.com/allcolor/PawFlow-Agents - **Website:** https://pawflow.allcolor.org/ ## Install ```sh agentstack add mcp-allcolor-pawflow-agents ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About PawFlow Self-hosted agent runtime for real infrastructure. Run durable AI agents against your own files, tools, browsers, desktops, services, and workflows. Website ยท Quickstart ยท Docs ยท Releases ๐Ÿ‘‰ Screenshots, live feature tour, quickstart, and full documentation live on pawflow.allcolor.org. The Ask PawFlow help bot on the website is powered by a PawFlow agent flow (web_help_bot, behind /api/help). --- PawFlow is the runtime layer between chat agents, local tools, and production workflows. The server keeps conversations, context, memory, files, flows, and provider sessions durable. Relays execute filesystem, shell, browser, desktop, and media tools next to the machines where the work actually happens. Use it when a hosted coding assistant is too boxed-in, a workflow tool is too rigid, and a library is not enough runtime. ## Why PawFlow PawFlow gives agents a real operating surface without handing your workspace to a vendor-controlled agent cloud. - **Relay-backed tools**: read, edit, grep, run commands, browse, control desktops, generate media, and inspect projects through explicit relay routes. - **Durable context**: conversations, shared context, per-agent context, memory, knowledge graphs, diaries, project graphs, files, and buckets survive restarts. - **Encryption at rest (opt-in)**: per-conversation passphrase encryption of message content, thinking, and tool I/O (and conv-scoped relay workspaces via CryFS); keys live in RAM only, so a stopped server leaves only ciphertext on disk. Off by default and transparent to conversations that don't use it. - **Multi-provider agents**: mix Codex app-server, Claude Code, Antigravity/Agy, Gemini CLI, Anthropic, OpenAI, and OpenAI-compatible services per agent or conversation. - **Shared clients**: continue the same conversation from the web UI, PawCode CLI, VS Code, API clients, or channel integrations. - **Deterministic flows**: turn repeated work into NiFi-style DAGs with scheduling, backpressure, checkpoints, approvals, and explicit LLM steps. - **Package ecosystem**: distribute agents, skills, tools, services, flow tasks, flows, and UI extensions as signed `.pfp` packages or import skills from supported marketplaces. ## What You Can Build - Agentic coding sessions against a linked workspace, with persistent context and auditable tool output. - Multi-agent operations where planners, coders, reviewers, researchers, and verifiers work in the same conversation. - Browser and desktop automation for workflows that do not have clean APIs. - Media pipelines that create images, video, audio, 3D assets, voice, and FileStore outputs. - Scheduled operational flows: daily digests, inbox triage, data transforms, reports, monitoring, and webhook-driven automation. - Reusable packages and registries for sharing internal or community agents, skills, tools, services, flow tasks, flows, and UI extensions. - Live help bots: the **Ask PawFlow** assistant on [pawflow.allcolor.org](https://pawflow.allcolor.org/) is powered by a PawFlow agent flow (`web_help_bot`) answering questions in real time, with a Telegram counterpart (`telegram_help_bot`). - Portable conversations with full PawFlow archives, including optional FileStore attachments and generated files. ## Quick Start > ๐Ÿ“– Prefer a guided version with screenshots? Follow the > [quickstart on the website](https://pawflow.allcolor.org/quickstart.html). The easiest path is the Docker installer from the latest release. It starts PawFlow, opens the bootstrap wizard, creates the first admin user, configures the selected LLM services, deploys the starter flow, and opens your first agent conversation. ### Docker Installer Downloadable artifacts are published on the [latest GitHub release](https://github.com/allcolor/PawFlow-Agents/releases/latest): installer zip, PawCode packages, Relay CLI archives, Relay Desktop installers, checksums, and source archives. ```bash PAWFLOW_VERSION=$(curl -fsSL https://api.github.com/repos/allcolor/PawFlow-Agents/releases/latest \ | python3 -c 'import json,sys; print(json.load(sys.stdin)["tag_name"])') curl -L -o "pawflow-install-$PAWFLOW_VERSION.zip" \ "https://github.com/allcolor/PawFlow-Agents/releases/download/$PAWFLOW_VERSION/pawflow-install-$PAWFLOW_VERSION.zip" unzip "pawflow-install-$PAWFLOW_VERSION.zip" cd "pawflow-install-$PAWFLOW_VERSION" bash scripts/install-pawflow.sh --port PORT --pull-images ``` `--version` is optional: when omitted the installer resolves the latest published release from GitHub. Pass `--version "$PAWFLOW_VERSION"` to pin a specific release. On Windows PowerShell with Docker Desktop Linux containers, use the bundled PowerShell installer instead: ```powershell powershell -ExecutionPolicy Bypass -File scripts/install-pawflow.ps1 -Port PORT -PullImages ``` `-Version` is likewise optional and defaults to the latest published release; pass `-Version $env:PAWFLOW_VERSION` to pin a specific release. Check and apply release updates with: ```bash bash scripts/install-pawflow.sh --check-updates bash scripts/install-pawflow.sh --self-update bash scripts/install-pawflow.sh --version NEW_VERSION --port PORT --pull-images ``` The update command recreates the PawFlow server container on the requested image while keeping persistent data under `PAWFLOW_HOME`, then removes older PawFlow server/relay image tags unless `--keep-old-images` is set. On Linux hosts with AppArmor (Ubuntu, Debian, ...), the installer also loads the PawFlow AppArmor profiles (`pawflow-mount` for provider pool containers, `pawflow-relay` for relay containers) into `/etc/apparmor.d/` โ€” sudo may prompt once. This confines the containers' mount privileges to exactly what they need; without the profiles PawFlow still works but those containers run `apparmor=unconfined`. Skip with `--skip-apparmor`, or load them manually later: ```bash sudo install -m 644 docker/apparmor/pawflow-mount docker/apparmor/pawflow-relay /etc/apparmor.d/ sudo apparmor_parser -r -W /etc/apparmor.d/pawflow-mount /etc/apparmor.d/pawflow-relay ``` Hosts without AppArmor (Windows/macOS Docker Desktop, WSL2, SELinux distros) are detected and skipped automatically โ€” nothing to do there. Open the installer at: ```text https://localhost:PORT/install ``` The first-run Private Gateway key is `RoyBetty`. Finalizing the wizard replaces it. ### From Source ```bash git clone https://github.com/allcolor/PawFlow-Agents.git cd PawFlow-Agents pip install -r requirements.txt python cli.py start --host 0.0.0.0 --port PORT ``` Open the web chat at: ```text http://localhost:PORT/chat ``` ## Clients ### Web UI The web UI is the main operator surface: chat, context editor, memory editor, file attachments, relay tools, desktop entry points, terminals, provider sessions, and flow actions in one place. ### PawCode CLI PawCode is a terminal client for the same PawFlow conversations. It can be used interactively or in Claude Code-compatible stream-JSON mode. ```bash pawcode --server http://localhost:PORT echo '{"type":"user","message":{"role":"user","content":"hello"}}' | \ pawcode --input-format stream-json --output-format stream-json ``` ### VS Code The VS Code extension attaches to the same PawFlow conversation and resource panel from inside your editor. ### Telegram Telegram bridges chats into the same conversations: message a BotFather bot and agents reply inline (web login uses the Telegram Login Widget). ## Architecture ``` โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ PawFlow Server โ”‚ โ”‚ โ”‚ โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ โ”‚ โ”‚ Agents โ”‚ โ”‚ Pipeline โ”‚ โ”‚ Auth โ”‚ โ”‚ Web Chat UI โ”‚ โ”‚ โ”‚ โ”‚ (LLM + โ”‚ โ”‚ Engine โ”‚ โ”‚ Gateway โ”‚ โ”‚ (SSE, files, โ”‚ โ”‚ โ”‚ โ”‚ tools) โ”‚ โ”‚ (100+ โ”‚ โ”‚ (9 OAuth โ”‚ โ”‚ context, โ”‚ โ”‚ โ”‚ โ”‚ โ”‚ โ”‚ tasks) โ”‚ โ”‚ provid.) โ”‚ โ”‚ commands) โ”‚ โ”‚ โ”‚ โ””โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ โ”‚ โ”‚ โ”‚ โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ โ”‚ โ”‚ 90+ Tool Handlers (via relay) โ”‚ โ”‚ โ”‚ โ”‚ bash, read, write, edit, glob, grep, web_search, โ”‚ โ”‚ โ”‚ โ”‚ screen, browser, generate_image, generate_video, โ”‚ โ”‚ โ”‚ โ”‚ generate_audio, generate_3d, clone_voice, speak, โ”‚ โ”‚ โ”‚ โ”‚ remember, kg_add, project_graph, delegate, plans, ... โ”‚ โ”‚ โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ โ”‚ โ”‚ WebSocket โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ Relay (Docker) โ”‚ โ† runs on user's machine โ”‚ or native host โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ ``` The **server** hosts the API, agent orchestration, pipeline engine, and web UI. A **relay** runs on the user's machine (or in a Docker container) and executes tools โ€” filesystem access, bash commands, code edits โ€” over a WebSocket connection. This means agents can manipulate your local codebase without the server needing direct access to your files. Connect a relay with the relay CLI or Relay Desktop to attach workspaces, desktops, browsers, and terminals. ## LLM Providers | Provider | Mode | Features | |---|---|---| | **Claude Code** | CLI subprocess/container + MCP | Non-interactive coding turns, session persistence, thinking | | **Claude Code interactive** | Interactive CLI container + observed stream | Claude subscription sessions, live control, provider-observed usage | | **Codex app-server** | App-server protocol in pooled container | Codex subscription or OpenAI API-key coding agents, threads, steering | | **Antigravity / Agy** | Interactive CLI container + observed stream | Default Gemini subscription provider, Gemini OAuth pool, MCP tools | | **Gemini CLI** | CLI subprocess/container | Secondary Gemini CLI path for Pro/CLI-specific workflows | | **Anthropic API** | Direct HTTP | Streaming, tool use, vision, extended thinking | | **OpenAI API** | Direct HTTP | Streaming, tool use, vision, JSON mode | | **OpenAI-compatible** | Direct HTTP | Local/self-hosted and third-party compatible endpoints via `base_url` | Switch providers per agent, per conversation, or globally. API keys normally use direct `openai`/`anthropic` services; subscription logins use the matching CLI-backed provider (`codex-app-server`, `claude-code-interactive`, or `antigravity-interactive`). Self-hosted and third-party LLMs can use the OpenAI-compatible endpoint (`base_url` override). See [LLM Providers](docs/llm_providers.md). ## Agent Capabilities ### Cognitive Systems Agents have persistent memory that survives across conversations: | System | Purpose | Storage | |--------|---------|--------| | **Memory** | Facts, preferences, events organized in wing/hall/room taxonomy | `data/memories/{user}.json` | | **Knowledge Graph** | Entity-relationship triples with temporal validity | `data/knowledge_graphs/{user}.json` | | **Agent Diary** | Personal observations, decisions, learnings per agent | `data/memories/{user}/diary_{agent}.jsonl` | | **Project Graph** | AST-based code structure graph (17 languages via tree-sitter) | `data/graphs/{user}/{conv}/graph.json` | Memory digests and diary entries are automatically injected into the system prompt. ### Multi-Agent - Delegate tasks to sub-agents with `delegate()` - Each sub-agent gets its own LLM, tools, and conversation context - Agents can run in parallel or sequentially - Git worktree isolation for parallel coding tasks is on the roadmap ### Plans - Create structured multi-step plans with `create_plan()` - Step-by-step execution with approval gates - Assign steps to different agents - Verify completed work before moving on ## Pipeline Engine 100+ tasks across 5 categories for data processing workflows: | Category | Count | Examples | |----------|-------|----------| | **System** | 11+ | log, wait, executeScript, cronTrigger, listFiles | | **IO** | 50+ | HTTP, Telegram, Discord, Slack, WhatsApp, S3, GCS, Azure, SFTP, Kafka, MQTT, email, chat UI, relay | | **Data** | 25+ | transformJSON, inferLLM, executeSQL, compressContent, validateJSON, Avro/Parquet | | **Control** | 10+ | routeOnAttribute, splitContent, mergeContent, controlRate, subflows, wait/notify | | **AI** | 2+ | agentLoop, agentActions, tool-use cycle | Flows are defined in JSON, executed as DAGs, and support backpressure, checkpointing, crash recovery, parameter contexts, subflows, and CRON scheduling. ## Packages and Marketplace PawFlow Packages (`.pfp`) are signed zip artifacts for distributing PawFlow resources. A package can include agents, prompts, skills, themes, task definitions, flows, service definitions, tools, service providers, flow tasks, task providers, and UI extensions. Install is review-first: PawFlow verifies the package signature and lock file, shows a selectable install plan, records per-object provenance, and executes code-bearing objects through a relay runtime instead of importing third-party code into the server process. Common package workflows: ```bash /pfp key-create /pfp build ./my-package.pfpdir --key-env PAWFLOW_PFP_SIGNING_KEY /pfp inspect ./dist/my-package-1.0.0.pfp /pfp install ./dist/my-package-1.0.0.pfp --include skill:x,service_provider:y /pfp dev-load ./my-package.pfpdir --include service_provider:image --secret api_key=my_provider_key /pfp export --package my.bundle --version 0.1.0 --include agent:helper,flow:daily --out ./my.bundle.pfpdir ``` Marketplace and registry support is decentralized. Users can add static package registries, search them, inspect remote packages with explicit download confirmation, then install or update selected objects. Skill marketplace import is also supported for Codex/OpenAI skills, Claude/Anthropic plugin marketplaces, HermesHub, and OpenClaw GitHub tree URLs; imports are bounded, reviewed, and never grant tool permissions automatically. See [PawFlow Packages](docs/PFP_PACKAGES.md), [PFP Developer Guide](docs/PFP_DEVELOPER_GUIDE.md), [PFP Publisher Guide](docs/PFP_PUBLISHER_GUIDE.md), and [Marketplace](docs/marketplace.md). ### Expression Language 40+ chainable operations for dynamic configuration: ``` ${name:upper} โ†’ "ALICE" ${api_key:default("not-set")} โ†’ uses fallback if empty ${status:equals("active"):then("ON"):else("OFF")} โ†’ conditional logic ${csv_line:split(","):index(0):trim} โ†’ first CSV field, trimmed ${response:json_get("data.items.0.id")} โ†’ extract from JSON ${content:hash_sha256} โ†’ hash a value ${:uuid} โ†’ generate a UUID ${:now:format("yyyy-MM-dd")} โ†’ "2026-04-08" ``` Expressions resolve through a cascade: secrets โ†’ flow parameters โ†’ conversation โ†’ user โ†’ global โ†’ environment variables. See [Expression Language docs](docs/EXPRESSION_LANGUAGE.md) for the full reference. ## Web Chat - Real-time streaming via SSE - Shared conversations across web, PawCode CLI, VS Code, API clients, and channel flows - File explorer with relay filesystem access - Context editor (view/edit agent context) - Conversation management with auto-titles - Drag & drop file attachments and FileStore outputs - 60+ slash commands (`/agent`, `/memory`, `/relay`, `/run`, `/plan`, `/desktop`, ...) - Desktop/VNC entry points plus relay-backed `screen` actions - Escape key: 1x = graceful interrupt, 2x = force stop - Multi-agent with agent switching ## Authentication 9 OAuth providers out of the box: | Provider | Status | |----------|--------| | Built-in (username/password) | Ready, tested | | Generic OAuth2 | Ready, tested | โ€ฆ ## Source & license This open-source MCP server is cataloged on AgentStack and links to its original source โ€” we do not rehost the code. - **Author:** [allcolor](https://github.com/allcolor) - **Source:** [allcolor/PawFlow-Agents](https://github.com/allcolor/PawFlow-Agents) - **License:** MIT - **Homepage:** https://pawflow.allcolor.org/ Install and usage instructions live in the source repository linked above. ## Pricing - **Free** โ€” Free ## Security capabilities Automated source analysis of v0.1.0 โ€” what this tool can access: - **Network access:** yes - **Filesystem access:** no - **Shell / process execution:** yes - **Environment & secrets:** yes - **Dynamic code execution:** no *"Yes" means the capability is present in the source โ€” more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** โ€” security scan: passed โ€” Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-allcolor-pawflow-agents - Seller: https://agentstack.voostack.com/s/allcolor - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack โ€” the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.