Small recipes for the first useful PawFlow sessions.

Choose the tool that owns the job

Objective: keep agents from treating similar-looking tools as interchangeable. PawFlow gives each kind of context, delegation, orchestration, and waiting a distinct owner.

PawFlow injects a compact selection map containing only tools available to the active agent. The agent can then call get_tool_schema(family="delegation") for an on-demand comparison and get_tool_schema(tool_name="delegate") for exact parameters. The full technical decision map also covers search/read/edit tools, artifacts, notifications, resources, packages, skills, tasks, and flows.

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.

Loading current release command...

PawFlow runs on the selected port, the wizard is complete, and the first conversation can call your chosen provider.

Install a published PawFlow conversation as a local MCP server

Objective: bind one Claude Code, Codex, Agy/Gemini, OpenCode, JCode, Pi, Hermes, or generic MCP client instance to exactly one PawFlow conversation and agent, while allowing other agents in that conversation to have independent MCP publications.

Download ZIP Download tar.gz

1. Open the target conversation, then Resources → MCP Repository → Publish/configure this conversation.
2. Select the attached agent, create an API key, and copy the endpoint and key immediately. Repeat with another attached agent when it needs its own publication.
3. Extract the client archive and run the installer for the current OS.
4. Enter a unique session name, endpoint, hidden API key, optional hidden gateway key, local project directory, and a comma-separated client subset from cc, codex, agy, opencode, jcode, pi, and hermes.
5. Choose read-only or read/write access and whether shell execution is allowed. The secure default leaves shell execution disabled.
6. Start the client with the session-bound command printed by the installer, confirm the MCP server is listed, then call pawflow_relay_status. It must report auto_default: false.

For any other MCP-compatible stdio client, use the generated mcp.json or entry.json in a dedicated client profile. Never merge it into a shared global profile: one local process must load one PawFlow session bundle.

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.

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.

You watch the same desktop surface the agent sees, while agent actions stay routed through auditable screen/see/tool calls.

Give GLM 5.2 vision and desktop awareness through Gemma 4 Cloud

Objective: keep GLM 5.2 as the reasoning and tool-using model while a separate Gemma 4 Cloud service describes uploads, screenshots, and visual tool results.

1. Create an OpenAI-compatible llmConnection named ollama_gemma4_vision. Use https://ollama.com/v1, model gemma4:cloud, and leave supports_vision enabled.
2. Create the primary service ollama_glm52 with model glm-5.2:cloud.
3. Disable supports_vision on the GLM service. The vision_llm_service picker appears; select ollama_gemma4_vision.
4. Select ollama_glm52 as the agent's llm_service. No special agent prompt is required.
5. Attach an image or ask the agent to inspect the desktop with screen, see, or an image read. The server log should report that the image was described through the delegated service.
6. For coordinate-based desktop work, capture a fresh screen before a sensitive click and verify the state after the action.

{
  "type": "llmConnection",
  "provider": "openai",
  "api_key": "${OLLAMA_API_KEY}",
  "base_url": "https://ollama.com/v1",
  "default_model": "gemma4:cloud",
  "supports_vision": true
}

{
  "type": "llmConnection",
  "provider": "openai",
  "api_key": "${OLLAMA_API_KEY}",
  "base_url": "https://ollama.com/v1",
  "default_model": "glm-5.2:cloud",
  "supports_vision": false,
  "vision_llm_service": "ollama_gemma4_vision"
}

In practice: only the first view of a screen pays the description round-trip (a few seconds, comparable to a native vision turn); byte-identical repeats are served from the hash cache instantly. Click coordinates come from the vision model's description — the text model only selects the target and copies them — which is why a text-only GLM 5.2 clicks accurately in real desktop sessions.

PawFlow transforms only the outbound call: the conversation keeps the original image, while GLM receives a cached textual description. Treat visual text as untrusted input and keep normal tool approvals enabled. Screen captures also return a revision for guarded clicks: the relay compares the target region locally immediately before input, with no second vision request or image-token charge when the screen is unchanged. Only the small opaque revision travels in the normal tool exchange. A changed region cancels the click and requires a fresh screenshot.

Combine several LLM advisors behind one final agent

Objective: ask complementary LLMs for detailed internal plans in parallel, then let one final LLM synthesize their findings and complete the user's request.

1. Create at least two enabled llmConnection services: one or more advisors and a different final LLM.
2. In Resources → Services, create an LLM Aggregator Service.
3. Select the final connection in aggregator_llm_service and enter the advisor service IDs in advisor_llm_services.
4. Keep enforce_read_only enabled. Choose best_effort when partial advice is useful or fail_fast when every advisor is mandatory.
5. Set max_parallel_advisors to the concurrency your providers can sustain, then select the aggregator as the agent or conversation LLM service.
6. Send a planning or implementation request. PawFlow runs advisors only once for that user turn, reuses their reports through later tool results, and shows only the final LLM's stream.

{
  "type": "llmAggregator",
  "aggregator_llm_service": "llm_final",
  "advisor_llm_services": [
    "llm_architect",
    "llm_reviewer"
  ],
  "max_parallel_advisors": 2,
  "advisor_max_iterations": 20,
  "failure_policy": "best_effort",
  "enforce_read_only": true
}

The final connection cannot also be an advisor, and every reference must target a direct llmConnection. Advisor calls add provider usage but are tracked separately from the final turn and do not inflate the main context gauge. Disable read-only enforcement only when you explicitly trust every advisor with all conversation tools.

Route each agent turn across LLM providers safely

Objective: select a direct LLM connection once per turn, retain it through tool iterations, and cold-handoff safely after a classified provider failure.

1. Create and test at least two enabled direct llmConnection services.
2. In Resources → Services, create an Adaptive LLM Router.
3. Add candidates with the structured editor, set priority and enabled state, then choose a strategy.
4. Select the new llmRouter as the agent or conversation LLM service.
5. Use Health and Explain last decision for sanitized diagnostics.
6. Test with one provider unavailable; persisted work remains in the cold-started child context.

{
  "type": "llmRouter",
  "strategy": "ordered",
  "candidates": [
    {"service_id": "llm_primary", "priority": 10, "enabled": true},
    {"service_id": "llm_backup", "priority": 20, "enabled": true}
  ]
}

If PawFlow cannot confirm that queued conversation writes are durable, it stops instead of handing an incomplete context to the next provider. Health and decision details are bounded and secret-free.

Install PawCode and attach a terminal agent to PawFlow

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

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.

Terminal work and webchat share the same PawFlow conversation.

Start PawCode with explicit server and Private Gateway settings

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

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

PawCode connects to the chosen server, passes Private Gateway, and uses the same relay and tool permissions as webchat.

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.

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.

VS Code is another PawFlow client over the same backend.

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.

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.

Webchat can link the workstation relay and use Desktop Relay/noVNC for GUI tasks.

Install Relay CLI for server and terminal workspaces

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

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.

The machine appears as a relay-backed filesystem and shell target, no desktop session required.

Connect ComfyUI to PawFlow

Objective: let agents run reviewed ComfyUI graphs without exposing arbitrary workflows or loading large outputs into server memory.

1. Install ComfyUI from its official manual/desktop instructions, install the required models and custom nodes, then verify http://127.0.0.1:8188/system_stats. ComfyUI has no official Docker image; community images remain operator-managed.
2. Run and test each graph in ComfyUI. End it in an artifact-producing save/combine node, then use File → Export Workflow (API), not the ordinary Save JSON.
3. In PawFlow Resources → Services, add comfyUIImageGeneration or comfyUIVideoGeneration.
4. For ComfyUI on the relay host, keep base_url=relay://${conv.relay}/localhost:8188 and relay_local=true. Set relay_local=false only when ComfyUI runs in the relay container.
5. Paste trusted presets in workflows. Each operation contains the complete API workflow, explicit bindings such as prompt -> 6.text, and an explicit output such as node 9, key images, index 0.
6. Configure only the operations the graph supports: generate/edit_image for images; generate, image_to_video, frame_to_video, reference_to_video, video_edit, or video_extend for video.
7. Generate a small artifact, confirm a FileStore/relay-file result, then tune time and byte limits. Keep port 8188 private or place authenticated TLS in front of it.

PawFlow uploads declared inputs, submits only the configured graph, polls prompt history, and streams the selected artifact to disk.