Harnesses & models

Native Harness connections

Platform supports Codex, Claude Code, Kimi Code, ZCode and Pi with your own model API key and endpoint (BYOK). New Runs require a Session model connection; Sandpi does not supply a shared model key or sell model Tokens. Model charges go to your provider or gateway, while Sandpi bills Sandbox runtime.

Sandpi runs the native Harness and keeps its conversation history. Model requests go directly from the Sandbox to your endpoint, without protocol translation in Sandpi. Choose the Harness by the API your endpoint implements, not just the model name or provider branding.

Codex uses OpenAI Responses. A gateway that only exposes Chat Completions cannot serve Codex. Claude Code requires Anthropic Messages. An “OpenAI-compatible” label alone does not establish which API a gateway supports.

Pi is an independent Harness. Its upstream project supports more adapters, including Google, Azure and Bedrock, and an optional pi-messages protocol. Platform exposes the three key-based native APIs above; it does not translate other protocols into them. Custom Pi models can specify contextWindow (default 128000) and maxOutputTokens (default 16384).

Endpoint addresses

Enter the API base URL, including the gateway's required path prefix. Do not enter the complete inference URL ending in /responses, /messages or /chat/completions; the native client adds that operation path.

The following are illustrative gateway addresses, not a domain allowlist. Official provider endpoints and custom gateways are accepted when they implement the Harness's native API.

For example, a gateway mounted under /models/v1 needs that prefix in its base URL. The /api/paas/v4 prefix shown for ZCode is an example, not a required path for every gateway. Use the prefix documented by your gateway for the selected API.

API format compatibility

These are the model provider's wire formats, separate from Sandpi's Session and Run API. The native Harness builds the model request and interprets the response.

A working text-only request is not sufficient proof of Harness compatibility. Your gateway must also support the native client's streaming responses, tool calls and tool results, authentication headers, and any additional operations or extensions the installed Harness uses. Sandpi does not convert between these formats or emulate missing gateway features.

Configure and rotate

Set connection.baseUrl and connection.apiKey when creating a Session. Pi also requires connection.api; other Harnesses use a fixed native protocol and reject that setting. Optional headers are passed to the native Harness. API keys and header values are encrypted, never returned in Session reads. The key is accessible to the agent inside its Sandbox, as required for direct model access.

Use the Session connection update to rotate credentials.

Rotation applies to new Runs; queued and active Runs retain the encrypted connection revision captured at admission. Existing Sessions need a connection before new Runs can start. A Session keeps its Harness and history when its connection changes.

Use your gateway's native model ID in each Run. Sandpi does not enforce a managed model catalog. The deprecated GET /v1/models returns an empty list.

curl \
    "https://api.sandpi.ai/v1/models"

{
  "data": []
}

{
  "error": {
    "code": "platform_balance_insufficient",
    "message": "Top up Platform credits before submitting a Run.",
    "requestId": "req_example"
  }
}

Gateway networking

Requests originate inside the Sandbox. Configure your gateway DNS, firewall and Environment network policy accordingly. Private gateways must be reachable from that network; saving their URL does not establish private connectivity. A localhost or 127.0.0.1 address refers to the Sandbox itself, not your laptop or the Sandpi control plane.

New Environments do not carry the retired managed-model provider deny rules. Existing Environments and forks retain their saved network policy, which can still block an official endpoint. If a connection fails, inspect and update the Environment's network policy through the API or console. Saving or rotating a model connection does not change outbound permissions.

The Platform connection API validates the URL shape; it does not probe credentials, check protocol compatibility or establish a private tunnel. Successfully saving a connection does not prove that its key, model ID or gateway works. Validate the connection with a Run that exercises native tool use.