Sandbox Runtime URLs

Sandboxes have real URL endpoints when you start it. No extra configuration required. Pick your favorite framework and get started. Sandboxes have two types of URLs:

runtime - This is the URL you use to access the sandbox’s runtime API. It is reserved on port 4001.
custom - This is any other port you wish to expose within the sandbox that is not reserved. You can set up any process you want on the sandbox on the specified port.

Runtime URL vs Custom Port URL

Every running sandbox includes a runtime base URL for API calls.

const sandbox = await client.sandboxes.create({
  imageName: "node",
});

console.log("Runtime URL:", sandbox.runtime.baseUrl);

// The SDK sends this to sandbox.runtime.baseUrl + /exec for you.
const result = await sandbox.exec(`node -e 'console.log("hello from runtime")'`);
console.log(result.stdout.trim());

sandbox = client.sandboxes.create(
    {
        "image_name": "python",
    }
)

print(f"Runtime URL: {sandbox.runtime.base_url}")

# The SDK sends this to sandbox.runtime.base_url + /exec for you.
result = sandbox.exec("""python3 -c 'print("hello from runtime")'""")
print(result.stdout.strip())

from hyperbrowser.models import CreateSandboxParams

sandbox = client.sandboxes.create(
    CreateSandboxParams(
        image_name="python",
    )
)

print(f"Runtime URL: {sandbox.runtime.base_url}")

# The SDK sends this to sandbox.runtime.base_url + /exec for you.
result = sandbox.exec("""python3 -c 'print("hello from runtime")'""")
print(result.stdout.strip())

create_response=$(
  curl -sS https://api.hyperbrowser.ai/api/sandbox \
    -H "x-api-key: $HYPERBROWSER_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "imageName": "node"
    }'
)

runtime_base_url=$(jq -r '.runtime.baseUrl' <<<"$create_response")
runtime_token=$(jq -r '.token' <<<"$create_response")

echo "Runtime URL: $runtime_base_url"

curl -sS \
  "$runtime_base_url/exec" \
  -H "Authorization: Bearer $runtime_token" \
  -H "Content-Type: application/json" \
  -d '{"command":"printf \"%s\\n\" \"hello from runtime\""}' \
  | jq -r '.result.stdout'

The SDK handles the sandbox runtime layer for you when you use the runtime functions. See Node SDK sandboxes and Python SDK sandboxes.

To make a service reachable, start it inside the sandbox and expose its port. For example:

runtime.host looks like https://<regional-runtime-host>
runtime.baseUrl looks like https://<regional-runtime-host>/sandbox/<sandbox-id>
exposed port 3000 uses a separate, sandbox-specific URL

The SDK can derive that URL locally:

sandbox.getExposedUrl(3000);

sandbox.get_exposed_url(3000)

Example: Expose a Public HTTP Server

The example below provides a public URL which you can use for running your own services inside the sandbox. For sensitive workloads, treat this as any other publicly accessible endpoint and authenticate your requests properly.

Start a simple HTTP server inside the sandbox, expose port 3000, and call it from outside the sandbox.

const sandbox = await client.sandboxes.create({
  imageName: "node",
});

const server = await sandbox.processes.start(`node -e "const http = require('http');

http
  .createServer((_, res) => {
    res.writeHead(200, { 'content-type': 'text/plain' });
    res.end('hello from sandbox');
  })
  .listen(3000, '0.0.0.0')"`);

await new Promise((resolve) => setTimeout(resolve, 1000));

const exposure = await sandbox.expose({
  port: 3000,
  auth: false,
});

console.log("Service URL:", exposure.url);

const response = await fetch(exposure.url);
console.log(await response.text());

import time
from urllib.request import urlopen

sandbox = client.sandboxes.create(
    {
        "image_name": "python",
    }
)

server = sandbox.processes.start(
    '''python3 -c "from http.server import BaseHTTPRequestHandler, HTTPServer

class Handler(BaseHTTPRequestHandler):
    def do_GET(self):
        body = b'hello from sandbox'
        self.send_response(200)
        self.send_header('Content-Type', 'text/plain')
        self.send_header('Content-Length', str(len(body)))
        self.end_headers()
        self.wfile.write(body)

HTTPServer(('0.0.0.0', 3000), Handler).serve_forever()"'''
)

time.sleep(1)

exposure = sandbox.expose(
    {
        "port": 3000,
        "auth": False,
    }
)

print(f"Service URL: {exposure.url}")

with urlopen(exposure.url) as response:
    print(response.read().decode())

import time
from urllib.request import urlopen

from hyperbrowser.models import CreateSandboxParams, SandboxExposeParams

sandbox = client.sandboxes.create(
    CreateSandboxParams(
        image_name="python",
    )
)

server = sandbox.processes.start(
    '''python3 -c "from http.server import BaseHTTPRequestHandler, HTTPServer

class Handler(BaseHTTPRequestHandler):
    def do_GET(self):
        body = b'hello from sandbox'
        self.send_response(200)
        self.send_header('Content-Type', 'text/plain')
        self.send_header('Content-Length', str(len(body)))
        self.end_headers()
        self.wfile.write(body)

HTTPServer(('0.0.0.0', 3000), Handler).serve_forever()"'''
)

time.sleep(1)

exposure = sandbox.expose(
    SandboxExposeParams(
        port=3000,
        auth=False,
    )
)

print(f"Service URL: {exposure.url}")

with urlopen(exposure.url) as response:
    print(response.read().decode())

Auth Enabled (`auth: true`)

When auth is true, the exposed custom URL now requires the auth token to be passed on each request.

Backend Calls (`exposure.url`)

Call exposure.url programmatically and pass the sandbox bearer token in the Authorization header.

Browser Access (`exposure.browserUrl`)

Open exposure.browserUrl in a browser when you need a user-facing flow for an auth-protected endpoint.

`browserUrl` Bootstrap

browserUrl performs auth bootstrap first and then redirects to the path in next.

Public Endpoint (`auth: false`)

Use auth: false when you want open browser access and keep auth/authorization logic inside your own application.

Backend Workflow (Bearer Token)

This flow is best for backend automation and API calls. Call the protected exposed URL with the sandbox bearer token.

const sandbox = await client.sandboxes.create({
  imageName: "node",
});

await sandbox.processes.start(`node -e "const http = require('http');

http
  .createServer((req, res) => {
    if (req.url === '/api/status') {
      res.writeHead(200, { 'content-type': 'application/json' });
      res.end(JSON.stringify({ ok: true }));
      return;
    }
    res.writeHead(404);
    res.end('not found');
  })
  .listen(3000, '0.0.0.0')"`);

await new Promise((resolve) => setTimeout(resolve, 1000));

const exposure = await sandbox.expose({
  port: 3000,
  auth: true,
});

const detail = await sandbox.info();
const apiUrl = new URL("/api/status", exposure.url);

const response = await fetch(apiUrl, {
  headers: {
    Authorization: `Bearer ${detail.token}`,
  },
});

console.log(await response.text());

import time
from urllib.parse import urljoin
from urllib.request import Request, urlopen

sandbox = client.sandboxes.create(
    {
        "image_name": "python",
    }
)

sandbox.processes.start(
    '''python3 -c "from http.server import BaseHTTPRequestHandler, HTTPServer

class Handler(BaseHTTPRequestHandler):
    def do_GET(self):
        if self.path == '/api/status':
            body = b'{"ok": true}'
            self.send_response(200)
            self.send_header('Content-Type', 'application/json')
            self.send_header('Content-Length', str(len(body)))
            self.end_headers()
            self.wfile.write(body)
            return

        self.send_response(404)
        self.end_headers()

    def log_message(self, format, *args):
        pass

HTTPServer(('0.0.0.0', 3000), Handler).serve_forever()"'''
)

time.sleep(1)

exposure = sandbox.expose(
    {
        "port": 3000,
        "auth": True,
    }
)

detail = sandbox.info()
api_url = urljoin(exposure.url, "/api/status")

request = Request(
    api_url,
    headers={"Authorization": f"Bearer {detail.token}"},
)

with urlopen(request) as response:
    print(response.read().decode())

import time
from urllib.parse import urljoin
from urllib.request import Request, urlopen

from hyperbrowser.models import CreateSandboxParams, SandboxExposeParams

sandbox = client.sandboxes.create(
    CreateSandboxParams(
        image_name="python",
    )
)

sandbox.processes.start(
    '''python3 -c "from http.server import BaseHTTPRequestHandler, HTTPServer

class Handler(BaseHTTPRequestHandler):
    def do_GET(self):
        if self.path == '/api/status':
            body = b'{"ok": true}'
            self.send_response(200)
            self.send_header('Content-Type', 'application/json')
            self.send_header('Content-Length', str(len(body)))
            self.end_headers()
            self.wfile.write(body)
            return

        self.send_response(404)
        self.end_headers()

    def log_message(self, format, *args):
        pass

HTTPServer(('0.0.0.0', 3000), Handler).serve_forever()"'''
)

time.sleep(1)

exposure = sandbox.expose(
    SandboxExposeParams(
        port=3000,
        auth=True,
    )
)

detail = sandbox.info()
api_url = urljoin(exposure.url, "/api/status")

request = Request(
    api_url,
    headers={"Authorization": f"Bearer {detail.token}"},
)

with urlopen(request) as response:
    print(response.read().decode())

curl "$EXPOSED_URL/api/status" \
  -H "Authorization: Bearer $SANDBOX_TOKEN"

Browser Workflow (Preview URL Redirect)

Use the auth-enabled endpoint to generate a protected preview URL for browser access.

const sandbox = await client.sandboxes.create({
  imageName: "node",
});

await sandbox.processes.start(`node -e "const http = require('http');

http
  .createServer((req, res) => {
    if (req.url === '/preview') {
      res.writeHead(200, { 'content-type': 'text/html' });
      res.end('<h1>Sandbox Preview</h1><p>Protected by sandbox auth.</p>');
      return;
    }
    res.writeHead(404);
    res.end('not found');
  })
  .listen(3000, '0.0.0.0')"`);

await new Promise((resolve) => setTimeout(resolve, 1000));

const exposure = await sandbox.expose({
  port: 3000,
  auth: true,
});

const browserUrl = new URL(exposure.browserUrl);
browserUrl.searchParams.set("next", "/preview");

console.log("Open preview URL:", browserUrl.toString());

import time
from urllib.parse import parse_qsl, urlencode, urlparse, urlunparse

sandbox = client.sandboxes.create(
    {
        "image_name": "python",
    }
)

sandbox.processes.start(
    '''python3 -c "from http.server import BaseHTTPRequestHandler, HTTPServer

class Handler(BaseHTTPRequestHandler):
    def do_GET(self):
        if self.path == '/preview':
            body = b'<h1>Sandbox Preview</h1><p>Protected by sandbox auth.</p>'
            self.send_response(200)
            self.send_header('Content-Type', 'text/html')
            self.send_header('Content-Length', str(len(body)))
            self.end_headers()
            self.wfile.write(body)
            return

        self.send_response(404)
        self.end_headers()

    def log_message(self, format, *args):
        pass

HTTPServer(('0.0.0.0', 3000), Handler).serve_forever()"'''
)

time.sleep(1)

exposure = sandbox.expose(
    {
        "port": 3000,
        "auth": True,
    }
)

parsed = urlparse(exposure.browser_url)
query = dict(parse_qsl(parsed.query))
query["next"] = "/preview"
browser_url = urlunparse(parsed._replace(query=urlencode(query)))

print(f"Open preview URL: {browser_url}")

import time
from urllib.parse import parse_qsl, urlencode, urlparse, urlunparse

from hyperbrowser.models import CreateSandboxParams, SandboxExposeParams

sandbox = client.sandboxes.create(
    CreateSandboxParams(
        image_name="python",
    )
)

sandbox.processes.start(
    '''python3 -c "from http.server import BaseHTTPRequestHandler, HTTPServer

class Handler(BaseHTTPRequestHandler):
    def do_GET(self):
        if self.path == '/preview':
            body = b'<h1>Sandbox Preview</h1><p>Protected by sandbox auth.</p>'
            self.send_response(200)
            self.send_header('Content-Type', 'text/html')
            self.send_header('Content-Length', str(len(body)))
            self.end_headers()
            self.wfile.write(body)
            return

        self.send_response(404)
        self.end_headers()

    def log_message(self, format, *args):
        pass

HTTPServer(('0.0.0.0', 3000), Handler).serve_forever()"'''
)

time.sleep(1)

exposure = sandbox.expose(
    SandboxExposeParams(
        port=3000,
        auth=True,
    )
)

parsed = urlparse(exposure.browser_url)
query = dict(parse_qsl(parsed.query))
query["next"] = "/preview"
browser_url = urlunparse(parsed._replace(query=urlencode(query)))

print(f"Open preview URL: {browser_url}")

browserUrl is not the raw port API URL. It is a bootstrap URL that sets the auth cookie and then redirects to next. Use url for programmatic clients, and use browserUrl when you want to land a browser on a protected page.

Get Started

Sandbox

Base Images

Custom Images

Volumes

Local Filesystem

Runtime URL vs Custom Port URL

Example: Expose a Public HTTP Server

Auth Enabled (`auth: true`)

Backend Workflow (Bearer Token)

Browser Workflow (Preview URL Redirect)

​Runtime URL vs Custom Port URL

​Example: Expose a Public HTTP Server

​Auth Enabled (auth: true)

​Backend Workflow (Bearer Token)

​Browser Workflow (Preview URL Redirect)

Runtime URL vs Custom Port URL

Example: Expose a Public HTTP Server

Auth Enabled (`auth: true`)

Backend Workflow (Bearer Token)

Browser Workflow (Preview URL Redirect)