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 3000await 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 URLconst publicUrl = await box.getPublicURL(3000)console.log(publicUrl.url)// → https://{BOX_ID}-3000.preview.box.upstash.com

from upstash_box import Boxbox = Box.create(runtime="node")# Start a web server on port 3000box.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 URLpublic_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 tokenconst publicUrl = await box.getPublicURL(3000, { bearerToken: true })console.log(publicUrl.token) // Use this in Authorization header// → "63d8b153..."// With basic authconst publicUrl = await box.getPublicURL(8080, { basicAuth: true })console.log(publicUrl.username) // → "user"console.log(publicUrl.password) // → "f0f145f0..."

# With bearer tokenpublic_url = box.get_public_url(3000, bearer_token=True)print(public_url.token)  # Use this in Authorization header# -> "63d8b153..."# With basic authpublic_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 URLconst publicUrl1 = await box.getPublicURL(3000)// Second public URL overwrites the first oneconst publicUrl2 = await box.getPublicURL(3000, { bearerToken: true })// publicUrl1.url is no longer accessible

# First public URLpublic_url1 = box.get_public_url(3000)# Second public URL overwrites the first onepublic_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.

After container resume and configuration finish, the proxy waits up to 30 additional seconds for the app to become ready. The total HTTP request can take longer than 30 seconds. If the app is still not ready when that wait expires, the request returns 503 with a Retry-After: 5 header: a browser gets a page that refreshes itself, and any other client gets a plain 503 to retry. The box is already resumed, and the app can continue starting in the background. Move slow dependency installation, such as a cold npm install, into the image or a snapshot so the init command only needs to start the app.

Set a client timeout that allows for both container resume and the app readiness wait. Both examples below use 90 seconds; increase it if your environment needs more time. Some clients, including httpx, default to a shorter timeout than a cold start takes.

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

import httpxpublic_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=90.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 boxconst publicUrl = await box.getPublicURL(3000)

box.pause()# This will resume the boxpublic_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 endpointsconst response = await fetch(`${publicUrl.url}/health`)console.log(await response.json()) // { status: "ok" }

import osfrom upstash_box import Box, Agentbox = 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 endpointsimport httpxresponse = 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 appawait box.files.write({  path: "/work/app.py",  content: `from flask import Flaskapp = 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 URLconst 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 httpxfrom upstash_box import Boxbox = Box.create(runtime="python")# Set up a Flask appbox.files.write(    path="/work/app.py",    content="""from flask import Flaskapp = 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 URLpublic_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 3000await 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 8080await 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 serviceconst 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 Boxbox = Box.create(runtime="node")# Start frontend on port 3000box.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 8080box.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 servicefrontend_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 serverawait box.exec.command("npx http-server /work -p 3000 &")// Create a public URL for testingconst publicUrl = await box.getPublicURL(3000)// Run your tests against the public URLconst response = await fetch(publicUrl.url)console.log(response.status) // 200// Clean upawait box.deletePublicURL(3000)await box.delete()

import httpxfrom upstash_box import Boxbox = Box.create(runtime="node")# Start test serverbox.exec.command("npx http-server /work -p 3000 &")# Create a public URL for testingpublic_url = box.get_public_url(3000)# Run your tests against the public URLresponse = httpx.get(public_url.url)print(response.status_code)  # 200# Clean upbox.delete_public_url(3000)box.delete()

Note

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#