diff --git a/packages/website/src/routeTree.gen.ts b/packages/website/src/routeTree.gen.ts index aa618795d..bb184b656 100644 --- a/packages/website/src/routeTree.gen.ts +++ b/packages/website/src/routeTree.gen.ts @@ -25,6 +25,7 @@ import { Route as DocsVoiceRouteImport } from "./routes/docs/voice"; import { Route as DocsUpdatesRouteImport } from "./routes/docs/updates"; import { Route as DocsSkillsRouteImport } from "./routes/docs/skills"; import { Route as DocsSecurityRouteImport } from "./routes/docs/security"; +import { Route as DocsProvidersRouteImport } from "./routes/docs/providers"; import { Route as DocsConfigurationRouteImport } from "./routes/docs/configuration"; import { Route as DocsCliRouteImport } from "./routes/docs/cli"; import { Route as DocsBestPracticesRouteImport } from "./routes/docs/best-practices"; @@ -110,6 +111,11 @@ const DocsSecurityRoute = DocsSecurityRouteImport.update({ path: "/security", getParentRoute: () => DocsRoute, } as any); +const DocsProvidersRoute = DocsProvidersRouteImport.update({ + id: "/providers", + path: "/providers", + getParentRoute: () => DocsRoute, +} as any); const DocsConfigurationRoute = DocsConfigurationRouteImport.update({ id: "/configuration", path: "/configuration", @@ -145,6 +151,7 @@ export interface FileRoutesByFullPath { "/docs/best-practices": typeof DocsBestPracticesRoute; "/docs/cli": typeof DocsCliRoute; "/docs/configuration": typeof DocsConfigurationRoute; + "/docs/providers": typeof DocsProvidersRoute; "/docs/security": typeof DocsSecurityRoute; "/docs/skills": typeof DocsSkillsRoute; "/docs/updates": typeof DocsUpdatesRoute; @@ -165,6 +172,7 @@ export interface FileRoutesByTo { "/docs/best-practices": typeof DocsBestPracticesRoute; "/docs/cli": typeof DocsCliRoute; "/docs/configuration": typeof DocsConfigurationRoute; + "/docs/providers": typeof DocsProvidersRoute; "/docs/security": typeof DocsSecurityRoute; "/docs/skills": typeof DocsSkillsRoute; "/docs/updates": typeof DocsUpdatesRoute; @@ -188,6 +196,7 @@ export interface FileRoutesById { "/docs/best-practices": typeof DocsBestPracticesRoute; "/docs/cli": typeof DocsCliRoute; "/docs/configuration": typeof DocsConfigurationRoute; + "/docs/providers": typeof DocsProvidersRoute; "/docs/security": typeof DocsSecurityRoute; "/docs/skills": typeof DocsSkillsRoute; "/docs/updates": typeof DocsUpdatesRoute; @@ -212,6 +221,7 @@ export interface FileRouteTypes { | "/docs/best-practices" | "/docs/cli" | "/docs/configuration" + | "/docs/providers" | "/docs/security" | "/docs/skills" | "/docs/updates" @@ -232,6 +242,7 @@ export interface FileRouteTypes { | "/docs/best-practices" | "/docs/cli" | "/docs/configuration" + | "/docs/providers" | "/docs/security" | "/docs/skills" | "/docs/updates" @@ -254,6 +265,7 @@ export interface FileRouteTypes { | "/docs/best-practices" | "/docs/cli" | "/docs/configuration" + | "/docs/providers" | "/docs/security" | "/docs/skills" | "/docs/updates" @@ -389,6 +401,13 @@ declare module "@tanstack/react-router" { preLoaderRoute: typeof DocsSecurityRouteImport; parentRoute: typeof DocsRoute; }; + "/docs/providers": { + id: "/docs/providers"; + path: "/providers"; + fullPath: "/docs/providers"; + preLoaderRoute: typeof DocsProvidersRouteImport; + parentRoute: typeof DocsRoute; + }; "/docs/configuration": { id: "/docs/configuration"; path: "/configuration"; @@ -436,6 +455,7 @@ interface DocsRouteChildren { DocsBestPracticesRoute: typeof DocsBestPracticesRoute; DocsCliRoute: typeof DocsCliRoute; DocsConfigurationRoute: typeof DocsConfigurationRoute; + DocsProvidersRoute: typeof DocsProvidersRoute; DocsSecurityRoute: typeof DocsSecurityRoute; DocsSkillsRoute: typeof DocsSkillsRoute; DocsUpdatesRoute: typeof DocsUpdatesRoute; @@ -448,6 +468,7 @@ const DocsRouteChildren: DocsRouteChildren = { DocsBestPracticesRoute: DocsBestPracticesRoute, DocsCliRoute: DocsCliRoute, DocsConfigurationRoute: DocsConfigurationRoute, + DocsProvidersRoute: DocsProvidersRoute, DocsSecurityRoute: DocsSecurityRoute, DocsSkillsRoute: DocsSkillsRoute, DocsUpdatesRoute: DocsUpdatesRoute, diff --git a/packages/website/src/routes/docs.tsx b/packages/website/src/routes/docs.tsx index af0407e1d..f18924820 100644 --- a/packages/website/src/routes/docs.tsx +++ b/packages/website/src/routes/docs.tsx @@ -12,6 +12,7 @@ const navigation = [ { name: "Git worktrees", href: "/docs/worktrees" }, { name: "CLI", href: "/docs/cli" }, { name: "Skills", href: "/docs/skills" }, + { name: "Providers", href: "/docs/providers" }, { name: "Configuration", href: "/docs/configuration" }, { name: "Security", href: "/docs/security" }, { name: "Best practices", href: "/docs/best-practices" }, diff --git a/packages/website/src/routes/docs/configuration.tsx b/packages/website/src/routes/docs/configuration.tsx index 368ae6157..69fcd132b 100644 --- a/packages/website/src/routes/docs/configuration.tsx +++ b/packages/website/src/routes/docs/configuration.tsx @@ -11,6 +11,8 @@ export const Route = createFileRoute("/docs/configuration")({ component: Configuration, }); +const CUSTOM_PROVIDERS_URL = "https://github.com/getpaseo/paseo/blob/main/docs/CUSTOM-PROVIDERS.md"; + function Configuration() { return (
@@ -59,15 +61,12 @@ function Configuration() {

Example

- Minimal example that configures listening address, hostnames, provider keys, and MCP: + Minimal example that configures listening address, hostnames, and MCP: 

           {`{
   "$schema": "https://paseo.sh/schemas/paseo.config.v1.json",
   "version": 1,
-  "providers": {
-    "openai": { "apiKey": "..." }
-  },
   "daemon": {
     "listen": "127.0.0.1:6767",
     "hostnames": ["localhost", ".localhost"],
@@ -83,84 +82,31 @@ function Configuration() {
-

Agent provider runtime settings

+

Agent providers

- Use agents.providers to customize how Paseo launches - agent provider CLIs. This works for claude,{" "} - codex, and - opencode. + Agent providers — both the first-class ones Paseo ships with and custom entries you add + under agents.providers — are documented on their own + page.

- command.mode can be{" "} - default, append, or{" "} - replace. Use env to - inject provider-specific environment variables. + See{" "} + + Providers + {" "} + for first-class providers, how to point Claude at Anthropic-compatible endpoints (Z.AI, + Alibaba/Qwen), multiple profiles, custom binaries, ACP agents, and the{" "} + additionalModels merge behavior. The full field + reference lives on GitHub at{" "} + + docs/CUSTOM-PROVIDERS.md + + .

- -

Enable Claude Code Chrome MCP

- 
-          {`{
-  "agents": {
-    "providers": {
-      "claude": {
-        "command": {
-          "mode": "append",
-          "args": ["--chrome"]
-        }
-      }
-    }
-  }
-}`}
-
- -

- Point Claude to Anthropic-compatible endpoints (z.ai example) -

- 
-          {`{
-  "agents": {
-    "providers": {
-      "claude": {
-        "env": {
-          "ANTHROPIC_BASE_URL": "https://api.z.ai/api/anthropic",
-          "ANTHROPIC_AUTH_TOKEN": "auth token",
-          "ANTHROPIC_API_KEY": ""
-        }
-      }
-    }
-  }
-}`}
-
- -

Run Claude through Docker

-

- Create a wrapper script that runs Claude in Docker, then tell Paseo to replace the Claude - launch command with that script. -

- 
-          {`{
-  "agents": {
-    "providers": {
-      "claude": {
-        "command": {
-          "mode": "replace",
-          "argv": ["/Users/you/bin/claude-docker"]
-        }
-      }
-    }
-  }
-}`}
-
- 
-          {`#!/usr/bin/env bash
-set -euo pipefail
-docker run --rm -i \\
-  -v "$PWD":"$PWD" \\
-  -w "$PWD" \\
-  -v "$HOME/.claude":"$HOME/.claude" \\
-  ghcr.io/anthropics/claude-code:latest \\
-  claude "$@"`}
-
diff --git a/packages/website/src/routes/docs/index.tsx b/packages/website/src/routes/docs/index.tsx index ceacc4a99..d614ce84c 100644 --- a/packages/website/src/routes/docs/index.tsx +++ b/packages/website/src/routes/docs/index.tsx @@ -148,6 +148,11 @@ function GettingStarted() { Voice +
  • + + Providers + +
  • Configuration diff --git a/packages/website/src/routes/docs/providers.tsx b/packages/website/src/routes/docs/providers.tsx new file mode 100644 index 000000000..eb160d3b0 --- /dev/null +++ b/packages/website/src/routes/docs/providers.tsx @@ -0,0 +1,345 @@ +import { createFileRoute } from "@tanstack/react-router"; +import { pageMeta } from "~/meta"; + +export const Route = createFileRoute("/docs/providers")({ + head: () => ({ + meta: pageMeta( + "Providers - Paseo Docs", + "First-class agent providers in Paseo, and how to configure custom providers, ACP agents, and profiles.", + ), + }), + component: Providers, +}); + +const CUSTOM_PROVIDERS_URL = "https://github.com/getpaseo/paseo/blob/main/docs/CUSTOM-PROVIDERS.md"; + +function Providers() { + return ( +
    +
    +

    Providers

    +

    + A provider is an agent CLI that Paseo knows how to launch, stream, and control. Paseo + ships with first-class providers for the major coding agents, and lets you add your own + through config.json — either by pointing an existing + provider at a different API, adding extra profiles, or plugging in any{" "} + + ACP + + -compatible agent. +

    +
    + +
    +

    First-class providers

    +

    + These work out of the box once the underlying CLI is installed and authenticated. Paseo + discovers them automatically, wires up modes, and exposes them in the app and CLI. +

    +
      +
    • + claude — Anthropic's Claude Code. Multi-tool + assistant with MCP support, streaming, and deep reasoning. +
      • +
    • + codex — OpenAI's Codex workspace agent with sandbox + controls and optional network access. +
      • +
    • + opencode — Open-source coding assistant with + multi-provider model support. +
      • +
    • + copilot — GitHub Copilot via ACP, with dynamic modes + and session support. +
      • +
    • + pi — Minimal terminal-based coding agent with + multi-provider LLM support. +
      • +
    +
    + +
    +

    Custom providers

    +

    + Everything beyond the defaults lives under{" "} + agents.providers in{" "} + ~/.paseo/config.json. You can: +

    +
      +
    • + Extend a first-class provider to point at a different API (Z.AI, + Alibaba/Qwen, a proxy, a self-hosted endpoint). +
      • +
    • + Add profiles — multiple entries against the same underlying provider + with different credentials or curated model lists. +
      • +
    • + Override the binary — run a nightly build, a wrapper script, or a + Docker image instead of the installed CLI. +
      • +
    • + Add ACP agents — Gemini CLI, Hermes, or any agent speaking the Agent + Client Protocol over stdio. +
      • +
    • + Disable a provider you don't use. +
      • +
    +

    + Provider IDs must be lowercase alphanumeric with hyphens ( + /^[a-z][a-z0-9-]*$/). Every custom entry needs{" "} + extends (a first-class provider ID or{" "} + "acp") and a label. +

    +

    + The examples below are a quick tour. The full, up-to-date reference is on GitHub:{" "} + + docs/CUSTOM-PROVIDERS.md + + . +

    +
    + +
    +

    Extending a first-class provider

    + 
    +          {`{
+  "agents": {
+    "providers": {
+      "my-claude": {
+        "extends": "claude",
+        "label": "My Claude",
+        "env": {
+          "ANTHROPIC_API_KEY": "sk-ant-...",
+          "ANTHROPIC_BASE_URL": "https://my-proxy.example.com/v1"
+        }
+      }
+    }
+  }
+}`}
+
    +
    + +
    +

    Z.AI (GLM) coding plan

    +

    + Z.AI exposes GLM models through an Anthropic-compatible endpoint. Point{" "} + ANTHROPIC_BASE_URL at their API and use{" "} + ANTHROPIC_AUTH_TOKEN for the key. Third-party endpoints + don't support Anthropic's server-side tools, so disable{" "} + WebSearch. +

    + 
    +          {`{
+  "agents": {
+    "providers": {
+      "zai": {
+        "extends": "claude",
+        "label": "ZAI",
+        "env": {
+          "ANTHROPIC_AUTH_TOKEN": "",
+          "ANTHROPIC_BASE_URL": "https://api.z.ai/api/anthropic",
+          "API_TIMEOUT_MS": "3000000"
+        },
+        "disallowedTools": ["WebSearch"],
+        "models": [
+          { "id": "glm-5-turbo", "label": "GLM 5 Turbo", "isDefault": true },
+          { "id": "glm-5.1", "label": "GLM 5.1" }
+        ]
+      }
+    }
+  }
+}`}
+
    +
    + +
    +

    Alibaba Cloud (Qwen) coding plan

    +

    + Alibaba's coding plan routes Claude Code to Qwen models via an Anthropic-compatible API. + Subscription keys look like sk-sp-... and must be + created in the Singapore region. +

    + 
    +          {`{
+  "agents": {
+    "providers": {
+      "qwen": {
+        "extends": "claude",
+        "label": "Qwen (Alibaba)",
+        "env": {
+          "ANTHROPIC_AUTH_TOKEN": "sk-sp-",
+          "ANTHROPIC_BASE_URL": "https://coding-intl.dashscope.aliyuncs.com/apps/anthropic"
+        },
+        "disallowedTools": ["WebSearch"],
+        "models": [
+          { "id": "qwen3.5-plus", "label": "Qwen 3.5 Plus", "isDefault": true },
+          { "id": "qwen3-coder-next", "label": "Qwen 3 Coder Next" }
+        ]
+      }
+    }
+  }
+}`}
+
    +
    + +
    +

    Multiple profiles

    +

    + Create as many entries as you want against the same first-class provider. Each one shows + up as a separate option in the app with its own credentials and models. +

    + 
    +          {`{
+  "agents": {
+    "providers": {
+      "claude-work": {
+        "extends": "claude",
+        "label": "Claude (Work)",
+        "env": { "ANTHROPIC_API_KEY": "sk-ant-work-..." }
+      },
+      "claude-personal": {
+        "extends": "claude",
+        "label": "Claude (Personal)",
+        "env": { "ANTHROPIC_API_KEY": "sk-ant-personal-..." }
+      }
+    }
+  }
+}`}
+
    +
    + +
    +

    Custom binary

    +

    + command is an array — first element is the binary, the + rest are arguments. It fully replaces the default launch command for that provider. +

    + 
    +          {`{
+  "agents": {
+    "providers": {
+      "claude": {
+        "command": ["/opt/claude-nightly/claude"]
+      }
+    }
+  }
+}`}
+
    +
    + +
    +

    ACP providers

    +

    + Any agent that speaks{" "} + + ACP + {" "} + over stdio can be added with extends: "acp" and a{" "} + command. Paseo spawns the process, sends an{" "} + initialize JSON-RPC request, and the agent reports its + capabilities, modes, and models at runtime. +

    + 
    +          {`{
+  "agents": {
+    "providers": {
+      "gemini": {
+        "extends": "acp",
+        "label": "Google Gemini",
+        "command": ["gemini", "--acp"]
+      },
+      "hermes": {
+        "extends": "acp",
+        "label": "Hermes",
+        "command": ["hermes", "acp"]
+      }
+    }
+  }
+}`}
+
    +
    + +
    +

    Adding or relabeling models

    +

    + models replaces the model list entirely.{" "} + additionalModels merges with runtime-discovered models + (ACP) or with models — use it to add an extra entry or + relabel a discovered one without redeclaring the full list. An entry with the same{" "} + id as a discovered model updates it in place. +

    + 
    +          {`{
+  "agents": {
+    "providers": {
+      "gemini": {
+        "extends": "acp",
+        "label": "Google Gemini",
+        "command": ["gemini", "--acp"],
+        "additionalModels": [
+          { "id": "experimental-model", "label": "Experimental", "isDefault": true },
+          { "id": "gemini-2.5-pro", "label": "Gemini 2.5 Pro (preferred)" }
+        ]
+      }
+    }
+  }
+}`}
+
    +
    + +
    +

    Disabling a provider

    + 
    +          {`{
+  "agents": {
+    "providers": {
+      "copilot": { "enabled": false }
+    }
+  }
+}`}
+
    +
    + +
    +

    Full reference

    +

    + For the complete field reference (extends,{" "} + label, command,{" "} + env, models,{" "} + additionalModels,{" "} + disallowedTools,{" "} + enabled, order), + model and thinking-option schemas, and deeper examples for each plan, see{" "} + + docs/CUSTOM-PROVIDERS.md + {" "} + on GitHub. +

    +
    +
    + ); +} diff --git a/packages/website/vite.config.ts b/packages/website/vite.config.ts index 2816797e2..354531366 100644 --- a/packages/website/vite.config.ts +++ b/packages/website/vite.config.ts @@ -20,6 +20,7 @@ const sitemapPages = [ "/docs/best-practices", "/docs/cli", "/docs/configuration", + "/docs/providers", "/docs/skills", "/docs/security", "/docs/updates",