tapid run
Launch an explicit Node.js project script with a configured execution policy.
Version scope
Published v0.0.13 requires tapid.toml and an exact script profile. It includes experimental macOS Restricted, Linux Restricted with targeted Ubuntu validation, and limited Windows read-only AppContainer execution. Windows writes and network-enabled profiles fail closed. Broader platform acceptance remains incomplete.
v0.0.13 includes Linux ManagedTree and timeout, output, process-count and memory limits. It requires private PID/mount namespaces and delegated cgroup v2 with the required controllers. Tapid does not configure host delegation. Exact-commit acceptance and the broader platform matrix remain pending. See Release changes.
Syntax
Tapid reads the selected package.json script and its [run.scripts.<name>] configuration. It launches Node.js scripts, forwards arguments after --, and returns the child exit status. It does not select Bun or Deno and does not provide a JavaScript runtime.
Configure the script
For a test script that needs to read the project, write to an existing build directory, and make no network requests, configure tapid.toml:
Adapt the paths to the script's actual needs. Paths are project-relative. Each selected script needs an exact profile; defaults alone do not authorize a script. Unsupported required restrictions fail before the script starts. There is no automatic unsandboxed fallback.
The dev example also requires its own profile. Hostname and port arguments configure the application, not the containment policy. network = true allows unrestricted networking; it is not a host or port allowlist.
Options
| Option | Purpose |
|---|---|
--project-dir PATH | Select the project, defaulting to the current directory. |
--node-runtime PATH | Select an exact Node executable instead of trusted host PATH discovery. |
--workspace NAME | Run a selected member script from its directory using the root policy and containment boundary. |
--receipt-json | Emit a versioned execution receipt as one JSON line on stderr after child output. |
--allow-process-memory-stats | Linux Restricted only. Provide read-only procfs for process-memory statistics through a private PID/mount namespace. Aliases are --allow-procfs and --allow-memory-read. |
The runner builds a controlled child environment and executable lookup. It does not append the invoking shell's entire PATH or inherit every environment variable. Environment access must be configured explicitly. See the CLI runner guide for configuration details.
Limits and failures
Missing scripts, missing configuration, missing exact profiles, invalid runtimes, and unsupported containment fail before launch. Dependency installation and lifecycle scripts do not run as part of run.
Restricted execution limits configured authority but does not guarantee complete descendant ownership or cleanup. Detached descendants can survive. Linux ManagedTree requires its namespace and cgroup prerequisites to enforce configured limits and own descendants. Other unsupported ManagedTree configurations fail before launch. Omitting assurance requests the stronger legacy ManagedTree contract and can therefore fail before launch.
--receipt-json appends one compact JSON line to stderr after child output. Stderr is a mixed stream, not a single-object JSON channel. Child output is untrusted and can resemble a receipt. Check CLI completion, but do not trust the last stderr line as an authenticated receipt. Launch failures emit no receipt, and later failure diagnostics can follow a receipt. Global --json rejects run before launching a child.
Execution receipts describe the enforcement and completion observed by the runner. They do not certify that arbitrary project or dependency code is safe. See platform validation for the tested platform/configuration combinations.
Windows boundary
The v0.0.13 Windows backend implements read-only AppContainer/Job Object execution and graceful Ctrl+C. Pre-integration Windows 11 and hosted checks do not establish full exact-revision support. Writes, network-enabled profiles and complete application acceptance remain unsupported or pending. The sample above grants writes and is therefore unsuitable for this Windows backend. Read the tagged Windows scope before evaluating a read-only profile.