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.
sandbox-npm-install solves a specific and painful problem in containerized development: when a Docker sandbox mounts the workspace via virtiofs, native Go and Rust binaries such as esbuild, lightningcss, and rollup crash with mmap alignment failures (SIGILL, SIGSEGV, or 'unaligned sysNoHugePageOS' errors) when executed from the virtiofs mount on aarch64. The skill's fix is to install packages onto the container's local ext4 filesystem and symlink node_modules back into the mounted workspace, avoiding the crashes entirely.
The workflow is driven by a bundled install script (scripts/install.sh) run from the workspace root. The script copies package.json, package-lock.json, and any .npmrc to a local ext4 directory, runs npm ci (falling back to npm install when no lockfile exists), symlinks node_modules back into the workspace, and verifies known native binaries (esbuild, rollup, lightningcss, vite) if present. Options include --workspace to point at a specific package.json directory and --playwright to also install the Playwright Chromium browser and its system dependencies (using sudo when available). The doc covers post-install verification, Vite server.fs.allow configuration for the symlinked path, and a troubleshooting table for intermittent native-binary crashes.
It targets developers and AI coding agents working inside Docker sandbox environments with virtiofs-mounted workspaces on Node.js projects, especially those hitting native-binary crashes during npm install, dev server startup, or builds. It is most useful on first setup of a new sandbox session, after package.json or package-lock.json changes, or when node_modules is missing or corrupted.
On first-time install in a new sandbox session, after package.json or package-lock.json changes, when node_modules is missing or corrupted, or when you hit native binary crashes like SIGILL, SIGSEGV, mmap, or 'unaligned sysNoHugePageOS'.
A Docker sandbox with a virtiofs-mounted workspace, Node.js and npm available in the container, and a package.json in the target workspace.
The doc warns that running npm ci or npm install directly in the virtiofs-mounted workspace causes native binaries to crash. Packages must be installed on the container-local ext4 filesystem and symlinked back.
No. The local install directory (e.g. /home/agent/project-deps) is container-local and is NOT synced to the host. The node_modules symlink appears as a broken link on the host, which is harmless since node_modules is typically gitignored.
Re-run the script — native binary crashes can be non-deterministic on first load. The script also verifies esbuild, rollup, lightningcss, and vite when present.
Quick Setup:
.claude/skills/Repository
github/awesome-copilot