# sandbox-cli-detector

> Detect whether a CLI is running inside a sandboxed environment

Latest version **0.2.0** (published 2026-07-18) · MIT license · 0 weekly downloads

## Install

```sh
npm install sandbox-cli-detector
pnpm add sandbox-cli-detector
yarn add sandbox-cli-detector
bun add sandbox-cli-detector
```

Provides the command `sandbox-cli-detector`.

## Health

**Score 75/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; has provenance; recently updated; high maintenance score; high quality score.

Warnings: low downloads; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.2.0 |
| Published | 2026-07-18 |
| First published | 2026-07-17 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=18.18 |
| Dependencies | 0 |
| Unpacked size | 31.2 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 1 |
| Author | David Mokos |
| Maintainers | davidmokos |
| Keywords | sandbox, detect, e2b, vercel-sandbox, replit, daytona, modal, codespaces, gitpod, cli, environment |

## Links

- npm: https://www.npmjs.com/package/sandbox-cli-detector
- Repository: https://github.com/davidmokos/sandbox-cli-detector
- Homepage: https://github.com/davidmokos/sandbox-cli-detector#readme
- Issues: https://github.com/davidmokos/sandbox-cli-detector/issues
- npm.io page: https://npm.io/package/sandbox-cli-detector

## Alternatives

- [replicas-cli](https://npm.io/package/replicas-cli.md) — 3.0K weekly downloads
- [env-contract](https://npm.io/package/env-contract.md) — 133 weekly downloads
- [@openveo/api](https://npm.io/package/@openveo/api.md) — 61 weekly downloads
- [@ryniaubenpm2/cumque-error-reiciendis](https://npm.io/package/@ryniaubenpm2/cumque-error-reiciendis.md) — 54 weekly downloads
- [ts-global-type-extra](https://npm.io/package/ts-global-type-extra.md) — 11 weekly downloads

## Recent versions

- 0.2.0 (latest) — 2026-07-18
- 0.1.1 — 2026-07-17
- 0.1.0 — 2026-07-17

## README

# sandbox-cli-detector

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

Please [open an issue](https://github.com/davidmokos/sandbox-cli-detector/issues/new)
if your sandbox is not properly detected.

[![npm](https://img.shields.io/npm/v/sandbox-cli-detector.svg)](https://www.npmjs.com/package/sandbox-cli-detector)
[![Tests](https://github.com/davidmokos/sandbox-cli-detector/actions/workflows/test.yml/badge.svg)](https://github.com/davidmokos/sandbox-cli-detector/actions/workflows/test.yml)
[![License](https://img.shields.io/npm/l/sandbox-cli-detector.svg)](LICENSE)

## Installation

```sh
npm install sandbox-cli-detector
```

## Usage

```ts
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](https://replit.com) | `replit` |
| [bolt.new](https://bolt.new) | `bolt` |
| [E2B](https://e2b.dev) | `e2b` |
| [Vercel Sandbox](https://vercel.com/docs/sandbox) | `vercel-sandbox` |
| [Daytona](https://daytona.io) | `daytona` |
| [Modal](https://modal.com) | `modal` |
| [Cloudflare Sandbox](https://developers.cloudflare.com/sandbox/) | `cloudflare-sandbox` |
| [GitHub Codespaces](https://github.com/features/codespaces) | `codespaces` |
| [CodeSandbox](https://codesandbox.io) | `codesandbox` |

Detection is data-driven. The exact environment variables for each sandbox
live in [`src/sandboxes.ts`](src/sandboxes.ts).

## API

### `detectSandbox(options?)`

Returns a detection result:

```ts
{
  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:

```ts
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:

```ts
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:

```sh
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](LICENSE)

---
_Source: https://npm.io/package/sandbox-cli-detector · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._