Public URLs - Upstash Documentation

Expose ports from a box with public URLs. Each public URL maps to a specific port and can optionally require authentication.

Quickstart

Create a public URL

Start a web server inside your box and create a public URL to access it.

import { Agent, Box } from "@upstash/box"

const box = await Box.create({ runtime: "node" })

// Start a web server on port 3000
await box.exec.command("cd /work && npm install express")
await box.files.write({
  path: "/work/server.js",
  content: `
    const express = require('express')
    const app = express()
    app.get('/', (req, res) => res.send('Hello from Box!'))
    app.listen(3000)
  `,
})
await box.exec.command("node /work/server.js &")

// Create a public URL
const publicUrl = await box.getPublicURL(3000)

console.log(publicUrl.url)
// → https://{BOX_ID}-3000.preview.box.upstash.com

from upstash_box import Box

box = Box.create(runtime="node")

# Start a web server on port 3000
box.exec.command("cd /work && npm install express")
box.files.write(
    path="/work/server.js",
    content="""
    const express = require('express')
    const app = express()
    app.get('/', (req, res) => res.send('Hello from Box!'))
    app.listen(3000)
  """,
)
box.exec.command("node /work/server.js &")

# Create a public URL
public_url = box.get_public_url(3000)

print(public_url.url)
# -> https://{BOX_ID}-3000.preview.box.upstash.com

Add authentication

Protect your public URL with bearer token or basic authentication.

// With bearer token
const publicUrl = await box.getPublicURL(3000, { bearerToken: true })

console.log(publicUrl.token) // Use this in Authorization header
// → "63d8b153..."

// With basic auth
const publicUrl = await box.getPublicURL(8080, { basicAuth: true })

console.log(publicUrl.username) // → "user"
console.log(publicUrl.password) // → "f0f145f0..."

# With bearer token
public_url = box.get_public_url(3000, bearer_token=True)

print(public_url.token)  # Use this in Authorization header
# -> "63d8b153..."

# With basic auth
public_url = box.get_public_url(8080, basic_auth=True)

print(public_url.username)  # -> "user"
print(public_url.password)  # -> "f0f145f0..."

API

Create Public URL

Creates a public URL that exposes a port on your box. Returns the URL and authentication credentials if requested.

const publicUrl = await box.getPublicURL(3000)

console.log(publicUrl.url)
// → https://{BOX_ID}-3000.preview.box.upstash.com

public_url = box.get_public_url(3000)

print(public_url.url)
# -> https://{BOX_ID}-3000.preview.box.upstash.com

With Bearer Token

Add bearerToken: true to require an authorization header when accessing the public URL.

const publicUrl = await box.getPublicURL(3000, { bearerToken: true })

console.log(publicUrl.token)
// → "63d8b153..."

// Access the public URL:
// curl -H "Authorization: Bearer 63d8b153..." https://{BOX_ID}-3000.preview.box.upstash.com

public_url = box.get_public_url(3000, bearer_token=True)

print(public_url.token)
# -> "63d8b153..."

# Access the public URL:
# curl -H "Authorization: Bearer 63d8b153..." https://{BOX_ID}-3000.preview.box.upstash.com

With Basic Authentication

Add basicAuth: true to require username and password when accessing the public URL.

const publicUrl = await box.getPublicURL(8080, { basicAuth: true })

console.log(publicUrl.username) // → "user"
console.log(publicUrl.password) // → "f0f145f0..."

// Access the public URL:
// curl -u user:f0f145f0... https://{BOX_ID}-8080.preview.box.upstash.com

public_url = box.get_public_url(8080, basic_auth=True)

print(public_url.username)  # -> "user"
print(public_url.password)  # -> "f0f145f0..."

# Access the public URL:
# curl -u user:f0f145f0... https://{BOX_ID}-8080.preview.box.upstash.com

With Both Auth Methods

Enable both authentication methods. Either one will work when accessing the public URL.

const publicUrl = await box.getPublicURL(8080, { bearerToken: true, basicAuth: true })

console.log(publicUrl.token) // → "63d8b153..."
console.log(publicUrl.username) // → "user"
console.log(publicUrl.password) // → "f0f145f0..."

public_url = box.get_public_url(8080, bearer_token=True, basic_auth=True)

print(public_url.token)     # -> "63d8b153..."
print(public_url.username)  # -> "user"
print(public_url.password)  # -> "f0f145f0..."

List Public URLs

Get all active public URLs for this box.

const { publicURLs } = await box.listPublicURLs()

console.log(publicURLs)
// [
//   { id: "{BOX_ID}-3000", port: 3000, url: "https://{BOX_ID}-3000.preview.box.upstash.com",
//     created_at: 1789990404, basic_auth: false, bearer_token: false },
//   { id: "{BOX_ID}-8080", port: 8080, url: "https://{BOX_ID}-8080.preview.box.upstash.com",
//     created_at: 1789990512, basic_auth: false, bearer_token: true },
// ]

result = box.list_public_urls()

print(result["public_urls"])
# [
#   PublicURL(url="https://{BOX_ID}-3000.preview.box.upstash.com", port=3000),
#   PublicURL(url="https://{BOX_ID}-8080.preview.box.upstash.com", port=8080),
# ]

Delete Public URL

Remove a public URL by port number.

await box.deletePublicURL(3000)

box.delete_public_url(3000)

Behavior

One Public URL Per Port

Creating a public URL for a port that already has one will overwrite the previous one, including any auth credentials.

// First public URL
const publicUrl1 = await box.getPublicURL(3000)

// Second public URL overwrites the first one
const publicUrl2 = await box.getPublicURL(3000, { bearerToken: true })

// publicUrl1.url is no longer accessible

# First public URL
public_url1 = box.get_public_url(3000)

# Second public URL overwrites the first one
public_url2 = box.get_public_url(3000, bearer_token=True)

# public_url1.url is no longer accessible

Public URL Lifecycle

A public URL outlives a pause. While the box is paused, a request to the URL resumes it. See Waking a Paused Box. Public URLs are removed when the box is deleted.

Waking a Paused Box

An incoming HTTP request to a public URL resumes its box if the box is paused. The request is held while the box comes back and until the app’s port is listening, so the caller gets the app’s real response instead of an error. If the public URL requires authentication, the credentials are checked before the box is woken. The wait is bounded at 30 seconds. If the port is not listening by then, the request returns 503 with a Retry-After: 5 header rather than hanging: a browser gets a page that refreshes itself, and any other client gets a plain 503 to retry. The box keeps resuming in the background, so a retry usually succeeds. Anything slower than 30 seconds to start, such as a cold npm install, should be built into the image or a snapshot instead of left to the init command. Set a client timeout longer than that window. Both examples below set one explicitly, because some clients default to less than a cold start takes.

const publicUrl = await box.getPublicURL(3000)

await box.pause()

// This request resumes the box and returns the app's response
const response = await fetch(publicUrl.url, { signal: AbortSignal.timeout(60_000) })
console.log(response.status) // 200, or 503 if the app is still starting

import httpx

public_url = box.get_public_url(3000)

box.pause()

# This request resumes the box and returns the app's response.
# httpx defaults to a 5 second timeout, which a cold start can outlast.
response = httpx.get(public_url.url, timeout=60.0)
print(response.status_code)  # 200, or 503 if the app is still starting

For the app to answer on its own after a resume, the box needs to start its server again. An init command does that: the box runs it once every time the container starts, including after a resume.

Auto-Resume

Creating a public URL on a paused box automatically resumes it.

await box.pause()

// This will resume the box
const publicUrl = await box.getPublicURL(3000)

box.pause()

# This will resume the box
public_url = box.get_public_url(3000)

Examples

Expose an agent-built app

Let an agent build a web app, then create a public URL to test it.

import { Agent, Box } from "@upstash/box"

const box = await Box.create({
  runtime: "node",
  agent: {
    harness: Agent.ClaudeCode,
    model: "anthropic/claude-opus-4-6",
    apiKey: process.env.ANTHROPIC_API_KEY,
  },
})

await box.agent.run({
  prompt: `
Create a simple Express web server that:
- Listens on port 3000
- Has a / route that returns "Hello World"
- Has a /health route that returns {"status": "ok"}
- Start the server in the background
  `,
})

const publicUrl = await box.getPublicURL(3000)
console.log(`Public URL available at: ${publicUrl.url}`)

// Test the endpoints
const response = await fetch(`${publicUrl.url}/health`)
console.log(await response.json()) // { status: "ok" }

import os
from upstash_box import Box, Agent

box = Box.create(
    runtime="node",
    agent={
        "harness": Agent.CLAUDE_CODE,
        "model": "anthropic/claude-opus-4-6",
        "api_key": os.environ["ANTHROPIC_API_KEY"],
    },
)

box.agent.run(
    prompt="""
Create a simple Express web server that:
- Listens on port 3000
- Has a / route that returns "Hello World"
- Has a /health route that returns {"status": "ok"}
- Start the server in the background
  """,
)

public_url = box.get_public_url(3000)
print(f"Public URL available at: {public_url.url}")

# Test the endpoints
import httpx
response = httpx.get(f"{public_url.url}/health")
print(response.json())  # {"status": "ok"}

Create a public URL with authentication for sharing with team members.

import { Agent, Box } from "@upstash/box"

const box = await Box.create({ runtime: "python" })

// Set up a Flask app
await box.files.write({
  path: "/work/app.py",
  content: `
from flask import Flask
app = Flask(__name__)

@app.route('/')
def home():
    return 'Internal Dashboard'

if __name__ == '__main__':
    app.run(host='0.0.0.0', port=8080)
  `,
})

await box.exec.command("pip install flask && python /work/app.py &")

// Create authenticated public URL
const publicUrl = await box.getPublicURL(8080, { basicAuth: true })

console.log(`Public URL: ${publicUrl.url}`)
console.log(`Username: ${publicUrl.username}`)
console.log(`Password: ${publicUrl.password}`)

// Share these credentials with your team

import httpx
from upstash_box import Box

box = Box.create(runtime="python")

# Set up a Flask app
box.files.write(
    path="/work/app.py",
    content="""
from flask import Flask
app = Flask(__name__)

@app.route('/')
def home():
    return 'Internal Dashboard'

if __name__ == '__main__':
    app.run(host='0.0.0.0', port=8080)
  """,
)

box.exec.command("pip install flask && python /work/app.py &")

# Create authenticated public URL
public_url = box.get_public_url(8080, basic_auth=True)

print(f"Public URL: {public_url.url}")
print(f"Username: {public_url.username}")
print(f"Password: {public_url.password}")

# Share these credentials with your team

Multi-port application

Create multiple public URLs for different services in the same box.

import { Agent, Box } from "@upstash/box"

const box = await Box.create({ runtime: "node" })

// Start frontend on port 3000
await box.files.write({
  path: "/work/frontend.js",
  content: `
const express = require('express')
const app = express()
app.get('/', (req, res) => res.send('Frontend'))
app.listen(3000)
  `,
})

// Start API on port 8080
await box.files.write({
  path: "/work/api.js",
  content: `
const express = require('express')
const app = express()
app.get('/api/status', (req, res) => res.json({ status: 'ok' }))
app.listen(8080)
  `,
})

await box.exec.command("npm install express")
await box.exec.command("node /work/frontend.js & node /work/api.js &")

// Create a public URL for each service
const frontendPublicUrl = await box.getPublicURL(3000)
const apiPublicUrl = await box.getPublicURL(8080)

console.log(`Frontend: ${frontendPublicUrl.url}`)
console.log(`API: ${apiPublicUrl.url}`)

from upstash_box import Box

box = Box.create(runtime="node")

# Start frontend on port 3000
box.files.write(
    path="/work/frontend.js",
    content="""
const express = require('express')
const app = express()
app.get('/', (req, res) => res.send('Frontend'))
app.listen(3000)
  """,
)

# Start API on port 8080
box.files.write(
    path="/work/api.js",
    content="""
const express = require('express')
const app = express()
app.get('/api/status', (req, res) => res.json({ status: 'ok' }))
app.listen(8080)
  """,
)

box.exec.command("npm install express")
box.exec.command("node /work/frontend.js & node /work/api.js &")

# Create a public URL for each service
frontend_public_url = box.get_public_url(3000)
api_public_url = box.get_public_url(8080)

print(f"Frontend: {frontend_public_url.url}")
print(f"API: {api_public_url.url}")

Temporary testing public URL

Create a public URL, run tests against it, then clean up.

import { Agent, Box } from "@upstash/box"

const box = await Box.create({ runtime: "node" })

// Start test server
await box.exec.command("npx http-server /work -p 3000 &")

// Create a public URL for testing
const publicUrl = await box.getPublicURL(3000)

// Run your tests against the public URL
const response = await fetch(publicUrl.url)
console.log(response.status) // 200

// Clean up
await box.deletePublicURL(3000)
await box.delete()

import httpx
from upstash_box import Box

box = Box.create(runtime="node")

# Start test server
box.exec.command("npx http-server /work -p 3000 &")

# Create a public URL for testing
public_url = box.get_public_url(3000)

# Run your tests against the public URL
response = httpx.get(public_url.url)
print(response.status_code)  # 200

# Clean up
box.delete_public_url(3000)
box.delete()

The SDK still supports getPreviewUrl, listPreviews, and deletePreview, but they are deprecated aliases for getPublicURL, listPublicURLs, and deletePublicURL.

​Quickstart

​Create a public URL

​Add authentication

​API

​Create Public URL

​With Bearer Token

​With Basic Authentication

​With Both Auth Methods

​List Public URLs

​Delete Public URL

​Behavior

​One Public URL Per Port

​Public URL Lifecycle

​Waking a Paused Box

​Auto-Resume

​Examples

​Expose an agent-built app

​Share a secure public URL

​Multi-port application

​Temporary testing public URL

Quickstart

Create a public URL

Add authentication

API

Create Public URL

With Bearer Token

With Basic Authentication

With Both Auth Methods

List Public URLs

Delete Public URL

Behavior

One Public URL Per Port

Public URL Lifecycle

Waking a Paused Box

Auto-Resume

Examples

Expose an agent-built app

Share a secure public URL

Multi-port application

Temporary testing public URL