Daytona

View as Markdown Edit on GitHub Docs at 1675df8

Daytona lets Termbridge run your terminal and preview in a cloud sandbox. Use this when you want a reproducible environment, a cloud preview, or to keep your laptop idle.

Requirements

A Daytona API key
A repository URL the sandbox can clone
Git credentials if the repo is private

Quick start

Set the backend to Daytona and provide the repo configuration:

Shell

export TERMBRIDGE_BACKEND=sandbox-daytona
export TERMBRIDGE_DAYTONA_API_KEY=your_key
export TERMBRIDGE_SANDBOX_REPO=https://github.com/you/your-repo.git
export TERMBRIDGE_SANDBOX_BRANCH=main
export TERMBRIDGE_SANDBOX_PATH=your-repo
export TERMBRIDGE_SANDBOX_NAME=termbridge-sandbox
export TERMBRIDGE_SANDBOX_PUBLIC=true
export TERMBRIDGE_SANDBOX_PREVIEW_PORT=5173
export TERMBRIDGE_SANDBOX_DELETE_ON_EXIT=true

Then run Termbridge as usual:

Shell

npx termbridge

Always set TERMBRIDGE_SANDBOX_REPO (or --sandbox-repo). When it is missing, Termbridge currently falls back to a built-in default repository that is not publicly accessible, so the sandbox is created and the clone fails (#2).

Daytona connection

Variable	Purpose
`TERMBRIDGE_DAYTONA_API_KEY`	Your Daytona API key
`TERMBRIDGE_DAYTONA_API_URL`	API endpoint (default `https://app.daytona.io/api`)
`TERMBRIDGE_DAYTONA_TARGET`	Daytona target region (optional)

These are passed to the Daytona SDK. When one of them is unset, the SDK falls back to its own DAYTONA_API_KEY, DAYTONA_API_URL or DAYTONA_TARGET variable.

Direct sandbox mode (no tunnel)

Direct mode runs the Termbridge server inside the sandbox and skips Cloudflare entirely. The share URL is the Daytona preview link to the sandboxed server.

Shell

export TERMBRIDGE_BACKEND=sandbox-daytona
export TERMBRIDGE_SANDBOX_DIRECT=true
export TERMBRIDGE_SANDBOX_SERVER_PORT=8080

TERMBRIDGE_SANDBOX_SERVER_PORT (or --port) defaults to 8080. Direct mode creates a public sandbox unless you set TERMBRIDGE_SANDBOX_PUBLIC=false, and the UI hides the terminal switcher.

You can still enable preview by setting TERMBRIDGE_SANDBOX_PREVIEW_PORT; in direct mode it is forwarded as the server --proxy port.

Repository cloning

Termbridge will create a sandbox and clone your repo into the sandbox working directory.

Use these settings:

Variable	Purpose
`TERMBRIDGE_SANDBOX_REPO`	Repo URL to clone (always set it, see the quick start)
`TERMBRIDGE_SANDBOX_BRANCH`	Branch to check out (optional)
`TERMBRIDGE_SANDBOX_PATH`	Path for the repo in the sandbox (optional)
`TERMBRIDGE_SANDBOX_NAME`	Sandbox name (optional, defaults to `termbridge-<random hex>`)

If TERMBRIDGE_SANDBOX_PATH is not set, Termbridge derives it from the repo name.

Private repositories

Provide git credentials when cloning private repos:

Shell

export TERMBRIDGE_SANDBOX_GIT_USERNAME=your_github_username
export TERMBRIDGE_SANDBOX_GIT_TOKEN=your_github_token

TERMBRIDGE_SANDBOX_GIT_PASSWORD is also supported and overrides the token if set.

Coding agents

Termbridge can install coding agents inside the sandbox and sync your local auth so they are ready immediately.

See the Coding agents guide for the full setup, automatic mode, and security details.

Preview mode

To show the preview view, set TERMBRIDGE_SANDBOX_PREVIEW_PORT to the port your dev server uses inside the sandbox.

For Vite, make sure you bind to all interfaces:

Shell

npm run dev -- --host 0.0.0.0 --port 5173

Termbridge fetches the Daytona preview link and proxies it through the Termbridge server so the preview loads inside the UI.

Public vs private sandboxes

Variable	What it does
`TERMBRIDGE_SANDBOX_PUBLIC=true`	Creates a public sandbox
`TERMBRIDGE_SANDBOX_PUBLIC=false`	Creates a private sandbox

When the variable is unset, sandboxes are private, except in direct mode, where they are public.

For private sandboxes, Termbridge forwards the preview token automatically when proxying the preview.

Cleanup and lifecycle

To delete sandboxes when Termbridge exits:

Shell

export TERMBRIDGE_SANDBOX_DELETE_ON_EXIT=true

For short-lived or test sandboxes, use a prefix:

Shell

export TERMBRIDGE_SANDBOX_NAME=termbridge-test-$(date +%s)
export TERMBRIDGE_SANDBOX_DELETE_ON_EXIT=true

This keeps sandbox usage under control and avoids disk quota issues.

CLI flags

You can also configure Daytona via flags. A flag takes precedence over the matching environment variable.

Flag	Environment variable	Purpose
`--backend sandbox-daytona`	`TERMBRIDGE_BACKEND`	Use the Daytona backend
`--sandbox-repo <url>`	`TERMBRIDGE_SANDBOX_REPO`	Repo URL
`--sandbox-branch <branch>`	`TERMBRIDGE_SANDBOX_BRANCH`	Branch
`--sandbox-path <path>`	`TERMBRIDGE_SANDBOX_PATH`	Repo path in sandbox
`--sandbox-name <name>`	`TERMBRIDGE_SANDBOX_NAME`	Sandbox name
`--sandbox-preview-port <port>`	`TERMBRIDGE_SANDBOX_PREVIEW_PORT`	Preview port
`--sandbox-public`	`TERMBRIDGE_SANDBOX_PUBLIC=true`	Create a public sandbox
`--sandbox-direct`	`TERMBRIDGE_SANDBOX_DIRECT=true`	Run the server inside the sandbox (no tunnel)

There is no flag for a private sandbox; use TERMBRIDGE_SANDBOX_PUBLIC=false. The built-in termbridge --help output still shows --daytona-* names and --backend daytona, which are rejected (#1).

Troubleshooting

Preview view is blank

Ensure the dev server is running inside the sandbox.
Use --host 0.0.0.0 so the preview port is reachable.
Confirm TERMBRIDGE_SANDBOX_PREVIEW_PORT matches the dev server port.

Sandbox creation fails with quota errors

Delete old sandboxes in the Daytona dashboard.
Use TERMBRIDGE_SANDBOX_DELETE_ON_EXIT=true for short-lived sessions.

Repo clone fails

Double-check repo URL, branch, and credentials.
Ensure the Git token has repo read access.