Get Started on Cloud
BasicsAI AgentsPipelinesActions & ServicesEnvironmentsIntegrationsTargetsTestsDomainsSandboxesAgents & TunnelsYAMLBuddy GitFAQ

YAML for sandboxes

View as Markdown

A Sandbox can be defined entirely in YAML, versioned in your repository, and imported into Buddy. For how to import, apply, and export a definition, see Sandbox configuration.

Sandbox parameters

Name Type Description
sandbox required String The sandbox identifier. Letters, digits, underscores, and hyphens; a hyphen cannot be the first or last character.
name required String The display name of the sandbox.
os String Operating system image: ubuntu:22.04 or ubuntu:24.04.
resources String Machine size as CPUxRAM, where RAM is in GB: 1x2, 2x4, 3x6, 4x8, 5x10, 6x12, 7x14, 8x16, 9x18, 10x20, 11x22, 12x24. Default: 2x4.
firstbootcommands String Commands run once during sandbox setup. Use |- for multi-line.
app_dir String Working directory for applications. Default: /buddy.
apps String[] Commands starting long-running applications.
timeout Integer Seconds of inactivity after which the sandbox stops. Not set by default - without it the sandbox keeps running. Traffic on an endpoint resets the countdown and wakes a stopped sandbox.
tags String[] Tags used to categorize sandboxes and to scope pipeline triggers.
fetch Fetch[] Sources pulled into the sandbox before setup: repositories and artifacts.
endpoints Endpoint[] Public endpoints (tunnels) of the sandbox.
variables Variable[] Environment variables, files, and keys.
permissions Permissions Access control for the sandbox.

Fetch parameters

Each entry is one source. Leave repository empty to use the project repository; set artifact to pull a published package instead of a repository.

Name Type Description
repository String URL of a public repository. Omit to use the project repository.
project String Project whose repository should be fetched, when it is not the current one.
artifact String Artifact to fetch, as name@version.
ref String Branch, tag, or revision. Defaults to the default branch.
path String Destination path inside the sandbox. Defaults to the app directory.
build_command String Command run in the source directory right after fetching.

Endpoint parameters

Name Type Description
name required String Name of the endpoint.
endpoint required String Target the endpoint forwards to - a port or an address, e.g. 80, localhost:8080.
type String HTTP (default), TCP, TLS, or SSH.
region String Region the endpoint is exposed from: EU, US, or AS.
whitelist String[] IP addresses and CIDR ranges allowed to connect.
timeout Integer Idle connection timeout in seconds.
http HttpSettings HTTP-specific settings.
tls TlsSettings TLS-specific settings.

An endpoint can also be written in shorthand as <name>: <endpoint>:

yaml
  endpoints:
  - metrics: 9090

HTTP endpoint parameters

Name Type Description
verify_certificate Boolean Verify the upstream TLS certificate.
compression Boolean Enable response compression.
http2 Boolean Enable HTTP/2.
log_requests Boolean Log incoming requests.
serve_path String Serve static files from this local path instead of forwarding to an application.
rewrite_host_header String Value to rewrite the Host header to.
whitelist_user_agents String[] User agents allowed to access the endpoint.
request_headers Object Headers added to forwarded requests.
response_headers Object Headers added to responses.
tls_ca String CA certificate used to verify the upstream (encrypted).
circuit_breaker Integer Circuit breaker threshold, 0-100.
auth_type String NONE, BASIC, or BUDDY. BUDDY requires visitors to sign in with their Buddy account - see Identity.
auth Auth Credentials used when auth_type is BASIC.

Auth parameters for HTTP endpoints

Name Type Description
username String Basic authentication username.
password String Basic authentication password (encrypted).

TLS endpoint parameters

Name Type Description
terminate_at String Where TLS is terminated: REGION (default), AGENT, or TARGET.
private_key String Private key of the TLS certificate (encrypted).
certificate String TLS certificate (encrypted).
ca_certificate String CA certificate (encrypted).

Variables parameters

Name Type Description
key required String Name of the variable.
value String Value of the variable. Use !encrypted for sensitive data.
type String VAR (default), FILE, SSH_KEY, or SSH_PUBLIC_KEY.
file_path String Where to write the file or key inside the sandbox. Required for FILE, SSH_KEY, and SSH_PUBLIC_KEY.
file_chmod String Permission set applied on write, e.g. 600.
note String Optional description.

See Variables and secrets for scopes and encryption.

Permissions parameters

Name Type Description
others String Access level for everyone else: DEFAULT, DENIED, READ_ONLY, or READ_WRITE.
users Object Map of user emails to access levels.
groups Object Map of group names to access levels.

Access levels map to the ones in the UI as follows:

Value In the UI
READ_WRITE Manage - full control
READ_ONLY View-only
DEFAULT Project role - inherit what the user's role in the project grants
DENIED None (Deny)

A user assigned directly takes that level; otherwise group assignments are summed; otherwise others applies. See Permissions and security.

Warning
MANAGE and USE_ONLY are valid for targets and environments, but not for Sandboxes - Buddy rejects them with Invalid value of 'accessLevel'. Use READ_WRITE and READ_ONLY instead.

Example

yaml
- sandbox: my-app
  name: My Application
  os: ubuntu:24.04
  resources: 3x6
  timeout: 3600
  first_boot_commands: |-
    apt-get update
    apt-get install -y nginx
  app_dir: /home/buddy/app
  apps:
  - npm start
  tags:
  - staging
  - preview
  fetch:
  - ref: main
    path: /home/buddy/app
    build_command: npm install && npm run build
  - artifact: my-assets@2.1.0
    path: /home/buddy/app/public
  endpoints:
  - name: www
    endpoint: 3000
    type: HTTP
    region: EU
    timeout: 60
    whitelist:
    - 12.34.56.78
    http:
      compression: true
      http2: true
      log_requests: true
      rewrite_host_header: my-app.example.com
      request_headers:
        X-Forwarded-Proto: https
      response_headers:
        X-Frame-Options: DENY
      circuit_breaker: 10
      auth_type: BASIC
      auth:
        username: user
        password: '!encrypted …'
  - name: database
    endpoint: localhost:5432
    type: TCP
    region: EU
    whitelist:
    - 12.34.56.78
  - name: secure
    endpoint: localhost:465
    type: TLS
    region: EU
    tls:
      terminate_at: AGENT
      private_key: '!encrypted …'
      certificate: '!encrypted …'
      ca_certificate: '!encrypted …'
  variables:
  - key: API_URL
    value: https://api.example.com
    note: Backend API URL
  - key: app_config
    value: '!encrypted …'
    type: FILE
    file_path: /home/buddy/app/config.json
    file_chmod: 644
  - key: deploy_key
    value: '!encrypted …'
    type: SSH_KEY
    file_path: "~/.ssh/id_deploy"
    file_chmod: 600

Example with permissions

yaml
- sandbox: dev-environment
  name: Development Environment
  os: ubuntu:24.04
  resources: 2x4
  apps:
  - npm start
  endpoints:
  - name: web
    endpoint: 3000
    type: HTTP
    region: EU
  permissions:
    others: DENIED
    users:
      admin@example.com: READ_WRITE
      developer@example.com: READ_ONLY
    groups:
      DevOps: READ_WRITE
      QA: READ_ONLY

Last modified on Aug 14, 2026

Previous pageYAML for environmentsNext pageYAML for agents