Endpoints

View as Markdown

An endpoint makes something inside a Sandbox reachable from outside it. Endpoints are tunnels: the Buddy agent (bdy) running in the Sandbox holds an encrypted connection to Buddy, and Buddy publishes it on an address it assigns. Nothing is exposed directly, and there are no ports to open.

Every new Sandbox comes with one endpoint already configured - SSH, so you can connect to the machine. See Terminal and SSH. Everything else you want reachable - a web application, an API, a database - needs an endpoint of its own.

Info

Endpoints share their machinery with Agents & Tunnels. If you have used bdy tunnel, this is the same mechanism attached to a Sandbox.

Types

Type	Use it for
HTTP	Web applications and APIs, with authentication, headers, and compression
TCP	Anything speaking a raw protocol - databases, message brokers
TLS	Encrypted connections with your own certificate

In the UI

Endpoints are defined in the Sandbox settings. Click + to add one and decide five things:

Field	What it is
Name	Name of the endpoint
Local endpoint	The port or address inside the Sandbox that traffic is forwarded to, for example `80` or `localhost:8080`
Type	HTTP, TCP, or TLS
Authorization	Who is allowed through - an IP whitelist on any endpoint, plus Basic auth or Buddy auth on HTTP ones. See Security
Region	Where the endpoint is published - EU, US, or AS. Defaults to auto-detect

Type and authorization share one dropdown next to Local endpoint.

Image loading... Add a new endpoint

Once saved, the endpoint shows up in the Tunnels section with the address Buddy assigned - published from the EU, US, or AS region, which you can read off the eu-1 / us-1 part of the address. The section also lists the local port, the protection in place (None, HTTP BA, HTTP Buddy), and whether the endpoint is online. A recreated Sandbox can receive a new address. See Custom domains. Removing an endpoint immediately cuts off access through it.

Image loading... Sandbox tunnels

Warning

The target server must listen on 0.0.0.0. A process bound to 127.0.0.1 is unreachable through an endpoint even though it works fine in the terminal.

Security

Security applies to every endpoint, whatever its type:

Setting	What it does
Whitelist IPs & subnets	Lets through only the listed addresses or CIDR ranges
Timeout	Connection timeout in seconds
Authentication	Basic auth or Buddy auth, HTTP endpoints only

Authentication comes in two forms:

Basic auth - a username and password prompt in front of the application.
Buddy auth - only signed-in Buddy users get through. Allows your application to see who the visitors are. Their name, email, owner/admin flags, and groups - with no login flow of its own. See Identity.

HTTP endpoint security adds controls that only make sense for HTTP:

Setting	What it does
Whitelist user-agents	Lets through only matching user-agents, given as text or a regular expression
Rewrite Host header	Sends a custom Host header to the application
Request header	Adds a header to every incoming request
Response header	Adds a header to every outgoing response
Circuit breaker	Failure-rate threshold, 0-100, at which the endpoint stops forwarding to a failing backend

HTTP settings

Compression, HTTP/2, upstream certificate verification, and request logging are configurable per endpoint. Request logging is the fastest way to check whether traffic reaches the Sandbox at all - see Logs.

An HTTP endpoint can also serve files straight from a directory on the Sandbox disk, with no web server running at all.

TLS settings

For TLS endpoints you can supply your own certificate, private key, and CA certificate, and choose where TLS terminates - at the region, at the agent, or at the target.

From the CLI

bash
bdy sb ep add my-sandbox -e 3000 -n www                # HTTP on port 3000
bdy sb ep add my-sandbox -e 3306 -t TCP -n db          # raw TCP
bdy sb ep add my-sandbox -e 3000 -n www -r us          # publish from the US region
bdy sb ep add my-sandbox -e 3000 --whitelist 10.0.0.0/8 -a admin:secret
bdy sb ep add my-sandbox -e 3000 --buddy               # Buddy auth
bdy sb ep list my-sandbox
$$$$$$

In YAML

Endpoints support a full form and a shorthand. The shorthand is <name>: <endpoint>:

yaml
  endpoints:
  - name: www
    endpoint: localhost:8080
    type: HTTP
    region: EU
    whitelist:
    - 10.0.0.0/8
    timeout: 60
    http:
      compression: true
      http2: true
      auth_type: BASIC
      auth:
        username: admin
        password: '!encrypted …'
  - metrics: 9090

Full key reference: Sandbox YAML.

Endpoints as pipeline targets

A Sandbox endpoint can be used as a target in pipeline actions, which is how a pipeline deploys files into a Sandbox or runs remote commands against it. See Sandboxes in pipelines and Targets.

If endpoints stop working

Endpoints depend on the agent running inside the Sandbox. If it is stopped or removed, every endpoint goes offline until the agent is restored - see Troubleshooting.

Info

Endpoints can also be managed programmatically - over the REST API, from the SDK, from inside the Sandbox with this endpoint, and through MCP by AI agents.

Last modified on Sep 1, 2026

Logs Identity