# Public URLs

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.

<CodeGroup>
```typescript box.ts
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
```

```python box.py
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
```
</CodeGroup>

### Add authentication

Protect your public URL with bearer token or basic authentication.

<CodeGroup>
```typescript box.ts
// 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..."
```

```python box.py
# 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..."
```
</CodeGroup>

---

## API

### Create Public URL

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

<CodeGroup>
```typescript box.ts
const publicUrl = await box.getPublicURL(3000)

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

```python box.py
public_url = box.get_public_url(3000)

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

#### With Bearer Token

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

<CodeGroup>
```typescript box.ts
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
```

```python box.py
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
```
</CodeGroup>

#### With Basic Authentication

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

<CodeGroup>
```typescript box.ts
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
```

```python box.py
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
```
</CodeGroup>

#### With Both Auth Methods

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

<CodeGroup>
```typescript box.ts
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..."
```

```python box.py
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..."
```
</CodeGroup>

---

### List Public URLs

Get all active public URLs for this box.

<CodeGroup>
```typescript box.ts
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 },
// ]
```

```python box.py
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),
# ]
```
</CodeGroup>

---

### Delete Public URL

Remove a public URL by port number.

<CodeGroup>
```typescript box.ts
await box.deletePublicURL(3000)
```

```python box.py
box.delete_public_url(3000)
```
</CodeGroup>

---

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

<CodeGroup>
```typescript box.ts
// 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
```

```python box.py
# 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
```
</CodeGroup>

### 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](#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](/box/overall/quickstart#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.

<CodeGroup>
```typescript box.ts
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
```

```python box.py
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
```
</CodeGroup>

For the app to answer on its own after a resume, the box needs to start its server again. An [init command](/box/overall/quickstart#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.

<CodeGroup>
```typescript box.ts
await box.pause()

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

```python box.py
box.pause()

# This will resume the box
public_url = box.get_public_url(3000)
```
</CodeGroup>

---

## Examples

### Expose an agent-built app

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

<CodeGroup>
```typescript box.ts
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" }
```

```python box.py
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"}
```
</CodeGroup>

### Share a secure public URL

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

<CodeGroup>
```typescript box.ts
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
```

```python box.py
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
```
</CodeGroup>

### Multi-port application

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

<CodeGroup>
```typescript box.ts
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}`)
```

```python box.py
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}")
```
</CodeGroup>

### Temporary testing public URL

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

<CodeGroup>
```typescript box.ts
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()
```

```python box.py
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()
```
</CodeGroup>

<Note>The SDK still supports `getPreviewUrl`, `listPreviews`, and `deletePreview`, but they are deprecated aliases for `getPublicURL`, `listPublicURLs`, and `deletePublicURL`.</Note>