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 works with any existing package.json project — no migration step, no new manifest format to learn. All you need is a directory with a package.json and a working internet connection. This guide walks you through installing your dependencies, adding a new package, understanding the security prompts you will see along the way, and running a script.
1

Point Ara at an existing project

Start from any npm project. If you do not have one handy, create a minimal one:
mkdir my-app && cd my-app
npm init -y
Ara reads package.json natively as its primary source of truth. You do not need an ara.toml to get started — that file is only for advanced configuration like security thresholds and hermetic build profiles.
2

Run ara install

From the project root, run:
ara install
Ara works through the install in several phases:
  1. Parse — reads package.json for dependencies, devDependencies, and workspace globs.
  2. Expand — globs workspaces patterns and creates implicit deps for each discovered member.
  3. Resolve — applies Minimum Version Selection (MVS) to produce a deterministic dependency graph.
  4. Fetch — downloads tarballs from the npm registry (or other sources); workspace members become live symlinks.
  5. Analyze — scans every JS/TS file in every fetched package against 18 security patterns.
  6. Prompt — asks for your approval on any findings (unless --non-interactive).
  7. Extract — unpacks approved packages into node_modules and the content-addressed store.
  8. Lock — writes ara.lock with the full resolved graph.
On a project with no suspicious dependencies, Ara completes silently. The prompts only appear when the analyzer finds something worth flagging.
3

Understand the security prompts

If any fetched package triggers a finding, Ara pauses and shows you exactly what it found before proceeding. For example, a package that uses eval() and reads a credential environment variable would produce output like this:
🔍 Scanning some-pkg@2.1.0...
  ⚠  eval-usage (critical) — eval() call in lib/utils.js:42
  ⚠  credential-access (medium) — process.env.AWS_SECRET_KEY in lib/config.js:10

Allow some-pkg@2.1.0?
  [y] Yes, install anyway
  [n] No, skip this package
  [s] Sandbox (restrict at runtime)
> _
You choose how to handle each flagged package individually. The finding details include the pattern ID, its severity (critical, high, medium, low), and the exact file and line number.In CI pipelines, pass --non-interactive to skip prompts and install everything:
ara install --non-interactive
You can tighten the threshold so that only high and critical findings trigger prompts. Add an ara.toml to your project root:
[security]
risk_threshold = "high"
4

Add a new package with ara add

To install a package and save it to package.json in one step, use ara add:
ara add zod
Ara resolves the latest version from the npm registry, fetches and scans it, prompts for approval if needed, extracts it to node_modules, and updates both package.json and ara.lock.You can specify an exact version, a range, or a dev dependency:
ara add zod@^3.23.0            # semver range, resolved to latest matching
ara add --save-dev typescript   # saved as devDependency
ara add react zod typescript    # multiple packages at once
ara install zod is an alias for ara add zod. Both spellings work.
5

Inspect the lockfile

After a successful install, Ara writes ara.lock in the project root. Commit this file to your repository — it guarantees that any other machine or CI run produces exactly the same dependency graph.
cat ara.lock
The lockfile is a TOML file. Each installed package has an entry like this:
version = 1

[graph]
resolver = "mvs"
generated_at = "2025-06-03T12:00:00Z"
graph_hash = "sha256:abc123..."

[[package]]
name = "zod"
version = "3.23.8"
source = "npm"
package_hash = "sha256:def456..."
integrity = "sha256:ghi789..."
dependencies = []
Every entry records the resolved version, its source (registry, workspace, git, etc.), a package_hash for the tarball stored in the content-addressed store, and an integrity hash for verification. There are no floating versions and no ^ ranges in the lockfile — everything is pinned.
6

Run a script with ara run

If your package.json defines scripts, you can run them through Ara:
ara run build
By default this uses the runtime (open) sandbox profile — no restrictions. On Linux, you can opt into stricter profiles:
ara run build --profile hermetic    # no network, deterministic clock, minimal syscalls
ara run test --profile restricted   # safe syscalls, read-only filesystem, no network
The four profiles are:
ProfileWhat it allows
open (or runtime)No restrictions — full access to the system
restrictedSafe syscalls only, no network, no subprocess spawning
hermeticMinimal syscall set, no network, deterministic clock
customUser-defined restrictions configured via ara.toml
Sandbox profiles only apply on Linux x86_64. On macOS and Windows, ara run executes the script without restrictions regardless of the --profile flag you pass.

​
What you now have

After following this guide your project directory looks like this: 
my-app/
├── package.json        ← updated with any new packages you added
├── ara.lock            ← committed, deterministic resolved graph
└── node_modules/
    └── zod/            ← extracted and stored by SHA-256 hash
You have installed dependencies with security scanning, added a package with ara add, reviewed a content-addressed lockfile, and run a script through the sandboxed executor.

​
Next steps

CLI Reference

Full documentation for every ara subcommand, flag, and spec format.

Security Overview

Learn what the analyzer detects, how findings are reported, and how to configure thresholds.

Lockfile Format

Understand the ara.lock schema, graph hashes, and how reproducibility is guaranteed.

Migrating from npm

Drop-in compatibility notes and the differences you will notice coming from npm or pnpm.

Build docs developers (and LLMs) love

Get started for freeTalk to us