Daytona sandbox environments require an API key in config or

Error message

Daytona sandbox environments require an API key in config or DAYTONA_API_KEY.

What it means

Thrown by resolveApiKey when neither the driver config's apiKey field nor the DAYTONA_API_KEY environment variable provides a non-empty API key. Every Daytona client construction requires a resolved key, so absence fails immediately at client creation.

Source

Thrown at packages/plugins/sandbox-providers/daytona/src/plugin.ts:248

    // Daytona session per lease and dispatches every command into it. The flag
    // stays default off until a live leak soak passes.
    useSessions: raw.useSessions === true,
    // Log-stream opt-in. Default OFF. When off, the session dispatch polls the
    // exit code every 50 ms and then reads the logs one time. When on, the
    // dispatch streams stdout and stderr from the callback log form and reads
    // the exit code one time after the stream ends. The flag stays default off
    // until a live soak passes.
    useLogStream: raw.useLogStream === true,
  };
}

function resolveApiKey(config: DaytonaDriverConfig): string {
  if (config.apiKey) {
    return config.apiKey;
  }
  const envApiKey = process.env.DAYTONA_API_KEY?.trim() ?? "";
  if (!envApiKey) {
    throw new Error("Daytona sandbox environments require an API key in config or DAYTONA_API_KEY.");
  }
  return envApiKey;
}

function createDaytonaClient(config: DaytonaDriverConfig): Daytona {
  const clientConfig: DaytonaConfig = {
    apiKey: resolveApiKey(config),
  };
  if (config.apiUrl) clientConfig.apiUrl = config.apiUrl;
  if (config.target) clientConfig.target = config.target;
  return new Daytona(clientConfig);
}

function buildResources(config: DaytonaDriverConfig): Resources | undefined {
  if (config.cpu == null && config.memory == null && config.disk == null && config.gpu == null) {
    return undefined;
  }
  return {

View on GitHub (pinned to 67001ec6eb)

Solutions

Set DAYTONA_API_KEY in the environment of the process running Paperclip (export DAYTONA_API_KEY=..., or add to .env / CI secret).
Alternatively, provide apiKey in the Daytona driver config passed to the plugin.
Verify the key is non-empty after trimming (no whitespace-only value).
Restart the server/worker after setting the env var so it is read at startup.

Example fix

# before: no key configured
# after: export before starting the server
export DAYTONA_API_KEY=dts_yourkey
pnpm dev

Defensive patterns

Strategy: validation

Validate before calling

function hasDaytonaApiKey(config: { apiKey?: string | null }): boolean {
  return Boolean(config.apiKey || (process.env.DAYTONA_API_KEY ?? '').trim());
}

Prevention

Set DAYTONA_API_KEY in the process environment before starting the server/worker.
Alternatively, configure apiKey in the Daytona driver config.
Verify CI/runtime secrets inject the key into the running process.

When it happens

Trigger: createDaytonaClient is called (during sandbox creation, probe, or interactive setup) with config.apiKey falsy AND process.env.DAYTONA_API_KEY empty/undefined/whitespace-only.

Common situations: First-time setup without setting DAYTONA_API_KEY; .env file not loaded in the process; the environment plugin config omits apiKey; CI runner missing the secret; the key was set in a different shell than the one running the server.

Related errors

AI-assisted analysis of paperclipai/paperclip@67001ec6eb (2026-08-12). Data as JSON: /api/errors/efde29fb9ce2e1c4. Report an issue: GitHub.