or: pip install pi-sidecar-client

CLIs after install: `pi-sidecar` (server) and `pi-sidecar-start` (dev start script).

### 2. Start the sidecar

**Production-style (default port 9100):**

```bash
npx pi-sidecar
# or: node dist/server.js

Local dev helper (default port 9201):

npx pi-sidecar-start
# foreground: npx pi-sidecar-start --foreground
# stop:       npx pi-sidecar-start --stop

Tip: Point the client at the port you actually started. Dev script uses 9201; the Node server and Python client default to 9100.

export SIDECAR_URL=http://127.0.0.1:9201   # when using pi-sidecar-start

3. Wait until healthy

curl -s http://127.0.0.1:9100/health

from pi_sidecar_client import check_sidecar_available

ok, msg = await check_sidecar_available()
print(ok, msg)

4. Discover models

from pi_sidecar_client import list_models

all_models = await list_models()
gemini = await list_models(provider="gemini")

Friendly Python provider aliases map to sidecar ids:

Refresh after changing agents or auth:

curl -X POST http://127.0.0.1:9100/models/refresh

Diagnose a single provider:

from pi_sidecar_client import get_sidecar_client

client = get_sidecar_client()
status = await client.get_model_provider_status("google")
print(status["registered"], status["modelCount"])

Note: On non-loopback binds, auth fields on provider status are redacted. Prefer 127.0.0.1 for local diagnostics. For Vertex auth setup, see Google Vertex Claude Provider.

5. Run a session

Single-shot (auto cleanup): use call_ai_once as in the Quick Example.

Multi-turn:

from pi_sidecar_client import call_ai, get_sidecar_client

result = await call_ai(
    "I'm building a REST API in Python. What framework should I use?",
    ai_provider="gemini",
    ai_model="gemini-2.5-flash",
    system_prompt="You are a senior Python developer. Be concise.",
)
session_id = result.session_id

result = await call_ai(
    "Show me a minimal example with that framework.",
    ai_provider="gemini",
    ai_model="gemini-2.5-flash",
    session_id=session_id,
)

await get_sidecar_client().delete_session(session_id)

Session lifecycle:

1. Create session (POST /sessions) with provider, model, system prompt, cwd.
2. Prompt (POST /sessions/:id/prompt) — one in-flight prompt per session.
3. Optional abort (POST /sessions/:id/abort).
4. Delete (DELETE /sessions/:id) when finished.

Default built-in tools when you omit tools: read, grep, find, ls, bash.

cwd loads project resources from {cwd}/.pi/ and AGENTS.md. Optional agent_dir points at a global agent directory (e.g. ~/.pi/agent); it is rejected on non-loopback binds unless DEV_MODE=true (then ignored).

Advanced Usage

HTTP API surface

Body size limit: 1 MiB. Concurrent prompts on the same session return conflict (busy).

Custom HTTP-backed tools

Pass custom_tools when creating a session. Entries with an http block are executed as outbound HTTP; {param} placeholders interpolate from tool args.

result = await call_ai_once(
    "Look up user 42",
    ai_provider="gemini",
    ai_model="gemini-2.5-flash",
    custom_tools=[{
        "name": "fetch_data",
        "description": "Fetch user data by ID",
        "parameters": {
            "type": "object",
            "properties": {"userId": {"type": "string"}},
        },
        "http": {
            "method": "GET",
            "url": "https://api.example.com/users/{userId}",
        },
    }],
)

Restrict the built-in tool allowlist with tools=["read", "grep"] (or [] for none).

ACPX and CLI model sources

export ACPX_AGENTS=cursor
export CLI_AGENTS=claude,gemini
npx pi-sidecar

Then use providers such as acpx-cursor / cli-claude (or Python aliases cursor / mapped names). Refresh with POST /models/refresh after changing env. See Configuration & Settings for project-level agent lists used by interactive Pi.

Watchdog (companion process)

export SIDECAR_WATCHDOG_URL=http://127.0.0.1:8000/health
npx pi-sidecar

When set, the sidecar polls that URL and shuts itself down after consecutive failures (default: 60s grace, 30s interval, 10s timeout, 6 failures).

Docker / process coupling

Start the sidecar, wait for /health, then start your app and trap cleanup — see the package entrypoint.example.sh pattern (SIDECAR_PORT default 9100).

Using vs extending

Startup lifecycle:

1. Assert Pi SDK version ≥ 0.81.1.
2. Listen on host/port.
3. Optionally start watchdog.
4. Async model discovery — /health is starting until ready.
5. Serve session/prompt routes; idle sessions cleaned after 1 hour.

Parallel calls and usage hooks

from pi_sidecar_client import run_parallel_with_limit, set_usage_recorder

set_usage_recorder(my_recorder)  # sync or async; kwargs: request_id, result, call_type, ...
results = await run_parallel_with_limit(tasks, max_concurrency=5)

ai_call_timeout on call_ai / call_ai_once is in minutes (converted to HTTP timeout seconds).

Troubleshooting

Warning: Default bind is loopback-only. Binding to 0.0.0.0 exposes an unauthenticated AI API on the network — use only behind a trusted boundary.

Related Pages

• Google Vertex Claude Provider
• ACPX Provider Integration
• External AI Agents & CLI
• Configuration & Settings
• Daemon & Websocket Networking