Skip to main content
Safe Chain reads configuration from ~/.safe-chain/config.json. This file is optional — Safe Chain works without it, using built-in defaults.
Config file values have the lowest priority. CLI flags and environment variables override any setting defined here.

​
Full schema

{
  "minimumPackageAgeHours": 48,
  "scanTimeout": 10000,
  "npm": {
    "minimumPackageAgeExclusions": ["@aikidosec/*", "my-trusted-package"],
    "customRegistries": ["npm.company.com", "registry.internal.net"]
  },
  "pip": {
    "minimumPackageAgeExclusions": ["requests", "django"],
    "customRegistries": ["pip.company.com", "registry.internal.net"]
  }
}

​
Keys

​
minimumPackageAgeHours
number
Global minimum age (in hours) a package must have before Safe Chain allows its installation. Applies to all ecosystems.Default: 48
{
  "minimumPackageAgeHours": 24
}
​
scanTimeout
number
Maximum time in milliseconds Safe Chain will wait for the pre-install malware scan to complete. If the scan does not finish within this window, Safe Chain throws an error and the installation is aborted.Default: 10000 (10 seconds)
{
  "scanTimeout": 30000
}
This setting can also be overridden with the AIKIDO_SCAN_TIMEOUT_MS environment variable, which takes precedence over the config file value.
​
npm.minimumPackageAgeExclusions
string[]
An array of npm package names or scopes to exclude from the minimum package age check. Supports @scope/* wildcards to trust all packages from an organization.Exclusions defined here are merged with any exclusions set via the SAFE_CHAIN_MINIMUM_PACKAGE_AGE_EXCLUSIONS environment variable.
{
  "npm": {
    "minimumPackageAgeExclusions": ["@aikidosec/*", "my-trusted-package"]
  }
}
​
npm.customRegistries
string[]
An array of npm registry hostnames that Safe Chain should scan in addition to the default npm registry.Registries defined here are merged with any registries set via the SAFE_CHAIN_NPM_CUSTOM_REGISTRIES environment variable.
{
  "npm": {
    "customRegistries": ["npm.company.com", "registry.internal.net"]
  }
}
​
pip.minimumPackageAgeExclusions
string[]
An array of Python package names to exclude from the minimum package age check for the pip ecosystem.Exclusions defined here are merged with any exclusions set via the SAFE_CHAIN_MINIMUM_PACKAGE_AGE_EXCLUSIONS environment variable.
{
  "pip": {
    "minimumPackageAgeExclusions": ["requests", "django"]
  }
}
​
pip.customRegistries
string[]
An array of PyPI registry hostnames that Safe Chain should scan in addition to the default PyPI registry.Registries defined here are merged with any registries set via the SAFE_CHAIN_PIP_CUSTOM_REGISTRIES environment variable.
{
  "pip": {
    "customRegistries": ["pip.company.com", "registry.internal.net"]
  }
}

​
Priority order

When the same setting is configured in multiple places, Safe Chain applies this precedence:
  1. CLI flags (highest priority) — e.g. --safe-chain-minimum-package-age-hours=24
  2. Environment variables — e.g. SAFE_CHAIN_MINIMUM_PACKAGE_AGE_HOURS=24
  3. Config file (~/.safe-chain/config.json) — lowest priority
For list-based settings (minimumPackageAgeExclusions, customRegistries), values from environment variables and the config file are merged together rather than one overriding the other.

Build docs developers (and LLMs) love

Get started for freeTalk to us