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.

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.

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 screen Open `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 screen Create the first admin account. This user owns the initial runtime resources and can configure global agents/services.
LLM provider screen Select the first provider: Codex app-server, Claude Code interactive, Antigravity/Agy, Gemini CLI, Anthropic, OpenAI, or an OpenAI-compatible endpoint.
Summarizer screen Choose the summarizer service and context limits so compaction is explicit and does not flood provider context.
Runtime screen Deploy the main PawFlow Agent flow: `httpReceiver` to `agentLoop` to `handleHTTPResponse`.
Conversation screen Open the starter conversation, confirm `assistant` is selected, send a small prompt, and verify streaming output.
Gateway and bootstrap key.
Admin account.
LLM service.
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 (VNC): noVNC opens the relay desktop in the browser.
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.

Download the platform package, install it, then connect to the PawFlow server.
Video: install, login, select conversation, stream a response.
Linux zip Windows zip Debian package PawCode docs Commands, 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.

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 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.

Install the release `.vsix`, configure the server URL, then login.
Video: install from VSIX, settings, login, chat sidebar, selection actions.
The PawFlow panel in VS Code: chat, conversations, files, tools, and live streaming over the same backend.
VS Code VSIX Extension docs Settings, gateway key, commands, and local VSIX build.Developer README Development host, compile command, and package command.Terminal alternative Use 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.

Install the desktop app, create a PawFlow server profile, then register a workspace.
Video: installer, profile, workspace, connected relay.
Linux AppImage Debian package Windows zip Windows setup Relay Desktop docs Profiles, 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.

Unpack the CLI, authenticate, and connect a workspace directory.
Video: CLI install, profile/login, relay connected in webchat.
Linux zip Linux tarball Windows zip Relay CLI docs Headless 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
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
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

## 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
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
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

## 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.

Google Google Cloud Console OAuth client, authorized redirect URI, email/profile scopes.
GitHub GitHub OAuth App, callback URL, optional org restrictions.
Microsoft Entra app registration, web redirect URI, user.read/email scopes.
X X/Twitter developer app, OAuth callback, profile/email permissions when available.
Meta/Facebook Meta app, Facebook Login product, valid OAuth redirect URI.
Amazon Login with Amazon security profile, allowed return URL.
Telegram BotFather bot plus allowed domain for Telegram login widget.
Generic Any OIDC/OAuth provider with authorize, token, userinfo endpoints.

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

Read auth docs
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
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.

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
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
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.

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
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.

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
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