Daytona SDK compatibility

The Daytona compatibility layer lets the Daytona SDK talk to Platinum. Point the SDK at a Platinum API key and Platinum's Daytona endpoint. Your Daytona code needs no changes.

The layer uses an ordinary Platinum API key. The native /v1/* API stays unchanged.

Setup

Set two environment variables:

export DAYTONA_API_KEY=pt_live_...
export DAYTONA_API_URL=https://api.platinum.dev/api/daytona

Then use the Daytona SDK as before. Daytona's snapshot parameter selects a Platinum template.

import { Daytona } from '@daytona/sdk';

const client = new Daytona();
const sandbox = await client.create({ snapshot: 'pt-base' });
const result = await sandbox.process.executeCommand('echo hello');
await sandbox.fs.uploadFile(Buffer.from('value'), '/tmp/value.txt');
console.log(result.result, String(await sandbox.fs.downloadFile('/tmp/value.txt')));
await client.delete(sandbox);

The matrix covers the layer's control-plane and toolbox handlers. An unsupported operation on the mounted surface returns a typed error (statusCode · message · code, HTTP 501). It never returns a false success. Services this layer does not host at all — the snapshot registry, the standalone volume API, object storage — are not routed and answer 404.

The machine-readable version lives in packages/compat-matrix.json.

Sandbox lifecycle

Capability	Status	Notes
Create, get, list, delete	Supported	List returns `{ items, nextCursor, total }`
Start / stop / pause / archive	Supported
Fork	Supported	Disk only — the fork cold-boots, so files survive and processes do not (details)
Resize (CPU / memory / disk)	Supported
Auto-stop timer	Supported	Minute granularity
Auto-archive / auto-delete timers	Supported	Rounded up to Platinum's day granularity
List filters and sort	Supported	id, name, labels, state, snapshot, region, CPU/memory/disk ranges, created-at range
Environment variables and labels	Supported	Labels are set at create and returned verbatim
Template selection (Daytona `snapshot`)	Supported	e.g. `pt-base`
Preview URL	Supported	Returns `url` + `token`
Network settings (read and update)	Supported	Maps to Platinum's egress policy, including `networkBlockAll` at create
Sandbox metrics	Supported	CPU, memory and disk telemetry for one sandbox
Set labels after create (`PUT /labels`)	Unsupported	No native backing — `PATCH /:id` renames only
Inline image build (`buildInfo`)	Unsupported	Rejected at create; name a template through `snapshot`
Standalone volume API	Unsupported	Platinum volumes are managed through the native API
Snapshot registry	Unsupported	Platinum has no named-image registry — `snapshot` on create names a template

Run code and commands

Capability	Status	Notes
Foreground command execution	Supported	`result` is the combined stdout+stderr, returned on completion, not streamed
Code execution	Supported	`argv` and `envs` are honoured
Chart artifacts	Always empty	The call succeeds; `artifacts.charts` is `[]` — nothing is ever extracted
Background / reconnectable sessions	Unsupported	See below
PTY	Unsupported	See below

Sessions and PTY are a platform gap, not a translation gap.

Guest exec kills the whole process group when the call returns, so no process survives for a later call to attach to. A PTY here dies with the connection, cannot be resized, and reports no exit code — nothing the layer can do would make the vendor's named, reconnectable session behave.

Files

Capability	Status	Notes
List, read, write, stat, mkdir, delete	Supported	`info` returns `owner` and `group` as empty strings: the guest reports no uid/gid, and `""` means unknown rather than asserting `root`
Upload	Supported	Both the original and the `upload-v2` multipart shapes
Bulk upload / bulk download	Supported	A bulk download takes up to 64 paths and 128 MiB
Move / rename	Supported
Permissions	Supported
Find	Supported	Searches file contents and returns matches with line numbers
Search	Supported	Searches file names by glob and returns `{ files: [] }`
Replace	Supported	The pattern is a regular expression, not a literal, matching the vendor contract. A path that does not exist is reported as a per-file failure
Git, LSP, GUI automation	Unsupported	No platform capability at any layer

find and search are not interchangeable.

find greps contents; search globs filenames. Calling the wrong one returns an empty result rather than an error.

Sandbox info

Capability	Status	Notes
User home directory, working directory	Supported
Toolbox version	Supported
System metrics	Supported	Guest CPU, memory and disk
List ports, port-in-use check	Supported	Reports listeners inside the guest

Secrets

Platinum org secrets are transform-only. The value is injected by the host egress proxy into an allowlisted request header, and never reaches the guest: no environment variable, no placeholder, no file. The vendor's secret model injects environment variables into the sandbox, so it cannot be honoured here. Use Platinum's native secrets API and the secrets scopes instead.

Verify a deployment

verify/compat/run.sh installs the real published SDK and drives it against a live control plane. It needs a Linux/KVM host attached, so it does not run on a control-plane-only machine.

PT_TOKEN=pt_live_... PT_API_URL=http://127.0.0.1:3000 ./verify/compat/run.sh