# tapid run

Source: https://tapid.dev/docs/commands/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](https://tapid.dev/docs-markdown/development/content.md).

## Syntax

```text
tapid run <SCRIPT> [OPTIONS] [-- <ARGS>...]
```

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

```toml
[run.scripts.test]
assurance = "restricted"
read = ["."]
write = ["build"]
network = false
```

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.

```bash
$ tapid run test --receipt-json
$ tapid run dev -- --hostname 127.0.0.1 --port 3001
```

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](https://github.com/LimeTip/tapid/blob/v0.0.13/crates/tapid-cli/README.md#experimental-nodejs-root-script-runner-and-bin-handling) 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](https://github.com/LimeTip/tapid/blob/v0.0.13/docs/platform-validation.md) 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](https://github.com/LimeTip/tapid/blob/v0.0.13/docs/windows-tapid-run-scope.md) before evaluating a read-only profile.