YAML for sandboxes

View as Markdown

Complete YAML reference for defining Buddy Sandboxes - resources, boot commands, apps, fetch sources, endpoints, variables, and permissions.

YAML parameters for YAML for sandboxes

Sandbox
sandboxrequiredstring
The sandbox identifier (human-readable ID).
namerequiredstring
The display name of the sandbox.
osstring
The operating system image (e.g. 'noble', 'ubuntu:24.04').
resourcesstring enum
The machine size (CPU x RAM in GB), e.g. '2x4'.
Allowed enum:
1x2,
2x4,
3x6,
4x8,
5x10,
6x12,
7x14,
8x16,
9x18,
10x20,
11x22,
12x24,
CUSTOM
first_boot_commandsstring
Shell commands run once on the first boot of the sandbox. Several commands go in one multi-line string (a | block), one per line - not a YAML list.
tagsstring[]
The list of tags associated with the sandbox.
app_dirstring
The working directory for the applications (default '/buddy').
apps(string | SandboxAppYaml)[]
The list of application start commands run in the sandbox.
timeoutinteger
The inactivity timeout in seconds after which the sandbox is stopped.
backupstring enum
How often an automatic snapshot of the sandbox is taken: OFF (default), HOURLY, DAILY or WEEKLY.
Allowed enum:
OFF,
HOURLY,
DAILY,
WEEKLY
snapshot_retentionSnapshotRetentionYaml
Which snapshots of the sandbox are kept; applies to all snapshots, automatic and manual.
endpointsTunnelYaml[]
The list of exposed endpoints (tunnels) of the sandbox.
variablesVariableYaml[]
The list of environment variables available in the sandbox.
fetchSandboxFetchYaml[]
The list of sources fetched into the sandbox before start (repositories or artifacts).
permissionsPermissionsYaml
Access control settings for the sandbox.
notestring
Note for this resource
agent_notestring
YAML note for AI agents operating on this resource
Endpoint
endpointstring
The target address the endpoint forwards to (e.g. 'localhost:8080').
namestring
The endpoint name.
typestring enum
The endpoint protocol.
Allowed enum:
TCP,
TLS,
HTTP,
SSH
whiteliststring[]
The list of IP addresses/ranges allowed to access the endpoint.
timeoutinteger
The endpoint idle timeout in seconds.
regionstring enum
The region the endpoint is exposed from. When not set, the region of the agent is used.
Allowed enum:
US,
EU,
AS
httpHttpSettingsYaml
HTTP-specific settings (applies to HTTP endpoints).
tlsTlsSettingsYaml
TLS-specific settings (applies to TLS endpoints).
notestring
Note for this resource
agent_notestring
YAML note for AI agents operating on this resource
HTTP Settings
verify_certificateboolean
Whether to verify the upstream TLS certificate.
compressionboolean
Whether to enable response compression.
http2boolean
Whether to enable HTTP/2.
log_requestsboolean
Whether to log incoming requests.
request_headersobject
Headers added to forwarded requests (name to value).
whitelist_user_agentsstring[]
The list of user agents allowed to access the endpoint.
rewrite_host_headerstring
The value to rewrite the Host header to.
response_headersobject
Headers added to responses (name to value).
tls_castring
The CA certificate used to verify the upstream (PEM).
circuit_breakerinteger
The circuit breaker threshold (percentage, 0-100).
serve_pathstring
The local path to serve static files from.
auth_typestring enum
The authentication type for the endpoint.
Allowed enum:
NONE,
BASIC,
BUDDY
authHttpAuthYaml
The credentials used when authentication is enabled.
HTTP Auth
usernamestring
The authentication username.
passwordstring
The authentication password.
TLS Settings
private_keystring
The TLS private key (PEM).
certificatestring
The TLS certificate (PEM).
ca_certificatestring
The CA certificate (PEM).
terminate_atstring enum
Where TLS is terminated. Default: REGION.
Allowed enum:
REGION,
AGENT,
TARGET
Permissions
othersstring enum
Access level for other workspace members. Allowed levels depend on the resource: pipelines and sandboxes accept DENIED, READ_ONLY, RUN_ONLY, READ_WRITE or DEFAULT; actions DENIED or ALLOWED; environments DENIED, USE_ONLY, MANAGE or DEFAULT; distributions DENIED, READ_ONLY, MANAGE or DEFAULT
Allowed enum:
DENIED,
READ_ONLY,
USE_ONLY,
BLIND,
RUN_ONLY,
READ_WRITE,
MANAGE,
DEFAULT,
ALLOWED,
STAGE,
COMMIT
usersobject
Map of specific users (username or email) to their access levels. A user who is not a member of the project (of the workspace for a sandbox outside a project) is ignored without an error. Allowed levels depend on the resource: pipelines and sandboxes accept DENIED, READ_ONLY, RUN_ONLY, READ_WRITE or DEFAULT; actions DENIED or ALLOWED; environments DENIED, USE_ONLY, MANAGE or DEFAULT; distributions DENIED, READ_ONLY, MANAGE or DEFAULT
groupsobject
List of user groups with their access levels. A group that is not added to the project (does not exist in the workspace for a sandbox outside a project) is ignored without an error. Allowed levels depend on the resource: pipelines and sandboxes accept DENIED, READ_ONLY, RUN_ONLY, READ_WRITE or DEFAULT; actions DENIED or ALLOWED; environments DENIED, USE_ONLY, MANAGE or DEFAULT; distributions DENIED, READ_ONLY, MANAGE or DEFAULT
pipelinesAllowedPipelineYaml[]
List of pipelines allowed to access this resource
sandboxesAllowedSandboxYaml[]
List of sandboxes allowed to access this resource

Last modified on Nov 17, 2026

YAML examples for YAML for sandboxes

Minimal sandbox

yaml
- sandbox: my-sandbox
  name: My Sandbox
  os: noble

Sandbox with endpoints, variables, fetch, backup and permissions

yaml
- sandbox: prod-box
  name: Production Box
  os: ubuntu:24.04
  resources: 3x6
  first_boot_commands: |
    #!/bin/bash
    apt-get update
    apt-get install -y nginx
  tags:
    - backend
    - prod
  app_dir: /app
  apps:
    - app: web
      run_command: npm run start
      path: /app/web
  timeout: 3600
  backup: DAILY
  snapshot_retention:
    keep_last: 10
  endpoints:
    - name: web
      endpoint: localhost:8080
      type: HTTP
      region: EU
      whitelist:
        - 10.0.0.0/8
      timeout: 300
      http:
        verify_certificate: true
        compression: true
        auth_type: BASIC
        auth:
          username: admin
          password: secret
    - tn1: 9090
  variables:
    - key: API_URL
      value: https://api.example.com
      type: VAR
      note: Backend API URL
  fetch:
    - repository: https://github.com/acme/app.git
      ref: main
      path: /app/src
    - artifact: acme-assets:latest
      path: /app/public
      source_path: dist.zip
  permissions:
    others: DENIED
    users:
      dev@example.com: READ_WRITE
    groups:
      admins: READ_WRITE
    pipelines:
      - all: DENIED
      - project: my-project
        pipeline: deploy
        access: USE_ONLY
    sandboxes:
      - project: my-project
        sandbox: base
        access: USE_ONLY