Browse documentation

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

image:
  mode: managed

Agent

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

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:

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:

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

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

exposeTo contains runtime, sandbox, or both.

Secrets

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.

PreviousCLI reference

Up nextProject layout reference