Preview a sandbox application

A preview routes an HTTPS URL to a port in your sandbox. Use it to open an agent-generated website in a browser or share a running application. 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; a public preview lets anyone with the URL reach your application.

Start an application and create a preview

Set up a Baseten SDK and create a sandbox before running these examples. Set BASETEN_API_KEY for SDK authentication. The examples use an existing sandbox named hello-world with Python installed. Bind your application to the sandbox’s HOST environment variable so the preview can reach it. Port 80 and the sandbox’s reserved system ports can’t serve previews. A preview on port 443 must stay private. Run the following code to start a web server on port 3000 and create a private preview named web. The process call waits for the server’s port before creating the preview:

TypeScript
Python
Go

To open the application through a private preview:

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());

To open the application through a private preview:

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}")

To open the application through a private preview:

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())
}

Open the printed URL in a browser. You should see 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 subsequent runs, reuse the running server and existing preview rather than 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, or CreateIfNotExists: true in Go. This returns the existing preview unchanged, including its access settings.

Control preview access

The preview token in the example expires after 1 hour. It grants access to that private preview and is separate from the sandbox access token used to manage resources. 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:

TypeScript
Python
Go

To allow access without a token:

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);

To allow access without a token:

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)

To allow access without a token:

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)
}

Open the returned URL in a new private browser window to verify access without a token. Set public to false in TypeScript and Go or False in Python to require a token again.

Set an expiration

A preview’s expiration controls when its URL stops serving. It’s separate from its tokens’ expiration and the sandbox’s lifetime. To delete the preview after 1 hour, set a relative lifetime when creating or updating it:

TypeScript
Python
Go

To expire the preview after 1 hour:

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);

To expire the preview after 1 hour:

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)

To expire the preview after 1 hour:

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))
}

Check that the printed expiration is 1 hour after the update request. You can set an absolute expiration with expiresAt in TypeScript, expires_at in Python, or ExpiresAt in Go instead. Use either a relative lifetime or an absolute expiration in one request.

Inspect previews with the CLI

Install the Baseten CLI and sign in before using CLI commands. To list previews and inspect a preview’s URL, port, and status, run:

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

The list includes each preview’s name, port, access setting, status, URL, and expiration. If a 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. Run the following code or commands to delete the web preview and stop the example server:

TypeScript
Python
Go
CLI

To remove the preview and stop the server:

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" });

To remove the preview and stop the server:

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")

To remove the preview and stop the server:

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)
    }
}

To remove the preview and stop the server:Install the Baseten CLI and sign in if you haven’t already.

Delete the preview:

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

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.

Get started

Model APIs

Inference

Training

Sandboxes

Development

Deployment

Engines

Model Labs

Organization

Hosting options

Observability

Troubleshooting

Preview a sandbox application

Start an application and create a preview

Control preview access

Set an expiration

Inspect previews with the CLI

Remove a preview

​Start an application and create a preview

​Control preview access

​Set an expiration

​Inspect previews with the CLI

​Remove a preview

Start an application and create a preview

Control preview access

Set an expiration

Inspect previews with the CLI

Remove a preview