sandbox-npm-install
Install npm packages in a Docker sandbox environment. Use this skill whenever you need to install, reinstall, or update node_modules inside a container where the workspace is mounted via virtiofs. Native binaries (esbuild, lightningcss, rollup) crash on virtiofs, so packages must be installed on the local ext4 filesystem and symlinked back.
Best use case
sandbox-npm-install is best used when you need a repeatable AI agent workflow instead of a one-off prompt.
Install npm packages in a Docker sandbox environment. Use this skill whenever you need to install, reinstall, or update node_modules inside a container where the workspace is mounted via virtiofs. Native binaries (esbuild, lightningcss, rollup) crash on virtiofs, so packages must be installed on the local ext4 filesystem and symlinked back.
Teams using sandbox-npm-install should expect a more consistent output, faster repeated execution, less prompt rewriting.
When to use this skill
- You want a reusable workflow that can be run more than once with consistent structure.
When not to use this skill
- You only need a quick one-off answer and do not need a reusable workflow.
- You cannot install or maintain the underlying files, dependencies, or repository context.
Installation
Claude Code / Cursor / Codex
Manual Installation
- Download SKILL.md from GitHub
- Place it in
.claude/skills/sandbox-npm-install/SKILL.mdinside your project - Restart your AI agent — it will auto-discover the skill
How sandbox-npm-install Compares
| Feature / Agent | sandbox-npm-install | Standard Approach |
|---|---|---|
| Platform Support | Not specified | Limited / Varies |
| Context Awareness | High | Baseline |
| Installation Complexity | Unknown | N/A |
Frequently Asked Questions
What does this skill do?
Install npm packages in a Docker sandbox environment. Use this skill whenever you need to install, reinstall, or update node_modules inside a container where the workspace is mounted via virtiofs. Native binaries (esbuild, lightningcss, rollup) crash on virtiofs, so packages must be installed on the local ext4 filesystem and symlinked back.
Where can I find the source code?
You can find the source code on GitHub using the link provided at the top of the page.
SKILL.md Source
# Sandbox npm Install ## When to Use This Skill Use this skill whenever: - You need to install npm packages for the first time in a new sandbox session - `package.json` or `package-lock.json` has changed and you need to reinstall - You encounter native binary crashes with errors like `SIGILL`, `SIGSEGV`, `mmap`, or `unaligned sysNoHugePageOS` - The `node_modules` directory is missing or corrupted ## Prerequisites - A Docker sandbox environment with a virtiofs-mounted workspace - Node.js and npm available in the container - A `package.json` file in the target workspace ## Background Docker sandbox workspaces are typically mounted via **virtiofs** (file sync between the host and Linux VM). Native Go and Rust binaries (esbuild, lightningcss, rollup, etc.) crash with mmap alignment failures when executed from virtiofs on aarch64. The fix is to install on the container's local ext4 filesystem and symlink back into the workspace. ## Step-by-Step Installation Run the bundled install script from the workspace root: ```bash bash scripts/install.sh ``` ### Common Options | Option | Description | |---|---| | `--workspace <path>` | Path to directory containing `package.json` (auto-detected if omitted) | | `--playwright` | Also install Playwright Chromium browser for E2E testing | ### What the Script Does 1. Copies `package.json`, `package-lock.json`, and `.npmrc` (if present) to a local ext4 directory 2. Runs `npm ci` (or `npm install` if no lockfile) on the local filesystem 3. Symlinks `node_modules` back into the workspace 4. Verifies known native binaries (esbuild, rollup, lightningcss, vite) if present 5. Optionally installs Playwright browsers and system dependencies (uses `sudo` when available) If verification fails, run the script again — crashes can be intermittent during initial setup. ## Post-Install Verification After the script completes, verify your toolchain works. For example: ```bash npm test # Run project tests npm run build # Build the project npm run dev # Start dev server ``` ## Important Notes - The local install directory (e.g., `/home/agent/project-deps`) is **container-local** and is NOT synced back to the host - The `node_modules` symlink appears as a broken link on the host — this is harmless since `node_modules` is typically gitignored - Running `npm ci` or `npm install` on the host naturally replaces the symlink with a real directory - After any `package.json` or `package-lock.json` change, re-run the install script - Do NOT run `npm ci` or `npm install` directly in the mounted workspace — native binaries will crash ## Troubleshooting | Problem | Solution | |---|---| | `SIGILL` or `SIGSEGV` when running dev server | Re-run the install script; ensure you're not running `npm install` directly in the workspace | | `node_modules` not found after install | Check that the symlink exists: `ls -la node_modules` | | Permission errors during install | Ensure the local deps directory is writable by the current user | | Verification fails intermittently | Run the script again — native binary crashes can be non-deterministic on first load | ## Vite Compatibility If your project uses Vite, you may need to allow the symlinked path in `server.fs.allow`. Add the symlink target's parent directory (e.g., `/home/agent/project-deps/`) to your Vite config so that Vite can serve files through the symlink.
Related Skills
installation-guide-creator
Installation Guide Creator - Auto-activating skill for Technical Documentation. Triggers on: installation guide creator, installation guide creator Part of the Technical Documentation skill category.
exa-install-auth
Install the exa-js SDK and configure API key authentication. Use when setting up a new Exa integration, configuring API keys, or initializing Exa in a Node.js/Python project. Trigger with phrases like "install exa", "setup exa", "exa auth", "configure exa API key", "exa-js".
evernote-install-auth
Install and configure Evernote SDK and OAuth authentication. Use when setting up a new Evernote integration, configuring API keys, or initializing Evernote in your project. Trigger with phrases like "install evernote", "setup evernote", "evernote auth", "configure evernote API", "evernote oauth".
elevenlabs-install-auth
Install and configure ElevenLabs SDK authentication for Node.js or Python. Use when setting up a new ElevenLabs project, configuring API keys, or initializing the elevenlabs npm/pip package. Trigger: "install elevenlabs", "setup elevenlabs", "elevenlabs auth", "configure elevenlabs API key", "elevenlabs credentials".
documenso-install-auth
Install and configure Documenso SDK/API authentication. Use when setting up a new Documenso integration, configuring API keys, or initializing Documenso in your project. Trigger with phrases like "install documenso", "setup documenso", "documenso auth", "configure documenso API key".
deepgram-install-auth
Install and configure Deepgram SDK authentication. Use when setting up a new Deepgram integration, configuring API keys, or initializing Deepgram in your project. Trigger: "install deepgram", "setup deepgram", "deepgram auth", "configure deepgram API key", "deepgram credentials".
databricks-install-auth
Install and configure Databricks CLI and SDK authentication. Use when setting up a new Databricks integration, configuring tokens, or initializing Databricks in your project. Trigger with phrases like "install databricks", "setup databricks", "databricks auth", "configure databricks token", "databricks CLI".
customerio-install-auth
Install and configure Customer.io SDK/CLI authentication. Use when setting up a new Customer.io integration, configuring API keys, or initializing Customer.io in your project. Trigger: "install customer.io", "setup customer.io", "customer.io auth", "configure customer.io API key", "customer.io credentials".
cursor-install-auth
Install Cursor IDE and configure authentication across macOS, Linux, and Windows. Triggers on "install cursor", "setup cursor", "cursor authentication", "cursor login", "cursor license", "cursor download".
coreweave-install-auth
Configure CoreWeave Kubernetes Service (CKS) access with kubeconfig and API tokens. Use when setting up kubectl access to CoreWeave, configuring CKS clusters, or authenticating with CoreWeave cloud services. Trigger with phrases like "install coreweave", "setup coreweave", "coreweave kubeconfig", "coreweave auth", "connect to coreweave".
cohere-install-auth
Install and configure Cohere SDK authentication with API v2. Use when setting up a new Cohere integration, configuring API keys, or initializing the CohereClientV2 in your project. Trigger with phrases like "install cohere", "setup cohere", "cohere auth", "configure cohere API key".
coderabbit-install-auth
Install and configure CodeRabbit AI code review on GitHub or GitLab repositories. Use when setting up CodeRabbit for the first time, installing the GitHub App, configuring the CLI, or connecting CodeRabbit to your repositories. Trigger with phrases like "install coderabbit", "setup coderabbit", "coderabbit auth", "configure coderabbit", "add coderabbit to repo".