Pi runtime

Pi is an optional runtime for the built-in Providers and custom providers configured in your Project. Select Pi in an Agent preset or use harness: "pi" in a v2 API request. Adding a Provider does not switch existing Agents or Sessions to Pi; OpenCode remains the default when the Project has only a custom provider.

Configure a model

1. In the active Project, open Config → Providers. Add a key for a built-in Provider, or choose Add custom provider.
2. For a custom provider, save the API key, HTTPS base URL, exact model IDs, and Model protocol implemented by that endpoint: OpenAI Chat Completions, OpenAI Responses, Anthropic Messages, or Google Gemini.
3. In the Agent editor, select Pi, then select a compatible model from the Project. Built-in models use their catalog protocol; custom models use the credential's selected protocol.
4. Send a representative task that uses a tool, then check its answer and output files. A successful optional Provider connection test alone does not verify a full Pi Run.

Pi uses the selected model protocol directly, including streaming and tool calls. A provider name or an OpenAI-compatible label does not establish which protocol an endpoint implements. An endpoint that implements only Responses can be used by selecting OpenAI Responses. See the protocol and runtime matrix.

This covers Mosoo's Project API-key credentials. It does not expose all authentication methods available in standalone Pi, such as subscription OAuth, Bedrock, or Vertex ambient credentials.

Create a Session with the API or CLI

Follow the v2 quickstart to configure the target, Project ID and Project API key. Save this request as pi-session.json, replacing YOUR_CUSTOM_MODEL_ID with the exact model ID configured above:

This example uses a custom provider. For a built-in provider, replace provider and model with its catalog IDs while keeping harness: "pi". The protocol belongs to the provider credential or model catalog, not the Session request.

{
  "configuration": {
    "type": "inline",
    "harness": "pi",
    "provider": "openai-compatible",
    "model": "YOUR_CUSTOM_MODEL_ID",
    "instructions": "Use tools to inspect the workspace and save deliverables in outputs/."
  }
}

curl -X POST "$MOSOO_API_BASE/projects/$MOSOO_PROJECT_ID/threads" \
  -H "Authorization: Bearer $MOSOO_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pi-session-1" \
  --data-binary @pi-session.json

MOSOO_API_BASE must end in /api/v2. Creation without input returns an idle Session; it does not test the model. Use the returned thread.id to send input, wait for a Run and read files. Keep the same ID for follow-up work. The Session retains the admitted Pi runtime and model.

The v2 CLI accepts the same JSON with an explicitly selected Project:

mosoo public-thread-api-v2 threads create --project-id "$MOSOO_PROJECT_ID" --file ./pi-session.json --idempotency-key pi-session-1 -o json

No provider API key belongs in this JSON. Configure it in the Project; use a Project API key or CLI login for mosoo access.

Execution and continuation

• Pi accepts text input. Uploaded files remain available in the Session workspace; this does not enable direct image, audio or video model input.
• Pi uses full-access execution inside the Session. Per-tool restrictions and interactive approval policies are not supported and are rejected. Choose an Environment with the required network policy.
• Attached Skills and authorized Remote MCP connections use the existing Skills and MCP flow.
• A successful Run checkpoints workspace files and Pi's native conversation state. Continue the same Session to restore that state. Missing or mismatched native state fails explicitly; it does not silently start a new conversation.

Self-hosted operators must deploy the matched API Worker, Driver and Pi sandbox image together. This integration uses Pi CLI 0.99.2, native RPC and Driver protocol 6. Follow the deployment guide before enabling it on a target.