sandbox-cli-detector

sandbox-cli-detector

Detect whether the current process is running inside a sandboxed developer environment.

Please open an issue if your sandbox is not properly detected.

Installation

npm install sandbox-cli-detector

Usage

import { detectSandbox } from "sandbox-cli-detector";

const result = detectSandbox();

if (result.detected && result.sandbox) {
  console.log("The name of the sandbox is:", result.sandbox.name);
} else {
  console.log("This program is not running inside a known sandbox");
}

Supported sandboxes

Officially supported sandbox environments:

Name	ID
Replit	replit
bolt.new	bolt
E2B	e2b
Vercel Sandbox	vercel-sandbox
Daytona	daytona
Modal	modal
Cloudflare Sandbox	cloudflare-sandbox
GitHub Codespaces	codespaces
CodeSandbox	codesandbox

Detection is data-driven. The exact environment variables for each sandbox live in src/sandboxes.ts.

API

detectSandbox(options?)

Returns a detection result:

{
  detected: true,
  sandbox: {
    id: "e2b",
    name: "E2B"
  }
}

When no sandbox is detected, it returns { detected: false }.

result.detected

A boolean that is true when the process is running inside a known sandbox and false otherwise.

result.sandbox.id

A stable identifier for the detected sandbox. Prefer comparing this value over result.sandbox.name.

result.sandbox.name

The display name of the detected sandbox. This may change without it being a breaking change.

isRunningInSandbox(options?)

A convenience function that returns result.detected as a boolean:

import { isRunningInSandbox } from "sandbox-cli-detector";

if (isRunningInSandbox()) {
  // Adjust CLI behavior for sandboxed execution.
}

Custom sandboxes

Pass custom definitions when you need to detect an internal environment:

import { defaultSandboxes, detectSandbox } from "sandbox-cli-detector";

const result = detectSandbox({
  sandboxes: [
    {
      id: "internal",
      name: "Internal Sandbox",
      env: [{ name: "INTERNAL_SANDBOX", value: "true" }],
    },
    ...defaultSandboxes,
  ],
});

Each environment signal matches either an exact value or any non-empty value when value is omitted. If multiple sandboxes match, the first definition is returned.

CLI

The package also ships a CLI:

npx sandbox-cli-detector
npx sandbox-cli-detector --json
npx sandbox-cli-detector --quiet

It exits with 0 when a sandbox is detected and 1 otherwise.

Contributing detections

Please include the platform name, a redacted env | sort captured inside the platform, and the variables that identify it.

License

MIT