PawFlow

How-tos

Small recipes for the first useful PawFlow sessions.

Install the runtime, connect relays, configure providers, publish packages, and turn useful agent work into flows.

InstallWizardDesktopPawCodePawCode usageVS Code pluginRelay DesktopRelay CLIIdentityResourcesFlowsTelegramSecurityMedia

Install and relays

From first server to controlled workspaces.

Install script + wizard

Run the release installer and reach the first conversation

Objective: show the full first-run path from the shell script to the PawFlow conversation screen with assistant selected.

Terminal running the PawFlow release install script
1. Download the release zip, unzip it, and run scripts/install-pawflow.sh.
Video: install script, browser wizard, and first chat.
terminal
Loading current release command...
Gateway screenOpen https://localhost:19990/install, accept the local certificate for private installs, enter the bootstrap key, then replace it with your real Private Gateway key.
Admin screenCreate the first admin account. This user owns the initial runtime resources and can configure global agents/services.
LLM provider screenSelect the first provider: Codex app-server, Claude Code interactive, Antigravity/Agy, Gemini CLI, Anthropic, OpenAI, or an OpenAI-compatible endpoint.
Summarizer screenChoose the summarizer service and context limits so compaction is explicit and does not flood provider context.
Runtime screenDeploy the main PawFlow Agent flow: httpReceiver to agentLoop to handleHTTPResponse.
Conversation screenOpen the starter conversation, confirm assistant is selected, send a small prompt, and verify streaming output.
PawFlow installer gateway screen
Gateway and bootstrap key.
PawFlow installer admin account screen
Admin account.
PawFlow installer LLM provider screen
LLM service.
First PawFlow conversation after install
First conversation.

Expected result: PawFlow is running on the selected port, the wizard is complete, and the first conversation can call the selected provider.

Desktop, noVNC, audio, screen tools

Use a relay desktop with noVNC, audio, screen, and see

Objective: explain the operator view and the agent-visible tools for desktop work. This applies to any relay running a desktop-capable image — server relay, remote Relay CLI, or Relay Desktop alike.

Desktop Relay noVNC session in the browser
Desktop (VNC): noVNC opens the relay desktop in the browser.
Audio-only relay streaming panel
Audio only: stream the relay's sound without opening a desktop.
Video: agent inspects the screen, then acts through approved tools.
  1. Connect any relay whose image ships the virtual desktop (server relay, remote Relay CLI, or Relay Desktop); for a local GUI session, install Relay Desktop on the workstation that owns it.
  2. Open Desktop from the webchat workspace menu and choose the relay's virtual desktop, or the local desktop when allow_local is intentionally enabled.
  3. Use noVNC for operator observation/control; enable audio only for sessions that need sound playback or capture.
  4. Let agents inspect UI state through screen screenshots or see multimodal analysis, then approve clicks/typing/shell/file actions separately.
  5. Keep desktop permissions narrower than filesystem permissions when the task only needs visual inspection.

Expected result: the user can watch the same desktop surface the agent sees, while agent actions remain routed through auditable screen/see/tool calls.

Read desktop docs
PawCode installer

Install PawCode and attach a terminal agent to PawFlow

Objective: install the PawCode CLI package and continue a PawFlow conversation from a terminal.

PawCode installer and terminal login
Download the platform package, install it, then connect to the PawFlow server.
Video: install, login, select conversation, stream a response.
Linux zipWindows zipDebian packagePawCode docsCommands, auth, streaming events, and conversation bootstrap.
  1. Download the PawCode asset matching the release version shown above.
  2. Install the package or unzip it into a directory on PATH.
  3. Run PawCode, point it at the PawFlow server, and authenticate with the same user.
  4. Select an existing conversation or create a new one; relays, memories, and tool policies stay server-side.

Expected result: terminal work and webchat share the same PawFlow conversation instead of creating an isolated provider session.

PawCode usage

Start PawCode with explicit server and Private Gateway settings

Objective: make the terminal client predictable across localhost, private deployments, and gateway-protected routes.

PawCode server and gateway settings
Set the server URL once, then login and resume shared conversations.
Video: server URL, Private Gateway key, login, resume, and run a relay-backed command.
PawCode terminal client running a live agent conversation with streaming thinking and tool events
PawCode in a terminal: live thinking, tool calls, and streaming responses over the same backend.
terminal
# Local server
PAWFLOW_SERVER="https://localhost:19990" pawcode --dir .

# Gateway-protected server
PAWFLOW_SERVER="https://pawflow.example.com" \
PAWFLOW_GATEWAY_KEY="your-private-gateway-key" \
pawcode --dir .

# Common flow after login
pawcode auth login
pawcode --dir .
  1. Use PAWFLOW_SERVER for the exact PawFlow origin, including scheme and port.
  2. Use PAWFLOW_GATEWAY_KEY when Private Gateway protects API/SSE routes; keep it in your shell profile or secret manager, not in prompts.
  3. Run pawcode auth login if the browser auth token is missing or expired.
  4. Use /conv and /resume <id> to continue webchat conversations.
  5. Use /new --agent assistant --llm <service> --relay <relay_id> when creating a terminal-first conversation with an existing relay binding.

Expected result: PawCode connects to the intended PawFlow server, passes Private Gateway cleanly, and uses the same relay/tool permissions as webchat.

Read PawCode docs
VS Code plugin

Install the PawFlow VS Code extension from a release VSIX

Objective: make the VS Code client installable without opening the extension source folder or running a development host.

VS Code install from VSIX flow
Install the release .vsix, configure the server URL, then login.
Video: install from VSIX, settings, login, chat sidebar, selection actions.
PawFlow extension running inside VS Code with a live agent conversation, streaming responses and tool events in the chat panel
The PawFlow panel in VS Code: chat, conversations, files, tools, and live streaming over the same backend.
VS Code VSIXExtension docsSettings, gateway key, commands, and local VSIX build.Developer READMEDevelopment host, compile command, and package command.Terminal alternativeUse PawCode when you want the same conversation from a shell.
  1. Download pawflow-vscode-<version>.vsix from the current release.
  2. In VS Code, run Extensions: Install from VSIX... and choose the file.
  3. Set pawflow.serverUrl to the PawFlow server, for example https://localhost:19990.
  4. Set pawflow.gatewayKey when Private Gateway is enabled.
  5. Run PawFlow: Login, then use the PawFlow activity bar view or editor context menu actions.

Expected result: VS Code is another PawFlow client over the same backend, not a separate relay or hidden agent runtime.

Relay Desktop installer

Install Relay Desktop for GUI workstations

Objective: connect a desktop machine to PawFlow with filesystem, terminal, browser, noVNC, audio, and screen capabilities scoped by relay profile.

Relay Desktop installer and connection profile
Install the desktop app, create a PawFlow server profile, then register a workspace.
Video: installer, profile, workspace, connected relay.
Linux AppImageDebian packageWindows zipWindows setupRelay Desktop docsProfiles, local helper, desktop access, and packaging notes.
  1. Install the Relay Desktop package for the workstation OS.
  2. Add the PawFlow server URL and authenticate with the user that owns the conversation.
  3. Register a workspace root and choose whether local host access is allowed.
  4. Confirm the relay appears connected in PawFlow before enabling desktop or shell tools.

Expected result: webchat can link the workstation relay and use Desktop Relay/noVNC for GUI tasks.

Relay CLI installer

Install Relay CLI for server and terminal workspaces

Objective: run a lightweight relay on machines that do not need the Desktop app.

Relay CLI install and terminal connection
Unpack the CLI, authenticate, and connect a workspace directory.
Video: CLI install, profile/login, relay connected in webchat.
Linux zipLinux tarballWindows zipRelay CLI docsHeadless relay setup, workspace roots, and tool boundaries.
  1. Download the Relay CLI archive for the target machine.
  2. Unpack it and place the executable on PATH, or run it from the extracted directory.
  3. Authenticate against the PawFlow server and register a workspace root.
  4. Use Docker/container relay mode for isolated work, and enable local host mode only for trusted tasks.

Expected result: the machine appears as a relay-backed filesystem/shell target without requiring a desktop session.

Install

Install PawFlow with Docker

Objective: start a self-hosted PawFlow server and open the first-run wizard.

  1. Open the current release downloads for .
  2. Download the installer zip.
  3. Unzip it and run the install command shown in the quickstart.
  4. Open `https://localhost:19990/install`.

Expected result: a starter conversation with `assistant` selected.

Open full quickstart
Managed PawFlow server relay setup
Server relay

Install a managed relay server

Objective: run a full relay on the PawFlow server itself, so agents get filesystem, shell, and tool access to server-side workspaces — the pure remote self-hosted setup — and client relays can register against it.

  1. Install PawFlow and complete the first-run wizard.
  2. Open resources/services and add a `relay` service.
  3. Leave `token` empty for a managed server relay.
  4. Save and confirm health before attaching client relays.

Expected result: agents can work directly in server-side workspaces, and PawFlow can broker filesystem, shell, screen, browser, and desktop-capable clients.

Read service docs
Relay Desktop and Relay CLI installation
Remote relay

Install a remote relay with Desktop or CLI

Objective: connect the machine that owns the files, terminal, browser, or desktop to PawFlow.

  1. Choose Relay Desktop for GUI workstations or Relay CLI for server/terminal machines.
  2. Install the package from the release downloads.
  3. Add the PawFlow server URL and gateway key/login.
  4. Register a workspace and link it to the webchat conversation.

Expected result: the workstation appears as a selectable relay with explicit tool boundaries.

Read relay client docs
Desktop relay session in PawFlow
Desktop

Open a desktop through a relay

Objective: give an agent controlled access to a full desktop surface for UI work.

  1. Start a relay with desktop/screen tooling enabled.
  2. Open the Desktop Relay view from webchat.
  3. If the relay uses `allow_local`, choose the local desktop where the host helper runs.
  4. Require approvals for screen, browser, shell, file, and delete operations.

Expected result: the agent can inspect and operate a desktop while you watch the same session.

Read desktop docs
Relay terminal open in a webchat tab
Terminals

Open relay terminals from webchat

Objective: debug or operate the environment attached to a conversation without leaving the browser.

  1. Open the webchat workspace menu.
  2. Choose the Docker relay terminal for containerized workspace commands.
  3. Choose the local terminal only when `allow_local` is enabled intentionally.
  4. Use the server relay terminal to work directly in PawFlow server workspaces and provider containers.

Expected result: Docker, local host, and server relay boundaries remain visible.

Read filesystem docs
Agents

Configure the first LLM-backed agent

Objective: connect the assistant to Codex app-server, Claude Code interactive, Antigravity/Agy, Gemini CLI, Anthropic, OpenAI, or a compatible endpoint.

  1. Create or select an LLM service in the installer/resource panel.
  2. Use direct `openai`/`anthropic` for API keys, `codex-app-server` for Codex subscriptions, `claude-code-interactive` for Claude subscriptions, and `antigravity-interactive` for Gemini subscriptions.
  3. Set credentials through secrets or the matching OAuth credential provider.
  4. Send a small inspection task before allowing edits or shell.

Expected result: streaming responses from the selected provider.

Read provider docs
VS Code code-server attached to a PawFlow relay
Editor

Open VS Code/code-server on the relay workspace

Objective: review files manually while agents continue to work in the same conversation.

  1. Link the target relay to the conversation.
  2. Open VS Code/code-server from the webchat workspace menu.
  3. Inspect diffs, run searches, or edit files directly in the browser editor.
  4. Ask the agent to explain or continue from the same relay workspace.

Expected result: manual review and agent work share one workspace boundary.

Read VS Code docs
Providers

Inspect interactive provider tmux sessions

Objective: debug subscription-backed CLI providers without losing the conversation state.

  1. Configure `claude-code-interactive` or `antigravity-interactive` for the selected agent.
  2. Open the provider runtime view or relay terminal from webchat.
  3. Inspect the tmux session when login, tool approval, or provider streaming needs attention.
  4. Return to the conversation after the provider state is healthy.

Expected result: interactive CLI providers stay observable instead of becoming hidden subprocesses.

Read provider docs

Identity, filesystems, and secrets

Connect accounts without leaking credentials.

OAuth provider setup in PawFlow
OAuth

Set up an OAuth provider

Objective: let users sign in through a supported external identity provider.

  1. Create the OAuth application at the provider and copy the client id/secret.
  2. Set the redirect URI to your PawFlow callback URL, for example `https://your-host/auth/callback`.
  3. Add the provider in Auth Gateway or the installer OAuth step.
  4. Set allowed domains, default role, and auto-provisioning rules before exposing the login button.
GoogleGoogle Cloud Console OAuth client, authorized redirect URI, email/profile scopes.
GitHubGitHub OAuth App, callback URL, optional org restrictions.
MicrosoftEntra app registration, web redirect URI, user.read/email scopes.
XX/Twitter developer app, OAuth callback, profile/email permissions when available.
Meta/FacebookMeta app, Facebook Login product, valid OAuth redirect URI.
AmazonLogin with Amazon security profile, allowed return URL.
TelegramBotFather bot plus allowed domain for Telegram login widget.
GenericAny OIDC/OAuth provider with authorize, token, userinfo endpoints.

Expected result: external users authenticate through PawFlow with predictable provisioning.

Read auth docs
rclone filesystem setup
Filesystem

Add an rclone filesystem

Objective: mount remote storage such as Google Drive or OneDrive into relay-backed tools.

  1. Create an `rcloneOAuthCredentials` service for the backend, such as Google Drive or OneDrive.
  2. Add an `rcloneFilesystem` service that references the credential service.
  3. Link the filesystem service to the conversation or relay.
  4. Use `/remote/<service_id>` from relay shell/tools when the relay image includes rclone.

Expected result: agents can read/write approved remote storage without storing raw OAuth tokens in prompts.

Read filesystem tools
Config

Use variables and secrets

Objective: keep reusable values visible and credentials encrypted.

  1. Create variables for non-secret values such as model names, ports, feature flags, and environment labels.
  2. Create secrets for tokens, API keys, OAuth client secrets, webhooks, and package bindings.
  3. Reference variables through expression language and secrets through service configuration instead of prompt text.
  4. Review scope: global, user, conversation, package, or flow.

Expected result: flows, services, and packages can be configured without leaking credentials into conversation context.

Read expression docs

Repositories, skills, tools, and marketplace

Manage the PawFlow depots as product resources.

Depots

Understand PawFlow resource depots

Objective: know where reusable definitions live and how scope changes visibility.

  1. Use the resource panel to browse agents, flows, skills, prompts, tools, MCP servers, services, themes, task definitions, and packages.
  2. Choose the right scope: global for shared defaults, user for personal assets, conversation for local experiments.
  3. Promote stable resources upward only after review.
  4. Keep secrets separate from imported packages and marketplace assets.

Expected result: teams can reuse resources without mixing experiments with production defaults.

Read resource tools
Skills

Create, import, and use skills

Objective: give agents task-specific instructions and assets on demand.

  1. Create a skill with `/skill add @name "prompt"` or from the resource panel.
  2. Import reviewed external skills from supported marketplaces or GitHub trees.
  3. Assign skills explicitly to agents with `/skill assign @agent @skill`.
  4. Run a skill immediately with `/skill run` or `//skill-name`; agents load full content with `load_skill` only when needed.

Expected result: specialized knowledge is available without bloating every prompt.

Read skill commands
Extend

Add MCP servers, hooks, tools, flows, and prompts

Objective: extend agents with controlled capabilities.

  1. Add MCP servers as opt-in resources and activate them only for the conversations that need them.
  2. Add tools for reusable actions, and document required inputs, side effects, and permissions.
  3. Add agent hooks for pre/post behavior where policy or automation must run around agent turns.
  4. Create prompts and flows as versioned resources so operators can reuse them without copying chat text.

Expected result: extensions are explicit, reviewable, and scoped.

Read tool catalog
PFP package install and marketplace
Packages

Import, export, and update PFP packages

Objective: move signed bundles of agents, flows, skills, themes, tools, task providers, and service providers between environments.

  1. Inspect a `.pfp` before installing; review capabilities, object list, required secrets, and risk flags.
  2. Install only selected objects and bind package secrets to existing PawFlow secrets.
  3. Export stable local resources into a `.pfp` or `.pfpdir` for review.
  4. Use update/uninstall through the package registry instead of overwriting resources manually.

Expected result: reusable assets can be distributed with provenance and explicit consent.

Read package docs
Marketplace

Use marketplace assets safely

Objective: discover packages or skills without trusting remote metadata blindly.

  1. Add registries from the package dialog or package commands.
  2. Search by capability, package id, author, or object type.
  3. Confirm download size/hash before fetching remote `.pfp` files.
  4. Install only reviewed objects and keep marketplace secrets bound locally.

Expected result: marketplace discovery stays separate from execution trust.

Read publisher guide
Themes

Select, create, and import themes

Objective: customize the webchat without editing product code.

  1. Select a global or conversation theme from the chat theme menu.
  2. Create a theme resource with `theme.json`, CSS, and optional assets.
  3. Import a theme from a PFP package or resource depot.
  4. Test readability across chat, resource panels, terminals, and modals before sharing globally.

Expected result: teams can brand or specialize workspaces while preserving accessible controls.

Read theme docs

Flows, tasks, and plans

Turn agent work into explicit automation.

PawFlow flow engine explanation
Flows

Understand PawFlow flows

Objective: know when to use deterministic flow execution instead of a free-running agent loop.

  1. Model work as a graph of tasks connected by relationships.
  2. Use services for external systems, credentials, LLMs, filesystems, and media providers.
  3. Use triggers for schedules, webhooks, messages, files, or manual starts.
  4. Keep LLM calls explicit through agent or `inferLLM` tasks where variability is acceptable.

Expected result: recurring work runs with visible routing, retries, checkpoints, and backpressure.

Read architecture docs
Main PawFlow Agent flow
Agent flow

Understand the main PawFlow Agent flow

Objective: recognize the runtime path behind the starter webchat.

  1. `httpReceiver` accepts chat/API events.
  2. `agentLoop` builds context, calls the selected LLM service, executes tools, and streams events.
  3. `handleHTTPResponse` returns the immediate HTTP response while background streaming continues.
  4. Conversation store, event bus, memory, relays, and FileStore keep the UI synchronized.

Expected result: operators can debug whether an issue is HTTP, context, provider, tool relay, or persistence.

Read agent system docs
Plans

Use tasks and PawFlow plans

Objective: coordinate work that needs status, verification, or recurrence.

  1. Use tasks for assigned work, scheduled loops, or recurring objectives.
  2. Use `create_plan` for multi-step work that needs approval before execution.
  3. Update plan steps as they move through pending, in progress, blocked, and done.
  4. Use verification when another agent or user must approve the result before continuing.

Expected result: long work becomes observable instead of a hidden chat thread.

Read task commands
Agent-created daily digest flow
Automation

Create a deterministic daily digest flow

Objective: use an agent to design a recurring automation, then let a JSON flow run it.

  1. Prompt the agent to create a daily digest with source fetch, LLM summary, and delivery.
  2. Review the generated task graph.
  3. Keep LLM calls explicit through `inferLLM` tasks.
  4. Deploy the flow once the shape is correct.

Expected result: CRON and flow tasks execute without a free-running agent in the loop.

Read the example

Channels

Reach the same agents from messaging apps.

Chatting with a PawFlow agent from Telegram, with live thinking and tool events streamed into the chat
Telegram

Talk to your agents from Telegram

Objective: use a Telegram bot as a first-class client for the shared agent runtime, with the same durable conversations, agents, and tools as web chat and PawCode.

  1. Create a bot with @BotFather and copy the bot token.
  2. Store the token as a secret, then add a telegramBot service that references it. Set allowed_users to the Telegram user IDs you trust.
  3. Deploy the Telegram agent flow: telegramReceiver ingests messages and telegramAgentClient submits them through the shared agent API. Add telegramConversationBridge to mirror live conversation events back to the chat.
  4. Link your Telegram account to a PawFlow user from account settings, so messages run under your identity, scope, and permissions.
  5. Message the bot: text, documents, photos, and voice are accepted. Use /new to start a conversation, /conv to switch, /tts for spoken replies, and /help for commands; slash commands mirror into the conversation.

Expected result: the same agents, multi-agent context, attachments, and FileStore outputs are available from Telegram, with responses streamed back to the chat.

Read multi-client docs

Security, context, and gateway

Keep access narrow and context intentional.

Context

Edit context and memory before the next turn

Objective: keep long-running conversations precise instead of letting stale state accumulate.

  1. Open the context editor to inspect what the selected agent will receive.
  2. Remove stale snippets or add focused context before a sensitive task.
  3. Open the memory editor to review durable memories and correct bad facts.
  4. Send the next turn only after the visible context matches the task.

Expected result: the agent runs with auditable short-term context and curated long-term memory.

Read cognitive tools docs
Context

Configure compact and summarizer settings

Objective: control how long conversations stay usable without flooding the provider context.

  1. Set `max_context_size` on the LLM service to match the real model window.
  2. Choose a summarizer service during install or in services.
  3. Use `compact_threshold_pct` for proactive compaction, or disable proactive compaction with `0` when manual control is preferred.
  4. Review compact summaries and memory extraction after long sessions.

Expected result: conversation history stays durable while provider prompts stay bounded.

Read agent context docs
Private Gateway setup and ban rules
Gateway

Configure Private Gateway and bans

Objective: protect exposed routes before a demo or internet-facing install.

  1. Enable Private Gateway during install or from gateway services.
  2. Replace the bootstrap key immediately; `RoyBetty` is only temporary.
  3. Set rate limits, failed-attempt cooldowns, and ban behavior for repeated failures.
  4. Use skins only as UX; do not treat them as security controls.

Expected result: public routes require an explicit gateway step and abusive clients can be slowed or banned.

Read security model
Security

Run a private demo safely

Objective: show PawFlow without exposing unrestricted host access.

  1. Use HTTPS or a trusted reverse proxy.
  2. Enable Private Gateway for internet-facing routes.
  3. Prefer Docker relay mode for untrusted workloads.
  4. Restrict agent tools and require approval for shell/edit/delete/desktop operations.

Expected result: a useful demo with explicit trust boundaries.

Read security model

Media and voice

Add multimodal services after the core runtime works.

PawFlow media service setup
Media

Add image, video, and audio services

Objective: enable multimodal tools without embedding large media payloads in context.

  1. Add the provider you need: image, video, audio/music, 3D, lipsync, upscaling, or speech-to-video.
  2. Store API keys as secrets or choose a local provider.
  3. Use clear service ids such as `image.default`, `video.default`, or `audio.default`.
  4. Run a tiny generation test and confirm the output is a FileStore URL or relay file path.

Expected result: agents return reusable files instead of base64 blobs.

Read media docs
TTS and STT service setup in PawFlow
Voice

Set up TTS and STT

Objective: enable read-aloud, browser dictation, voice cloning, and speech tools.

  1. Add a TTS service such as `supertonicTTS`, `voicebox`, `luxTTS`, or a compatible hosted provider.
  2. Add an STT service such as `openaiCompatibleSTT` or `voicebox`.
  3. For Supertonic, use fast private local TTS; for Voicebox, configure the local endpoint/profile.
  4. Test the speaker and microphone buttons, then test `speak`, `clone_voice`, or `speech_to_video` if needed.

Expected result: webchat can speak and transcribe, and agents can generate voice artifacts.

Read voice docs
Troubleshooting

Debug the first blocked install

Objective: isolate common setup failures without guessing.

  1. Run the doctor script first.
  2. Check Docker daemon access and selected port availability.
  3. Confirm provider credentials are stored as secrets or login-backed services.
  4. Check relay connection state before testing filesystem tools.

Expected result: the failing layer is visible: host prerequisites, server, provider, or relay.

Read Docker docs