Pi Runtime Template

If you want to run Pi-based agents in Salambo, the reference starting point is the Salambo Sandbox Pi SDK template. This template preserves the Salambo platform contract while letting you customize the Pi harness itself.

What The Template Is For

Use the Pi runtime template when you want:

• a pi runtime snapshot instead of a codex runtime snapshot
• Pi-specific prompts, skills, extensions, or themes
• a customizable sandbox template that still behaves like a Salambo runtime from the platform's point of view

If you do not need Pi-specific behavior, a standard runtime template is usually simpler.

What Must Stay Stable

The template keeps these HTTP surfaces compatible:

• GET /health
• POST /agent/query
• POST /agent/interrupt
• GET /agent/status
• GET /agent/events/:sandboxId
• POST /workspace/files/sync
• POST /workspace/files/import
• DELETE /workspace/sandbox/:sandboxId

It also keeps the expected workspace layout:

• /workspace/work
• /workspace/outputs

And it preserves the main event families:

• sandbox.run.init
• sandbox.run.ready
• sandbox.run.complete
• sandbox.run.cancelled
• sandbox.run.error
• session.event

What You Can Customize Safely

The Pi template is meant to be customized in the harness layer. Key areas include:

• harness-config/pi-agent-home/settings.json
• harness-config/pi-agent-home/SYSTEM.md
• harness-config/pi-agent-home/extensions/
• harness-config/pi-agent-home/skills/
• harness-config/pi-agent-home/prompts/
• harness-config/pi-agent-home/themes/
• harness-config/initial-workspace/.pi/

This is where you adapt prompts, settings, extensions, and local project overrides without breaking the app-level contract Salambo expects.

Operational Notes

The template is designed around the Pi runtime profile and includes support for:

• Pi session persistence and resume behavior
• managed proxy and CA wiring
• auth seeding for local and Docker startup
• stable workspace sync and import endpoints

In practice, this means you can customize Pi behavior while still using Salambo's snapshot, agent, and run-management flows.

How To Use It In Salambo

1. Customize the Pi template in your own repo or image pipeline.
2. Build and publish the Docker image.
3. Create a new snapshot in Salambo with runtime type pi.
4. Assign that snapshot to the agent that should use the Pi runtime.
5. Test with a small run before moving production traffic.

When This Page Matters Most

This page is mainly for technical operators, platform owners, and teams maintaining custom runtime templates. If your team only consumes existing snapshots, you can skip this page and focus on normal agent and snapshot operations.