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.

tagsstring[]

The list of tags associated with the sandbox.

app_dirstring

The working directory for the applications (default '/buddy').

appsstring[]

The list of application start commands run in the sandbox.

timeoutinteger

The inactivity timeout in seconds after which the sandbox is stopped.

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 enum:

DENIED,

READ_ONLY,

USE_ONLY,

BLIND,

RUN_ONLY,

READ_WRITE,

MANAGE,

DEFAULT,

ALLOWED,

STAGE,

COMMIT

usersobject

List of specific users with their access levels

groupsobject

List of user groups with their access levels

pipelinesAllowedPipelineYaml[]

List of pipelines allowed to access this resource

sandboxesAllowedSandboxYaml[]

List of sandboxes allowed to access this resource

Last modified on Aug 14, 2026

YAML for environments YAML for agents

YAML examples for YAML for sandboxes

Minimal sandbox

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

Sandbox with endpoints, variables, fetch 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:
    - npm run start
  timeout: 3600
  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
  permissions:
    others: DENIED
    users:
      dev@example.com: READ_WRITE
    groups:
      admins: MANAGE
    sandboxes:
      - project: my-project
        sandbox: base
        access: USE_ONLY