Skip to content

daytona.md

Latest commit

 

History

History
153 lines (118 loc) · 6.4 KB

daytona.md

File metadata and controls

153 lines (118 loc) · 6.4 KB
Raw

Daytona

Read when:

  • choosing provider: daytona;
  • configuring Daytona authentication, snapshots, or SSH access;
  • understanding how the Daytona backend differs from a plain SSH-lease provider.

provider: daytona provisions Daytona sandboxes and supports Linux targets exclusively. Direct mode is hybrid: warmup, run, list, status, and stop drive Daytona's SDK and toolbox APIs, while ssh mints a short-lived SSH token. Brokered mode keeps the API key in the coordinator, returns an expiring SSH identity to the authorized client, and uses Crabbox's normal SSH/rsync run path.

Authentication

Crabbox accepts credentials from two sources, in precedence order:

  1. Explicit Crabbox config or environment variables (highest priority).
  2. The active Daytona CLI profile (used only when no explicit token is set).

Log in with the Daytona CLI to populate a profile:

daytona login

Crabbox reads the active profile's API key and active organization ID from the Daytona CLI config when no explicit token is provided.

To set credentials directly, provide an API key:

export DAYTONA_API_KEY=...

or a JWT plus organization ID:

export DAYTONA_JWT_TOKEN=...
export DAYTONA_ORGANIZATION_ID=...

DAYTONA_ORGANIZATION_ID is required whenever JWT auth is used. If no API key, JWT token, or authenticated CLI profile is found, lease operations fail with a configuration error.

Each variable also has a CRABBOX_-prefixed form that takes precedence over the bare Daytona name (useful when other tooling already owns the unprefixed variable):

Crabbox-prefixed Daytona name Config key
CRABBOX_DAYTONA_API_KEY DAYTONA_API_KEY daytona.apiKey
CRABBOX_DAYTONA_JWT_TOKEN DAYTONA_JWT_TOKEN daytona.jwtToken
CRABBOX_DAYTONA_ORGANIZATION_ID DAYTONA_ORGANIZATION_ID daytona.organizationId
CRABBOX_DAYTONA_API_URL DAYTONA_API_URL daytona.apiUrl

The API URL defaults to https://app.daytona.io/api.

For brokered mode, configure the coordinator instead of client auth:

DAYTONA_CRABBOX_KEY               # required secret
CRABBOX_DAYTONA_SNAPSHOT          # optional shared snapshot
CRABBOX_DAYTONA_TARGET            # optional compute target
CRABBOX_DAYTONA_SSH_ACCESS_MINUTES # minimum token TTL; default 120

The coordinator accepts no Daytona API credential from lease requests.

Config

The Daytona integration is snapshot-first: the snapshot owns CPU, memory, disk, and installed tooling. Crabbox does not expose Daytona resource flags, so --class and --type are rejected for provider=daytona — size the sandbox in the snapshot instead.

provider: daytona
target: linux
daytona:
  snapshot: my-app-ready
  target: "" # optional Daytona compute target
  user: daytona
  workRoot: /home/daytona/crabbox
  sshGatewayHost: ssh.app.daytona.io # fallback when the API omits an SSH command
  sshAccessMinutes: 30 # SSH access token TTL
Config key Flag Default
daytona.snapshot --daytona-snapshot (required)
daytona.target --daytona-target (empty)
daytona.user --daytona-user daytona
daytona.workRoot --daytona-work-root /home/daytona/crabbox
daytona.sshGatewayHost --daytona-ssh-gateway-host ssh.app.daytona.io
daytona.sshAccessMinutes --daytona-ssh-access-minutes 30
daytona.apiUrl --daytona-api-url https://app.daytona.io/api

A snapshot is required; warmup/run fail without --daytona-snapshot or daytona.snapshot.

Examples

# Lease a sandbox from a snapshot and keep it warm.
crabbox warmup --provider daytona --daytona-snapshot my-app-ready

# Sync the local checkout into an existing lease and run a command.
crabbox run --provider daytona --id swift-crab -- pnpm test

# Open an interactive shell (mints a short-lived SSH token).
crabbox ssh --provider daytona --id swift-crab

# End the lease.
crabbox stop --provider daytona swift-crab

Behavior

  • warmup creates a Daytona sandbox from daytona.snapshot, waits for it to become ready, records Crabbox labels, then prints a normal Crabbox lease ID and slug.
  • run --id resolves a Daytona sandbox, uploads a Crabbox sync-manifest archive through Daytona toolbox file APIs, extracts it in the sandbox, and executes the command through Daytona toolbox process APIs. The command transport is Daytona's SDK — not direct SSH.
  • list and status discover sandboxes only when Daytona labels bind them to the Daytona provider and a canonical Crabbox lease. Direct IDs with missing or mismatched ownership labels are rejected.
  • run --id, ssh, and stop additionally require a local claim that binds the exact Daytona sandbox ID to that lease. A legacy labelled sandbox with an unbound claim must be adopted explicitly with --reclaim from its owning repository before it can be reused or deleted.
  • ssh mints a fresh Daytona SSH access token (TTL daytona.sshAccessMinutes, default 30 minutes), parses the host and port from Daytona's returned SSH command (falling back to daytona.sshGatewayHost and port 22), and prints the token redacted as <token> unless --show-secret is passed.

Daytona is a hybrid backend: core rendering, lease labels, sync manifests, and repo claim checks stay Crabbox-owned, while the run transport is the Daytona SDK/toolbox. Actions runner hydration is not supported, because it requires a long-lived, directly SSH-reachable runner host.

In brokered mode the Worker creates and deletes the sandbox, verifies exact lease labels before destructive cleanup, refreshes the SSH token before expiry, and redacts that token from the portal. Workspaces and ready pools are disabled because they persist an SSH endpoint beyond the rotating credential.

See providers.md for the full provider matrix and capabilities.md for opt-in lease features.