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

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

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

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

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

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

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 },// ]

Delete Public URL#

Remove a public URL by port number.

await box.deletePublicURL(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

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 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(60_000) })console.log(response.status) // 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)

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

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

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

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

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#