Skip to main content
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

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

​
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)
// [
//   { url: "https://{BOX_ID}-3000.preview.box.upstash.com", port: 3000 },
//   { 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)

​
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

​
Public URL Lifecycle

Public URLs expire automatically when:
  • The box is paused
  • The box is deleted

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

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

​
Share a secure public URL

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

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

​
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()
The SDK still supports getPreviewUrl, listPreviews, and deletePreview, but they are deprecated aliases for getPublicUrl, listPublicUrls, and deletePublicUrl.