Preview a sandbox application

Baseten Sandboxes are now available and free to use until November 16. Each organization can run up to 10 sandboxes at once. To raise this limit, contact support.

Reach an application running in a sandbox in one of two ways:

Port route: your own code calls the sandbox’s URL followed by /port/<PORT>/, with a sandbox access token. See Call an HTTP service in a sandbox.
Preview: an HTTPS URL for browsers and sharing, such as an agent-generated website. This page covers previews.

A preview routes its own HTTPS URL to a port in your sandbox. A sandbox can have multiple previews, each with its own name and access settings. Previews are private by default: a private preview requires a preview token, and a public preview lets anyone with the URL reach your application.

Prepare your application

Bind your application to the sandbox’s HOST environment variable so the preview can reach it. Port 80 is reserved and can’t serve a preview, and a preview of port 443 must be private. Set up your SDK or the CLI before running these examples. They use an existing sandbox named hello-world with Python installed, such as one created from Base Image. To create one, see Create a sandbox.

Create a preview

Start a web server on port 3000, wait for it to listen, then create a private preview named web and a preview token that expires after 1 hour. To open the application through a private preview:

TypeScript
Python
Go
CLI

Run the following code:

import { SandboxClient } from "@basetenlabs/sandbox";

const client = new SandboxClient({ apiKey: process.env.BASETEN_API_KEY! });
const sandbox = await client.get({ name: "hello-world" });

await sandbox.process.exec({
  command: 'python3 -m http.server 3000 --bind "$HOST" --directory /tmp',
  name: "preview-server",
  waitForPorts: [3000],
});
const preview = await sandbox.previews.create({
  name: "web",
  port: 3000,
  public: false,
});
const token = await sandbox.previews.createToken({
  previewName: preview.name,
  expiresAt: new Date(Date.now() + 3_600_000),
});
const url = new URL(preview.url);
url.searchParams.set("preview_token", token.token);
console.log(url.toString());

Run the following code:

import os
from datetime import datetime, timedelta, timezone
from urllib.parse import urlencode

from baseten.sandbox import SandboxClient

with SandboxClient(api_key=os.environ["BASETEN_API_KEY"]) as client:
    sandbox = client.get(name="hello-world")
    sandbox.process.exec(
        command='python3 -m http.server 3000 --bind "$HOST" --directory /tmp',
        name="preview-server",
        wait_for_ports=[3000],
    )
    preview = sandbox.previews.create(name="web", port=3000, public=False)
    token = sandbox.previews.create_token(
        preview_name=preview.name,
        expires_at=datetime.now(timezone.utc) + timedelta(hours=1),
    )
    query = urlencode({"preview_token": token.token})
    print(f"{preview.url}?{query}")

Run the following code:

package main

import (
    "context"
    "fmt"
    "log"
    "net/url"
    "os"
    "time"

    "github.com/basetenlabs/baseten-go/sandbox"
)

func main() {
    ctx := context.Background()
    client, err := sandbox.NewClient(sandbox.ClientOptions{
        APIKey: os.Getenv("BASETEN_API_KEY"),
    })
    if err != nil {
        log.Fatal(err)
    }
    sb, err := client.Get(ctx, sandbox.GetOptions{Name: "hello-world"})
    if err != nil {
        log.Fatal(err)
    }
    if _, err := sb.Process().Exec(ctx, sandbox.ProcessExecOptions{
        Command:      `python3 -m http.server 3000 --bind "$HOST" --directory /tmp`,
        Name:         "preview-server",
        WaitForPorts: []int{3000},
    }); err != nil {
        log.Fatal(err)
    }
    preview, err := sb.Previews().Create(ctx, sandbox.PreviewCreateOptions{
        Name:   "web",
        Port:   3000,
        Public: false,
    })
    if err != nil {
        log.Fatal(err)
    }
    token, err := sb.Previews().CreateToken(ctx, sandbox.PreviewCreateTokenOptions{
        PreviewName: preview.Name,
        ExpiresAt:   time.Now().Add(time.Hour),
    })
    if err != nil {
        log.Fatal(err)
    }
    previewURL, err := url.Parse(preview.URL)
    if err != nil {
        log.Fatal(err)
    }
    query := previewURL.Query()
    query.Set("preview_token", token.Token)
    previewURL.RawQuery = query.Encode()
    fmt.Println(previewURL.String())
}

Run the following command to start the web server and wait until it listens on port 3000:

baseten sandbox process start --name hello-world --process-name preview-server \
  --wait-for-port 3000 -- 'python3 -m http.server 3000 --bind "$HOST" --directory /tmp'

Run the following command to create a private preview of port 3000:

baseten sandbox preview create --name hello-world --preview-name web --port 3000

Name:              web
Status:            DEPLOYED
URL:               <PREVIEW_URL>
Port:              3000
Public:            false
Region:            us-pdx-1
Created:           2026-11-05T18:02:41Z
Updated:           2026-11-05T18:02:41Z

Replace <EXPIRES_AT> with a time 1 hour from now in ISO 8601, such as 2026-11-05T19:02:42Z, then run the following command to create a preview token:

baseten sandbox preview token create --name hello-world --preview-name web --expires-at <EXPIRES_AT>

Name:     <TOKEN_NAME>
Token:    <PREVIEW_TOKEN>
Expires:  2026-11-05T19:02:42Z
URL:      <PREVIEW_URL>?preview_token=<PREVIEW_TOKEN>

Open the printed URL in a browser. The page shows the directory listing for /tmp. For your own application, replace the server command and port. The preview routes traffic to the running application; it doesn’t start it. Retrieve or create the sandbox through the SDK before managing its previews. Preview operations need the sandbox’s name and don’t work on a handle created from its URL alone. On later runs, reuse the running server and existing preview instead of starting another process on the same port. To reuse a preview by name, pass createIfNotExists: true in TypeScript, create_if_not_exists=True in Python, CreateIfNotExists: true in Go, or --if-not-exists in the CLI. This returns the existing preview unchanged, including its access settings.

Control preview access

A preview token grants access to one private preview until it expires. It’s separate from the sandbox access token that authenticates sandbox requests. Treat a URL containing a preview token as a credential and share it only with people who should have access. The first request sets a cookie so the browser can continue navigating without the query parameter. To let anyone with the URL open the application, make the preview public. To make a preview public:

TypeScript
Python
Go
CLI

Run the following code:

import { SandboxClient } from "@basetenlabs/sandbox";

const client = new SandboxClient({ apiKey: process.env.BASETEN_API_KEY! });
const sandbox = await client.get({ name: "hello-world" });

const publicPreview = await sandbox.previews.update({ name: "web", public: true });
console.log(publicPreview.url);

Run the following code:

import os

from baseten.sandbox import SandboxClient

with SandboxClient(api_key=os.environ["BASETEN_API_KEY"]) as client:
    sandbox = client.get(name="hello-world")
    preview = sandbox.previews.update(name="web", public=True)
    print(preview.url)

Run the following code:

package main

import (
    "context"
    "fmt"
    "log"
    "os"

    "github.com/basetenlabs/baseten-go/sandbox"
)

func main() {
    ctx := context.Background()
    client, err := sandbox.NewClient(sandbox.ClientOptions{
        APIKey: os.Getenv("BASETEN_API_KEY"),
    })
    if err != nil {
        log.Fatal(err)
    }
    sb, err := client.Get(ctx, sandbox.GetOptions{Name: "hello-world"})
    if err != nil {
        log.Fatal(err)
    }
    public := true
    preview, err := sb.Previews().Update(ctx, sandbox.PreviewUpdateOptions{
        Name:   "web",
        Public: &public,
    })
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(preview.URL)
}

Run the following command:

baseten sandbox preview update --name hello-world --preview-name web --public

Name:              web
Status:            DEPLOYED
URL:               <PREVIEW_URL>
Port:              3000
Public:            true
Region:            us-pdx-1
Created:           2026-11-05T18:02:41Z
Updated:           2026-11-05T18:02:43Z

Open the returned URL in a new private browser window to verify access without a token. To require a token again, set public to false in TypeScript and Go or False in Python, or pass --private in the CLI.

Set an expiration

When a preview expires, Baseten deletes it and its URL stops serving. A preview’s expiration is separate from its tokens’ expiration and the sandbox’s expiration. Set it as a duration from the request, or as a fixed time with expiresAt in TypeScript, expires_at in Python, ExpiresAt in Go, or --expires-at in the CLI. Use one or the other in a request. Setting an expiration replaces any previous one. To delete the preview after 1 hour:

TypeScript
Python
Go
CLI

Run the following code:

import { SandboxClient } from "@basetenlabs/sandbox";

const client = new SandboxClient({ apiKey: process.env.BASETEN_API_KEY! });
const sandbox = await client.get({ name: "hello-world" });

const expiringPreview = await sandbox.previews.update({
  name: "web",
  ttlMs: 3_600_000,
});
console.log(expiringPreview.expiresAt);

Run the following code:

import os
from datetime import timedelta

from baseten.sandbox import SandboxClient

with SandboxClient(api_key=os.environ["BASETEN_API_KEY"]) as client:
    sandbox = client.get(name="hello-world")
    preview = sandbox.previews.update(name="web", ttl=timedelta(hours=1))
    print(preview.expires_at)

Run the following code:

package main

import (
    "context"
    "fmt"
    "log"
    "os"
    "time"

    "github.com/basetenlabs/baseten-go/sandbox"
)

func main() {
    ctx := context.Background()
    client, err := sandbox.NewClient(sandbox.ClientOptions{
        APIKey: os.Getenv("BASETEN_API_KEY"),
    })
    if err != nil {
        log.Fatal(err)
    }
    sb, err := client.Get(ctx, sandbox.GetOptions{Name: "hello-world"})
    if err != nil {
        log.Fatal(err)
    }
    preview, err := sb.Previews().Update(ctx, sandbox.PreviewUpdateOptions{
        Name: "web",
        TTL:  time.Hour,
    })
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(preview.ExpiresAt.Format(time.RFC3339))
}

Run the following command:

baseten sandbox preview update --name hello-world --preview-name web --ttl 1h

Name:              web
Status:            DEPLOYED
URL:               <PREVIEW_URL>
Port:              3000
Public:            true
Region:            us-pdx-1
Expires at:        2026-11-05T19:02:43Z
Created:           2026-11-05T18:02:41Z
Updated:           2026-11-05T18:02:43Z

The printed expiration is 1 hour after the update request. You can also set an expiration when you create a preview.

List and inspect previews

To list and inspect a sandbox’s previews:

Run the following command to list the sandbox’s previews:

baseten sandbox preview list --name hello-world

NAME  PORT  PUBLIC  STATUS    URL            EXPIRES
web   3000  false   DEPLOYED  <PREVIEW_URL>  -

Run the following command to inspect one preview’s URL, port, and status:

baseten sandbox preview describe --name hello-world --preview-name web

If a preview URL returns a 502 error, check that your application is running on the preview’s port and listening on HOST.

Remove a preview

Deleting a preview removes its tokens and stops access through its URL. It leaves the sandbox running. Deleting the sandbox also removes its previews. To remove the preview and stop the server:

TypeScript
Python
Go
CLI

Run the following code:

import { SandboxClient } from "@basetenlabs/sandbox";

const client = new SandboxClient({ apiKey: process.env.BASETEN_API_KEY! });
const sandbox = await client.get({ name: "hello-world" });

await sandbox.previews.delete({ name: "web" });
await sandbox.process.kill({ identifier: "preview-server" });

Run the following code:

import os

from baseten.sandbox import SandboxClient

with SandboxClient(api_key=os.environ["BASETEN_API_KEY"]) as client:
    sandbox = client.get(name="hello-world")
    sandbox.previews.delete(name="web")
    sandbox.process.kill(identifier="preview-server")

Run the following code:

package main

import (
    "context"
    "log"
    "os"

    "github.com/basetenlabs/baseten-go/sandbox"
)

func main() {
    ctx := context.Background()
    client, err := sandbox.NewClient(sandbox.ClientOptions{
        APIKey: os.Getenv("BASETEN_API_KEY"),
    })
    if err != nil {
        log.Fatal(err)
    }
    sb, err := client.Get(ctx, sandbox.GetOptions{Name: "hello-world"})
    if err != nil {
        log.Fatal(err)
    }
    if _, err := sb.Previews().Delete(ctx, sandbox.PreviewDeleteOptions{Name: "web"}); err != nil {
        log.Fatal(err)
    }
    if err := sb.Process().Kill(ctx, sandbox.ProcessKillOptions{Identifier: "preview-server"}); err != nil {
        log.Fatal(err)
    }
}

Run the following command to delete the preview, and confirm when prompted:

baseten sandbox preview delete --name hello-world --preview-name web

Run the following command to stop the example server:

baseten sandbox process kill --name hello-world --process-name preview-server

Open the preview URL in a new browser window to confirm that it no longer serves your application. For more information, see baseten sandbox preview and Create a sandbox preview.

Get started

Model APIs

Inference

Training

Baseten Grid

Frontier Gateway

Sandboxes

Development

Deployment

Engines

Model Labs

Organization

Hosting options

Observability

Troubleshooting

Preview a sandbox application

Prepare your application

Create a preview

Control preview access

Set an expiration

List and inspect previews

Remove a preview

​Prepare your application

​Create a preview

​Control preview access

​Set an expiration

​List and inspect previews

​Remove a preview

Prepare your application

Create a preview

Control preview access

Set an expiration

List and inspect previews

Remove a preview