Small recipes for the first useful PawFlow sessions.

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.

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.

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.