Clarify preview url usage

Author: ghostwriternr

src/content/docs/sandbox/concepts/index.mdx

@@ -7,8 +7,6 @@ sidebar:
 
 These pages explain how the Sandbox SDK works, why it's designed the way it is, and the concepts you need to understand to use it effectively.
 
-## Available concepts
-
 - [Architecture](/sandbox/concepts/architecture/) - How the SDK is structured and why
 - [Sandbox lifecycle](/sandbox/concepts/sandboxes/) - Understanding sandbox states and behavior
 - [Container runtime](/sandbox/concepts/containers/) - How code executes in isolated containers

src/content/docs/sandbox/concepts/preview-urls.mdx

@@ -12,7 +12,7 @@ Preview URLs work in local development without configuration. For production, yo
 Preview URLs provide public HTTPS access to services running inside sandboxes. When you expose a port, you get a unique URL that proxies requests to your service.
 
 ```typescript
-await sandbox.startProcess('python -m http.server 8000');
+await sandbox.startProcess("python -m http.server 8000");
 const exposed = await sandbox.exposePort(8000);
 
 console.log(exposed.exposedAt);
@@ -29,7 +29,7 @@ console.log(exposed.exposedAt);
 
 **Local development**: `http://localhost:8787/...`
 
-URLs remain stable for a given sandbox ID and port. You can share, bookmark, or use them in webhooks.
+Preview URLs remain stable while a port is exposed and can be shared during that time. However, if you unexpose and re-expose a port, a new random token is generated and the URL changes. For persistent URLs, keep ports exposed for the duration you need them accessible.
 
 ## Request Routing
 
@@ -39,14 +39,14 @@ You must call `proxyToSandbox()` first in your Worker's fetch handler to route p
 import { proxyToSandbox, getSandbox } from "@cloudflare/sandbox";
 
 export default {
-  async fetch(request, env) {
-    // Handle preview URL routing first
-    const proxyResponse = await proxyToSandbox(request, env);
-    if (proxyResponse) return proxyResponse;
-
-    // Your application routes
-    // ...
-  }
+	async fetch(request, env) {
+		// Handle preview URL routing first
+		const proxyResponse = await proxyToSandbox(request, env);
+		if (proxyResponse) return proxyResponse;
+
+		// Your application routes
+		// ...
+	},
 };
 ```
 
@@ -57,11 +57,11 @@ Requests flow: Browser → Your Worker → Durable Object (sandbox) → Your Ser
 Expose multiple services simultaneously:
 
 ```typescript
-await sandbox.startProcess('node api.js');      // Port 3000
-await sandbox.startProcess('node admin.js');    // Port 3001
+await sandbox.startProcess("node api.js"); // Port 3000
+await sandbox.startProcess("node admin.js"); // Port 3001
 
-const api = await sandbox.exposePort(3000, { name: 'api' });
-const admin = await sandbox.exposePort(3001, { name: 'admin' });
+const api = await sandbox.exposePort(3000, { name: "api" });
+const admin = await sandbox.exposePort(3001, { name: "admin" });
 
 // Each gets its own URL:
 // https://3000-abc123.example.com
@@ -71,7 +71,6 @@ const admin = await sandbox.exposePort(3001, { name: 'admin' });
 ## What Works
 
 - HTTP/HTTPS requests
-- WebSocket (WSS) via HTTP upgrade
 - Server-Sent Events
 - All HTTP methods (GET, POST, PUT, DELETE, etc.)
 - Request and response headers
@@ -80,15 +79,25 @@ const admin = await sandbox.exposePort(3001, { name: 'admin' });
 
 - Raw TCP/UDP connections
 - Custom protocols (must wrap in HTTP)
-- Ports 80/443 (use 1024+)
+- WebSocket connections
+- Ports outside range 1024-65535
+- Port 3000 (used internally by the SDK)
 
 ## Security
 
 :::caution
-Preview URLs are publicly accessible. Anyone with the URL can access your service.
+Preview URLs are publicly accessible by default, but require a valid access token that is generated when you expose a port.
 :::
 
-Add authentication in your service:
+**Built-in security**:
+
+- **Token-based access** - Each exposed port gets a unique token in the URL (for example, `https://8080-sandbox-abc123token.example.com`)
+- **HTTPS in production** - All traffic is encrypted with automatic TLS
+- **Unpredictable URLs** - Tokens are randomly generated and difficult to guess
+
+**Add application-level authentication**:
+
+For additional security, implement authentication within your application:
 
 ```python
 from flask import Flask, request, abort
@@ -97,16 +106,14 @@ app = Flask(__name__)
 
 @app.route('/data')
 def get_data():
-    token = request.headers.get('Authorization')
-    if token != 'Bearer secret-token':
+    # Check for your own authentication token
+    auth_token = request.headers.get('Authorization')
+    if auth_token != 'Bearer your-secret-token':
         abort(401)
     return {'data': 'protected'}
 ```
 
-**Security features**:
-- All traffic is HTTPS (automatic TLS)
-- URLs use random sandbox IDs (hard to guess)
-- You control authentication in your service
+This adds a second layer of security on top of the URL token.
 
 ## Troubleshooting
 
@@ -123,10 +130,10 @@ const ports = await sandbox.getExposedPorts();
 
 // 3. Is service binding to 0.0.0.0 (not 127.0.0.1)?
 // Good:
-app.run(host='0.0.0.0', port=3000)
+app.run((host = "0.0.0.0"), (port = 3000));
 
 // Bad (localhost only):
-app.run(host='127.0.0.1', port=3000)
+app.run((host = "127.0.0.1"), (port = 3000));
 ```
 
 ### Production Errors
@@ -135,7 +142,7 @@ For custom domain issues, see [Production Deployment troubleshooting](/sandbox/g
 
 ### Local Development
 
-:::caution[Local development only]
+:::caution[Local development limitation]
 When using `wrangler dev`, you must expose ports in your Dockerfile:
 
 ```dockerfile

src/content/docs/sandbox/configuration/index.mdx

@@ -14,91 +14,31 @@ Configure your Sandbox SDK deployment with Wrangler, customize container images,
 <LinkTitleCard
 	title="Wrangler configuration"
 	href="/sandbox/configuration/wrangler/"
-	icon="document"
+	icon="puzzle"
 >
-	Configure Durable Objects bindings, container images, and Worker settings in wrangler.jsonc.
+	Configure Durable Objects bindings, container images, and Worker settings in
+	wrangler.jsonc.
 </LinkTitleCard>
 
 <LinkTitleCard
 	title="Dockerfile reference"
 	href="/sandbox/configuration/dockerfile/"
-	icon="wrench"
+	icon="seti:docker"
 >
-	Customize the sandbox container image with your own packages, tools, and configurations.
+	Customize the sandbox container image with your own packages, tools, and
+	configurations.
 </LinkTitleCard>
 
 <LinkTitleCard
 	title="Environment variables"
 	href="/sandbox/configuration/environment-variables/"
-	icon="gear"
+	icon="seti:powershell"
 >
 	Pass configuration and secrets to your sandboxes using environment variables.
 </LinkTitleCard>
 
 </CardGrid>
 
-## Quick reference
-
-### Essential wrangler.jsonc settings
-
-```jsonc
-{
-  "name": "my-worker",
-  "main": "src/index.ts",
-  "compatibility_date": "2024-09-02",
-  "compatibility_flags": ["nodejs_compat"],
-  "durable_objects": {
-    "bindings": [
-      {
-        "name": "Sandbox",
-        "class_name": "Sandbox",
-        "script_name": "@cloudflare/sandbox"
-      }
-    ]
-  },
-  "containers": [
-    {
-      "binding": "CONTAINER",
-      "image": "ghcr.io/cloudflare/sandbox-runtime:latest"
-    }
-  ]
-}
-```
-
-### Common Dockerfile customizations
-
-```dockerfile
-FROM ghcr.io/cloudflare/sandbox-runtime:latest
-
-# Install additional Python packages
-RUN pip install scikit-learn tensorflow pandas
-
-# Install Node.js packages globally
-RUN npm install -g typescript ts-node
-
-# Install system packages
-RUN apt-get update && apt-get install -y postgresql-client
-
-# Add custom scripts
-COPY ./scripts /usr/local/bin/
-```
-
-### Environment variables
-
-```typescript
-// Pass to sandbox at creation
-const sandbox = getSandbox(env.Sandbox, 'my-sandbox');
-
-// Configure environment for commands
-await sandbox.exec('node app.js', {
-  env: {
-    NODE_ENV: 'production',
-    API_KEY: env.API_KEY,
-    DATABASE_URL: env.DATABASE_URL
-  }
-});
-```
-
 ## Related resources
 
 - [Get Started guide](/sandbox/get-started/) - Initial setup walkthrough

src/content/docs/sandbox/guides/background-processes.mdx

@@ -3,6 +3,7 @@ title: Run background processes
 pcx_content_type: how-to
 sidebar:
   order: 3
+description: Start and manage long-running services and applications.
 ---
 
 import { TypeScriptExample } from "~/components";

src/content/docs/sandbox/guides/code-execution.mdx

@@ -3,6 +3,7 @@ title: Use code interpreter
 pcx_content_type: how-to
 sidebar:
   order: 5
+description: Execute Python and JavaScript code with rich outputs.
 ---
 
 import { TypeScriptExample } from "~/components";

src/content/docs/sandbox/guides/execute-commands.mdx

@@ -3,6 +3,7 @@ title: Execute commands
 pcx_content_type: how-to
 sidebar:
   order: 1
+description: Run commands with streaming output, error handling, and shell access.
 ---
 
 import { TypeScriptExample } from "~/components";

src/content/docs/sandbox/guides/expose-services.mdx

@@ -3,6 +3,7 @@ title: Expose services
 pcx_content_type: how-to
 sidebar:
   order: 4
+description: Create preview URLs and expose ports for web services.
 ---
 
 import { TypeScriptExample } from "~/components";

src/content/docs/sandbox/guides/git-workflows.mdx

@@ -3,6 +3,7 @@ title: Work with Git
 pcx_content_type: how-to
 sidebar:
   order: 6
+description: Clone repositories, manage branches, and automate Git operations.
 ---
 
 import { TypeScriptExample } from "~/components";

src/content/docs/sandbox/guides/index.mdx

@@ -5,17 +5,11 @@ sidebar:
   order: 4
 ---
 
-These guides show you how to solve specific problems and implement features with the Sandbox SDK. Each guide focuses on a particular task and provides practical, production-ready solutions.
+import { ResourcesBySelector } from "~/components";
 
-## Available guides
+These guides show you how to solve specific problems and implement features with the Sandbox SDK. Each guide focuses on a particular task and provides practical, production-ready solutions.
 
-- [Execute commands](/sandbox/guides/execute-commands/) - Run commands with streaming output, error handling, and shell access
-- [Manage files](/sandbox/guides/manage-files/) - Read, write, organize, and synchronize files in the sandbox
-- [Run background processes](/sandbox/guides/background-processes/) - Start and manage long-running services and applications
-- [Expose services](/sandbox/guides/expose-services/) - Create preview URLs and expose ports for web services
-- [Use code interpreter](/sandbox/guides/code-execution/) - Execute Python and JavaScript code with rich outputs
-- [Work with Git](/sandbox/guides/git-workflows/) - Clone repositories, manage branches, and automate Git operations
-- [Stream output](/sandbox/guides/streaming-output/) - Handle real-time output from commands and processes
+<ResourcesBySelector directory="sandbox/guides/" types={["how-to"]} />
 
 ## Related resources
 

src/content/docs/sandbox/guides/manage-files.mdx

@@ -3,6 +3,7 @@ title: Manage files
 pcx_content_type: how-to
 sidebar:
   order: 2
+description: Read, write, organize, and synchronize files in the sandbox.
 ---
 
 import { TypeScriptExample } from "~/components";