Introduction
Sandboxes are isolated Linux machines in Buddy. They boot in milliseconds, keep their disk between sessions, and expose applications on public endpoints.
Quick start
Create your first Buddy Sandbox from the web interface or the CLI, connect to it, run your project, and open the application on a public URL.
Configuration
Every setting of a Buddy Sandbox - resources, boot commands, apps, fetch sources, endpoints, variables, tags, and timeout - and what you can change later.
What's in a Sandbox
The default image every Buddy Sandbox starts from - operating system, language runtimes, Docker, developer tools, AI coding agent, Buddy CLI, user, and working directory.
Lifecycle
Sandbox and application statuses, what persists on disk between sessions, how the Sandbox timeout works, and how a stopped Sandbox wakes on traffic.
Git and Artifacts
Pull the project repository, a repository from another Buddy project, or a public repository into a Sandbox - with a destination path and a build command.
Variables and secrets
Define environment variables, files, and SSH keys for a Buddy Sandbox at workspace, project, or Sandbox level - encrypted and injected before the first command.
Snapshots
Save a Buddy Sandbox as a snapshot, start new Sandboxes from it, or revert to an earlier state - from the UI, the CLI, a pipeline, or the Sandbox itself.
Terminal and SSH
Open a shell in a Buddy Sandbox from the browser or over SSH, connect your IDE to the machine, and understand who is authorized to connect and how.
Files
Browse the persistent filesystem of a Buddy Sandbox, copy files in and out with the CLI, and manage them programmatically over the API and SDK.
Running commands
Execute non-interactive commands in a Buddy Sandbox in Bash, JavaScript, TypeScript, or Python - with full history, logs, statuses, and exit codes.
Apps
Define long-running applications in a Buddy Sandbox, start and stop them, read their logs, and expose them to the internet through an endpoint.
Logs
Every log a Buddy Sandbox produces - setup, fetch, apps, commands, HTTP requests, and the activity audit trail - and where to read each in the UI and the CLI.
Endpoints
Expose applications running in a Buddy Sandbox over HTTP, TCP, or TLS - with regional placement, IP whitelisting, authentication, and static file serving.
Identity
Put Buddy authentication in front of a Sandbox endpoint and let the app inside read who the visitor is - name, email, and groups - with no login flow.
Custom domains
Serve an app running in a Buddy Sandbox on your own domain instead of a generated one - by routing the domain to a Sandbox endpoint through a distribution.
Permissions and security
How access to a Buddy Sandbox is calculated from project roles, direct assignments, and groups - plus repository and artifact access, tokens, and IP whitelists.
CLI
Everyday Buddy Sandbox workflows with the bdy CLI - create, connect, run commands, copy files, expose ports, take snapshots, and inspect the machine.
Self-management
The this command lets anything inside a Buddy Sandbox reconfigure that machine - endpoints, apps, snapshots, resources - with no identifier and no token.
SDK
Create and drive Buddy Sandboxes from code with @buddy-works/sandbox-sdk - the full lifecycle, commands, files, apps, and snapshots from TypeScript.
AI agents
Run AI coding agents inside a Buddy Sandbox, let agents operate Sandboxes over MCP, and host Claude Managed Agents on Buddy infrastructure.
Sandboxes in pipelines
Create, deploy to, and tear down Buddy Sandboxes from a pipeline - with the Create and Manage Sandbox actions, Sandbox targets, and Sandbox event triggers.
Troubleshooting
Fixes for the problems Sandbox users hit most often - unreachable endpoints, an offline agent, unexpected stops, failed setup, a full disk, and SSH errors.