# Configure salambo.yaml

Define deployment identity, managed sandbox settings, runtime access, and workspace upgrade behavior.

`salambo.yaml` describes deployment and runtime configuration. Agent behavior belongs under `.pi/`.

## Managed deployment example

```yaml
version: 1
name: my-agent
runtime: pi

image:
  mode: managed

agent:
  name: My Agent
  slug: my-agent
  description: General-purpose agent.
  icon: 🤖
  isActive: true

runtimeConfig:
  sandboxRegion: eu
  egressPolicyMode: restricted
  egressAllowlist: []
  workspaceUpgradePolicy: automatic

env: {}

secrets:
  OPENAI_API_KEY:
    fromEnv: OPENAI_API_KEY
    description: Provider key.
    exposeTo:
      - runtime
```

## Configuration boundaries

| Section         | Owns                                                       |
| --------------- | ---------------------------------------------------------- |
| `image`         | Managed sandbox image                                      |
| `agent`         | Deployment identity and active state                       |
| `runtimeConfig` | Region, egress, telemetry overrides and workspace upgrades |
| `env`           | Non-secret runtime or sandbox configuration                |
| `secrets`       | Values read from the deployer's environment                |

## Important rules

* `runtime` is currently `pi`.
* `agent.slug` is the stable deployment lookup key.
* Use `agent.isActive` for runtime callability.
* Do not place prompts or instructions under `agent` in YAML.
* Put extensions under `.pi/extensions/`; do not duplicate them in YAML.
* Do not store raw secret values.
* Egress allowlists contain hosts only: no scheme, path or port.
* Credential exchanges contain secret names only; values remain in Salambo's secret store.
* Managed images reject Dockerfile, context, platform and build arguments.
* `workspaceUpgradePolicy` is `automatic` or `new-run-only`.

Use the complete [salambo.yaml reference](/docs/reference/salambo-yaml) for field-level behavior.