# Pi runtime (https://mosoo.ai/docs/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.

<Callout>
  These instructions require a deployment that includes Pi. Confirm that Pi is available on your selected target before creating a Session. Local test results alone do not establish availability on mosoo Cloud.
</Callout>

## Configure a model [#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](https://mosoo.ai/docs/providers-and-models/#model-protocols-and-runtimes).

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 [#create-a-session-with-the-api-or-cli]

Follow the [v2 quickstart](https://mosoo.ai/docs/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.

```json
{
  "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/."
  }
}
```

```bash
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](https://mosoo.ai/docs/quickstart/#create-and-continue). 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:

```bash
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 [#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](https://mosoo.ai/docs/environments/) with the required network policy.
* Attached Skills and authorized Remote MCP connections use the existing [Skills and MCP](https://mosoo.ai/docs/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](https://mosoo.ai/docs/deploy-mosoo/) before enabling it on a target.