Browse documentation

Project structure

Know which files builders own, which files Salambo compiles, and which paths exist only at runtime.

A Salambo project describes agent behavior and sandbox inputs. It is not a replacement agent server: Salambo runs the model loop in the hosted worker.

Recommended layout

support-agent/
├── .pi/
│   ├── settings.json
│   ├── SYSTEM.md
│   ├── skills/
│   │   └── incident-triage/
│   │       └── SKILL.md
│   ├── prompts/
│   │   └── incident-report.md
│   └── extensions/
│       └── support-tools.mjs
├── sandbox/
│   ├── packages.json
│   └── workspace/
│       └── README.md
├── salambo.yaml
└── package.json

What each path owns

Path	Builder responsibility
`.pi/SYSTEM.md`	Base purpose, rules, and response expectations
`.pi/settings.json`	Standard Pi model and thinking-level defaults
`.pi/skills/`	Reusable, immutable instruction packages
`.pi/prompts/`	Named prompt templates
`.pi/extensions/`	Sandbox-hosted Pi extensions
`sandbox/packages.json`	Versioned APT, npm, and Python packages installed into the managed image
`sandbox/workspace/`	Seed files copied only into new run workspaces
`salambo.yaml`	Deployment, image, region, egress, environment, and secrets

Build-time and runtime paths

The source path and runtime path are intentionally different:

Source	Hosted behavior	Mutability
`.pi/SYSTEM.md`	Compiled into the deployment manifest	Immutable per deployment
`.pi/skills/`	Projected as agent resources	Read-only
`.pi/extensions/`	Loaded by the sandbox extension host	Read-only
`sandbox/packages.json`	Installed while the deployment image is built	Read-only at runtime
`sandbox/workspace/`	Copied to `/workspace` for a new run	Mutable and checkpointed

Only /workspace is builder-owned mutable state. Platform runtime files are not exposed through managed agent file tools.

Files Salambo generates

salambo manifest compiles source files into a deployment manifest containing normalized model settings, instructions, skills, prompts, tool declarations, hook subscriptions, and workspace policy. Do not edit the compiled manifest manually.

What does not belong here

Salambo, storage, or provider credentials in source files
Code that expects access to trusted worker memory
Mutable customer work under the immutable .pi/ source tree

Next, write agent instructions and choose the built-in tools needed to carry them out.

PreviousCreate your first agent

Up nextWrite agent instructions