Different tradeoff
safe-install prioritizes local-only sandbox execution. Aikido Safe Chain prioritizes proxy filtering and package intelligence. Socket prioritizes hosted analysis, visibility, and workflow automation.
Docker sandbox · strong isolation · no telemetry
$ safe-install onboarding
Add AI agent instructions? Y
Add repo-local shims? Y
Add package.json guard? Y
Install global shims? n
Sandbox: docker
Minimum package age: 48h
Onboarding complete.
fake HOME
script detonation
lockfile diff
Local-first dependency gate
Run installs like every package could fight back.
A Docker sandbox gate for npm, pnpm, yarn, and bun. Built for humans, AI coding agents, and teams that do not want dependency graphs uploaded to a dashboard.
Install
npm install -D @asynq.org/safe-install
No telemetry
No public score
48h age gate
Offline script detonation
First run
One guided setup instead of a pile of flags.
`safe-install onboarding` asks what to enable, checks Docker readiness, and tunes the policy for humans, agents, and CI.
$ safe-install onboarding --dry-run
Selected actions:
enable safe-install.yaml
enable AI agent instruction files
enable repo-local shims
enable package.json preinstall guard
skip global package-manager shims
No files were changed.Policy in minutes
Pick package age, install-script blocking, repo shims, package.json guardrails, and global shim behavior from one prompt.
Agent-ready setup
Generate instructions for Codex, Claude Code, Cursor, Copilot, and generic coding agents so dependency changes use the same route.
CI-shaped defaults
Use `safe-install verify-lockfile` and `safe-install ci` to turn lockfile intelligence into a pull-request gate.
Comparison
Different shape than scanners and proxy firewalls.
safe-install focuses on one narrow moment: what happens during an install or update before the real project is touched. These tools can be complementary. Comparison last updated June 10, 2026.
| Capability | safe-install | Aikido Safe Chain | Socket |
|---|---|---|---|
| Open source | Yes, Apache-2.0 | Yes, AGPL-3.0 | No |
| Free to use | ✓ | ✓ | Free* |
| Free plan scan limit | No scan meter | No scan meter | 1,000 / month |
| Docker sandbox detonation before apply | ✓ | - | - |
| Real project untouched until sandbox passes | ✓ | - | - |
| No hosted dashboard or dependency graph upload | ✓ | ✓ | - |
| AI agent instructions and repo shims | ✓ | - | - |
| CI command for lockfile verification | ✓ | - | ✓ |
| Package age policy | ✓ | ✓ | ✓ |
| Known malware and threat intelligence | - | ✓ | ✓ |
| Hosted triage, alerts, and team dashboard | - | - | ✓ |
| Broad ecosystem coverage beyond JS/TS | - | ✓ | ✓ |
* Socket has a $0 Free plan with 1,000 scans per month, plus paid plans for higher limits and team features.
External references
Command surface
Every command the CLI exposes.
Use onboarding for first setup. Dependency changes run the sandbox first and apply automatically when the report passes. Use `--dry-run` for report-only checks.
Project setup
safe-install onboarding- Interactive setup that asks which policy, agent, shim, and guard options to enable.
safe-install onboarding --dry-run- Shows the onboarding plan without writing project or global shim files.
safe-install onboarding --defaults- Applies the recommended setup without prompts for scripted environments.
safe-install init- Manual setup command that writes `safe-install.yaml` with Docker strong isolation defaults.
safe-install init --agents- Adds AI agent instructions for Codex, Claude Code, Cursor, Copilot, and generic agent workflows.
safe-install init --enforce- Creates repo-local npm, pnpm, yarn, and bun shims in `.safe-install/bin` and ignores them in git.
safe-install init --package-json-guard- Adds a `preinstall` guard that tells users to use safe-install.
safe-install init --all- Enables config, agent files, repo shims, and package.json guard together.
Install and update
safe-install <pm> <command> [args]- Wraps npm, pnpm, yarn, or bun dependency commands in the Docker sandbox.
safe-install npm install <pkg>- Runs npm install through the Docker sandbox, then applies with scripts disabled when the report passes.
safe-install pnpm add <pkg>- Checks pnpm add/install flows and lockfile changes.
safe-install yarn add <pkg>- Tests Yarn dependency changes before applying to the real workspace.
safe-install bun add <pkg>- Uses the Bun Docker image for Bun dependency changes.
safe-install npm update <pkg>- Runs update flows through the same sandbox gate.
safe-install pnpm remove <pkg>- Allows removals through the same report and apply workflow.
... --dry-run- Prints the sandbox report without changing the real project.
... --json- Outputs the sandbox report as JSON for automation and CI experiments.
Inspect and guard
safe-install doctor- Detects sandbox capability and explains Docker CLI or daemon setup issues.
safe-install verify-lockfile --base <ref>- Analyzes package.json and lockfile changes against a base git ref.
safe-install ci --base <ref>- CI entrypoint that verifies lockfiles and requires Docker daemon availability.
safe-install guard npm- Used by package.json `preinstall` to block raw npm installs with clear guidance.
SAFE_INSTALL_GUARD_BYPASS=1 npm install- Maintainer-only emergency bypass for the lightweight package.json guard.
safe-install help- Prints the command overview.
safe-install --version- Prints the installed CLI version.
Global shims
safe-install install-global-shims- Dry-run plan for global npm, pnpm, yarn, and bun shims in `~/.safe-install/shims`.
safe-install install-global-shims --apply- Installs optional global shims for protected repos with `safe-install.yaml`.
safe-install uninstall-global-shims- Dry-run removal plan.
safe-install uninstall-global-shims --apply- Removes global shims without touching shell config.
SAFE_INSTALL_GLOBAL_SHIM_BYPASS=1 npm install- Emergency bypass when global shims are installed.
Enforcement modes
Pick the amount of friction your team can tolerate.
package.json guard
Lightweight warning for raw npm installs. It is simple, visible, and does not require shell changes.
safe-install init --package-json-guard
Repo shims
Local package-manager wrappers block raw commands when `.safe-install/bin` is first in PATH.
safe-install init --enforce
Agent policy
Generated instructions for Codex, Claude Code, Cursor, Copilot, and generic AI agents.
safe-install init --agents
Global shims
Optional power-user mode that preserves normal npm/pnpm/yarn/bun muscle memory across repos.
safe-install install-global-shims --apply
Age gate
Block direct dependency versions that are too new. Default is 48 hours; set 168 for a week.
policy.minimumPackageAgeHours: 168
Sandbox flow
The real project is not the detonation chamber.
01
Copy workspace
Skip `.git`, `node_modules`, build output, and caches.
02
Fake HOME
No real SSH keys, npm tokens, cloud credentials, or editor configs are mounted.
03
Resolve first
Fetch packages with lifecycle scripts disabled.
04
Detonate offline
Rebuild scripts run in Docker with `--network none`.
05
Report and apply
Passing reports apply automatically; `--dry-run` stops after the sandbox report.
Roadmap
JavaScript first. Multi-language next.
Now
npm, pnpm, yarn, bun, Docker backend, lockfile verification, agent instructions, guards, local and global shims.
Next
Install-script allowlists, richer PR annotations, transitive package-age checks, and better behavior tracing.
Later
Python pip/uv, Rust cargo/build.rs, Podman, bubblewrap, and local report viewer.