Maturity: Private preview. The API is implemented. The Pi adapter requires an operator-provisioned Sandbox template pinned by version and digest, with APPALOFT_PI_SANDBOX_TEMPLATE_ID configured.

Run an agent in a Sandbox

An Agent Runtime belongs to one ready Sandbox. Your application keeps the chat/session; Appaloft owns isolated execution, one active Run per Runtime, fresh/continue lineage, event readback, and cancellation.

Typical product stories include:

• Chat-to-App: a user asks your SaaS to create or modify an application. Your product keeps the chat and user session; Appaloft receives a bounded task and runs it in an expiring Sandbox.
• Repository maintenance: a support or engineering workflow gives a coding agent a prepared workspace, then reads Run events and the terminal outcome back into the originating ticket.
• Human-gated automation: a Run can pause on a structured approval request; your application shows the capability, destination, request digest, and expiry before resolving it.

Agent operations currently require a product session. Do not substitute a deploy token in a backend example until a scoped long-lived application credential is explicitly available.

const sandbox = await appaloft.sandboxes.create(sandboxInput);
const agent = await sandbox.agents.create({ harness: "pi" });
const run = await agent.runs.create({ task: "Build the requested app in /workspace/app" });

The SDK maps Agent to the canonical Sandbox Agent Runtime, uses the admitted Pi template default, and generates idempotency keys. Pass harnessTemplateId, context, or idempotencyKey when the caller needs an explicit pin or continuation. Resource methods throw AppaloftSdkRequestError; the non-throwing generated operations remain at appaloft.operations.

Run events have count, depth, and string bounds and recursively redact credential, secret, password, token, and authorization fields. They are not audit events or a full model transcript. Pi runs as a terminable background process in the Sandbox. Cancellation terminates that process and prevents a late success result from overwriting cancelled.

The official examples repository contains runnable, end-to-end-oriented source for Chat-to-App, human approval, and Preview-to-Promotion.