Core Concepts
Configuration
Agentinel is configured via a single .agentinel.json file in your project root. All options are optional.
The .agentinel.json file
When you run npx asen init, a default config file is written to your project root:
{
"mode": "warn",
"allowlist": {}
}This file should be committed to version control so all team members share the same security posture.
Modes: warn vs strict
Agentinel supports two operating modes, controlled by the mode field.
Agentinel surfaces a warning in the agent output but does not block the install. The agent decides whether to proceed.
{
"mode": "warn"
}Best for teams migrating to Agentinel gradually or using agents in read-heavy workflows.
Agentinel hard-blocks the install and returns an error payload to the agent. The install never reaches npm.
{
"mode": "strict"
}Recommended for production repos, CI pipelines, and any project with autonomous agentic access.
Strict mode and false positives
Strict mode will block packages that trigger heuristics, even if they are legitimately safe. Use the allowlist to carve out exceptions for known-good packages. See the section below.
The allowlist
The allowlist lets you permanently approve a package so Agentinel never flags it again, even in strict mode. Each entry includes an audit trail: who approved it and why.
Use the npx asen allow command to add a package with a required reason:
npx asen allow my-internal-package --reason "Internal monorepo package, pre-approved by security team"This updates your .agentinel.json with a structured entry:
{
"mode": "strict",
"allowlist": {
"my-internal-package": {
"reason": "Internal monorepo package, pre-approved by security team",
"addedAt": "2026-07-14T09:32:11.000Z",
"addedBy": "git:aman@company.com"
}
}
}Audit trail
The addedBy field is populated from your local Git config (git config user.email). Because this file is committed to version control, you have a full, reviewer-visible history of every manual allowlist decision.
Full config schema
| Field | Type | Default | Description |
|---|---|---|---|
mode | "warn" | "strict" | "warn" | Operating mode. "warn" alerts but allows. "strict" hard-blocks. |
allowlist | Record<string, AllowlistEntry> | {} | Map of package names to their allowlist entries. |
allowlist[pkg].reason | string | required | Human-readable reason the package was approved. |
allowlist[pkg].addedAt | ISO 8601 string | auto | Timestamp when the allowlist entry was created. |
allowlist[pkg].addedBy | string | auto | Git user email of the person who ran asen allow. |