Using a Custom Proxy for Daytona Previews

Last updated: September 5, 2025

Daytona’s default preview links work out of the box. A custom proxy is for teams that need tighter control, advanced authentication, or fully branded preview experiences. This guide builds on the core documentation with deeper details for production use.

Why Go Beyond the Defaults

  • Unified access control: reuse your organization’s existing login/session system.

  • Preview lifecycle automation: auto-start stopped sandboxes on first request.

  • Consistent UX: replace warnings or errors with branded pages.

  • Security hardening: decide exactly which headers and tokens are accepted.

Implementation Patterns

1. Authentication Flows

  • Validate sessions before forwarding to a sandbox.

  • Enforce role-based access: e.g. allow only project members to open previews.

  • Map user sessions to sandbox tokens securely — never expose raw tokens client-side.

2. Sandbox Lifecycle Handling

  • Detect stopped sandboxes.

  • Use the SDK or API to trigger sandbox.start().

  • Poll until state=STARTED, then forward the request.

  • Add retry limits and clear error messages for users if startup fails.

3. Header Control

Daytona allows preview behavior overrides with headers:

X-Daytona-Skip-Preview-Warning: trueX-Daytona-Disable-CORS: true

Use these carefully. Always validate that requests originate from your proxy before applying.

4. Error Management

Instead of generic 502/timeout responses:

  • Serve a page with status, logs, or next steps.

  • Distinguish between “sandbox not started” vs “sandbox crashed” for clearer feedback.

Operational Considerations

  • Scaling: design your proxy to handle concurrent preview traffic without bottlenecks.

  • Security: keep API keys and sandbox tokens in secure storage. Rotate regularly.

  • Monitoring: track request volumes, sandbox startup times, and failure rates.

  • Audit: log which user accessed which preview, useful for compliance and debugging.

When a Custom Proxy Is Overkill

If you don’t need custom authentication, lifecycle automation, or branding, use Daytona’s managed preview links. They are simpler to operate and fully maintained.

Next Steps

  1. Clone a Daytona proxy sample.

  2. Add authentication logic matching your environment.

  3. Extend lifecycle handling and custom error responses.

  4. Deploy under your domain, then test with private and public previews.