# salambo.yaml reference

Field reference for source deployment, runtime configuration, environment exposure, and Pi project ownership.

## Top-level fields

| Field           | Type   | Notes                                          |
| --------------- | ------ | ---------------------------------------------- |
| `version`       | `1`    | Configuration version                          |
| `name`          | string | Project identifier                             |
| `runtime`       | `pi`   | Current hosted runtime                         |
| `image`         | object | Managed image configuration                    |
| `agent`         | object | Agent identity and active state                |
| `runtimeConfig` | object | Region, egress, telemetry and workspace policy |
| `env`           | map    | Non-secret environment values                  |
| `secrets`       | map    | Values loaded from deployer environment        |
| `local`         | object | Optional local template metadata               |

## Image

```yaml
image:
  mode: managed
```

## Agent

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

Prompts and instructions are not accepted here. Use `.pi/SYSTEM.md`, skills, and prompt templates.

## Runtime configuration

```yaml
runtimeConfig:
  sandboxRegion: eu
  egressPolicyMode: restricted
  egressAllowlist:
    - api.openai.com
  otlpEndpointOverride: null
  otelIncludeContentOverride: null
  workspaceUpgradePolicy: automatic
```

| Field                        | Values                                |
| ---------------------------- | ------------------------------------- |
| `sandboxRegion`              | Optional `us` or `eu`                 |
| `egressPolicyMode`           | `restricted` or `full-open`           |
| `egressAllowlist`            | Host-only values                      |
| `credentialExchanges`        | Named sealed OAuth exchange policies  |
| `otlpEndpointOverride`       | Optional per-deployment OTLP endpoint |
| `otelIncludeContentOverride` | Optional content-export override      |
| `workspaceUpgradePolicy`     | `automatic` or `new-run-only`         |

### Sealed credential exchanges

Use a credential exchange when sandbox code must convert long-lived OAuth material into a short-lived access token without receiving the source secrets or plaintext token:

```yaml
runtimeConfig:
  egressPolicyMode: restricted
  egressAllowlist:
    - oauth2.googleapis.com
    - gmail.googleapis.com
  credentialExchanges:
    google-workspace:
      request:
        host: oauth2.googleapis.com
        method: POST
        path: /token
        contentType: application/x-www-form-urlencoded
        requiredFields:
          grant_type: refresh_token
        secretFields:
          client_secret: GOOGLE_CLIENT_SECRET
          refresh_token: GOOGLE_REFRESH_TOKEN
      response:
        contentType: application/json
        credentialField: access_token
        tokenTypeField: token_type
        expectedTokenType: Bearer
        expiresInField: expires_in
      access:
        allowedHosts:
          - gmail.googleapis.com
```

`secretFields` contains environment-variable names, never values. The names may refer to secrets managed in `salambo.yaml` or secrets already configured in the Salambo UI. Every referenced value must be a sandbox-exposed secret whose host scope permits the exchange host. Restricted egress must also allow the exchange and access hosts.

The sandbox receives sealed handles. The managed proxy opens source credentials only for the exact declared token request, then returns a sealed access token that it can open only for the declared access hosts.

Authentication-file formats remain agent-owned. If a CLI requires a file, keep
the adapter beside the agent skill and create the file as late as possible. For
a command-line client, prefer a private temporary file that exists only for the
child process:

```bash
node /workspace/.salambo/agent/skills/provider/scripts/client.mjs <arguments>
```

The adapter should create the file with mode `0600`, set the provider's file
environment variable only for the child process, wait for the client, and
remove the temporary directory in a `finally` block. Do not place authentication
files in `/workspace`, because the workspace is durable and checkpointed. Do
not write provider files under `/run/salambo`; that namespace is platform-owned.

## Environment values

```yaml
env:
  APP_MODE:
    value: standard
    description: Application behavior mode.
    exposeTo:
      - runtime
```

`exposeTo` contains `runtime`, `sandbox`, or both.

## Secrets

```yaml
secrets:
  PARTNER_TOKEN:
    fromEnv: PARTNER_TOKEN
    description: Partner API credential.
    allowedHosts:
      - api.partner.example
    exposeTo:
      - sandbox
```

Sandbox exposure requires at least one `allowedHosts` entry. Raw secret values are rejected.

## Pi project boundary

Do not declare extensions in `salambo.yaml`. Put agent behavior under `.pi/`, including `.pi/extensions/`, `.pi/skills/`, `.pi/prompts/`, and `.pi/SYSTEM.md`.

## Unsupported top-level fields

The v1 schema accepts only the documented fields. Deployment records and the platform-owned runtime lifecycle own versioning and runtime preparation.