Pi Runtime Template
Understand the Salambo Sandbox Pi SDK template, what stays stable, and what you can safely customize before turning it into a snapshot.
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
piruntime snapshot instead of acodexruntime 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 /healthPOST /agent/queryPOST /agent/interruptGET /agent/statusGET /agent/events/:sandboxIdPOST /workspace/files/syncPOST /workspace/files/importDELETE /workspace/sandbox/:sandboxId
It also keeps the expected workspace layout:
/workspace/work/workspace/outputs
And it preserves the main event families:
sandbox.run.initsandbox.run.readysandbox.run.completesandbox.run.cancelledsandbox.run.errorsession.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.jsonharness-config/pi-agent-home/SYSTEM.mdharness-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
- Customize the Pi template in your own repo or image pipeline.
- Build and publish the Docker image.
- Create a new snapshot in Salambo with runtime type
pi. - Assign that snapshot to the agent that should use the Pi runtime.
- 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.