Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/ara-home/ara/llms.txt

Use this file to discover all available pages before exploring further.

ara run executes a named script from your project’s package.json (or ara.toml) inside a configurable sandbox. By wrapping the process in a Linux seccomp-BPF filter, Ara can restrict which syscalls the script is allowed to make — limiting network access, filesystem mutations, or clock reads depending on the profile you choose. The node_modules/.bin directory is automatically prepended to PATH so locally installed binaries like tsc, eslint, or vitest are found without any extra configuration.

​
Usage

ara run <script> [--profile <profile>]
<script> must match a key in the scripts section of your package.json or ara.toml.

​
Flags

​
--profile
string
default:"runtime"
The sandbox profile to apply when executing the script. Accepted values are open (alias: runtime), restricted, hermetic, and custom. See Profiles below for details.

​
Profiles

Ara provides four built-in sandbox profiles that trade off between isolation and permissiveness:
Default profile. The script runs with network access enabled and subprocess spawning allowed. Use this for development servers, scaffolding tools, or any script that needs to reach the internet or fork child processes.
ara run start
ara run start --profile open
ara run start --profile runtime  # identical alias
Equivalent ara.toml entry:
[scripts]
start = "node server.js"

​
Profile comparison

ProfileNetworkSpawn subprocessesDeterministic clock
open / runtime✅✅❌
restricted❌❌❌
hermetic❌❌✅
custom❌❌❌

​
Script resolution

Ara looks up the script name in this order:
  1. The [scripts] section of ara.toml (if it exists).
  2. The scripts object in package.json.
This means any existing package.json scripts work with ara run immediately, with no migration required. 
{
  "scripts": {
    "build": "tsc --noEmit && esbuild src/index.ts --bundle --outdir=dist",
    "test": "vitest run",
    "lint": "eslint src"
  }
}

ara run build                     # open profile (default)
ara run test --profile restricted
ara run lint --profile restricted

​
Examples

# Start a dev server (needs network)
ara run dev
ara run dev --profile open

# Run tests without network access
ara run test --profile restricted

# Type-check only (no side effects needed)
ara run typecheck --profile restricted
Before executing the script, Ara constructs a PATH by prepending the absolute path to node_modules/.bin. This ensures locally installed binaries take precedence over globally installed ones: 
/home/user/my-app/node_modules/.bin:/usr/local/bin:/usr/bin:/bin
No shell configuration or npx wrapper is needed to invoke project-local tools.
Linux x86_64 only. The seccomp-BPF sandbox filter is written for x86_64 Linux syscall numbers. On macOS, Windows, or other architectures, ara run degrades gracefully — the script runs without any syscall restrictions. The --profile flag is accepted but has no enforcement effect on non-Linux platforms.
Ara does not run npm lifecycle scripts (preinstall, postinstall, prepare, etc.) during package installation. ara run only executes scripts you explicitly invoke by name.

Build docs developers (and LLMs) love

Get started for freeTalk to us