Configuration

aube reads pnpm-compatible configuration from project .npmrc, user .npmrc, user aube config, aube-workspace.yaml, environment variables, and supported CLI flags. An existing pnpm-workspace.yaml is read and updated in place.

Start with aube config find <words> to locate a setting and aube config explain <key> to see its default and supported sources. The settings reference contains every registered setting.

Choose a configuration source

Scope	Where to put it
One command	A supported CLI flag or environment variable
Shared registry and authentication setup	Project .npmrc; keep token values in environment variables
Shared workspace and build policy	aube-workspace.yaml or an existing pnpm-workspace.yaml
Personal aube defaults	aube config set <key> <value>
Enforced organization policy	/etc/aube/managed.toml

CLI and environment overrides generally beat file settings. Some settings combine map or list values, and some give workspace YAML priority over .npmrc. Use the source details for the individual setting; managed policy applies after normal resolution and cannot be weakened by a local override.

Defaults worth knowing

Area	Default	Why it matters
Linker	nodeLinker=isolated	Keeps transitive dependencies scoped to the packages that declared them.
Package imports	packageImportMethod=auto	Links files from the store with the faster same-filesystem primitive per platform — reflink (clonefile) on macOS, hardlink on Linux and elsewhere — falling back to copy on cross-filesystem boundaries. Set clone or clone-or-copy to attempt reflink first, still falling back to copy when reflink is unavailable.
New releases	minimumReleaseAge=1440	Avoids installing versions published in the last 24 hours by default.
Exotic transitive deps	blockExoticSubdeps=true	Blocks transitive git and tarball dependencies unless you opt out.
Dependency scripts	allowlist	Project approvals and built-in trusted packages may run scripts; explicit denies win.
Jailed builds	jailBuilds=false	Opt in to running approved dependency scripts with a restricted environment, temporary HOME, and native macOS/Linux enforcement. Planned to default to true in the next major version.
Auto-install before scripts	enabled	aube run, aube test, and aube exec repair stale installs first.

User aube config

aube config set writes user-scope settings to ~/.config/aube/config.toml by default. If XDG_CONFIG_HOME is set, the path is $XDG_CONFIG_HOME/aube/config.toml.

minimumReleaseAge = 2880
autoInstallPeers = true
nodeLinker = "isolated"
packageImportMethod = "auto"

aube reads configuration from .npmrc regardless of which tool wrote it. Writes follow a routing rule: settings marked npmShared = true in crates/aube-settings/settings.toml (plus per-host auth/cert templates and scoped registries) land in .npmrc so npm, yarn, and pnpm see the same value. aube-only and pnpm-only settings land in ~/.config/aube/config.toml instead, so unknown-to-npm keys don't trigger warnings from sibling tools.

Managed hardening config

System administrators can enforce security settings with /etc/aube/managed.toml. Managed config is not normal precedence: aube first resolves CLI, env, project, workspace, and user config, then applies managed policy as a final hardening pass. Local config, env vars, and CLI flags can make managed settings stricter, but cannot weaken them.

For tests and non-root deployments, AUBE_MANAGED_CONFIG_PATH points at an additional managed TOML file. It is additive with /etc/aube/managed.toml: when both files set the same managed setting, aube keeps the stricter value.

The settings reference is generated from the settings registry and marks every enforceable setting with Managed policy. The policy names describe how multiple managed files and local config combine:

• max: the largest integer wins.
• trueWins: true wins over false.
• falseWins: false wins over true.
• ranked:a<b<c: later ranked values are stricter.
• managedWins: the managed value replaces the local value; when multiple managed files set a list, aube keeps only entries present in every managed file.

.npmrc

registry=https://registry.npmjs.org/
@mycorp:registry=https://npm.mycorp.internal/
//registry.npmjs.org/:_authToken=${NPM_TOKEN}
https-proxy=http://corp-proxy:3128/

.npmrc holds the keys that npm, yarn, and pnpm all read: registries, scoped registries, per-host auth, proxy/TLS, and the npm-standard scalars tagged npmShared in the settings registry. aube preserves symlinked .npmrc files when it writes to one. See the settings reference — each entry lists its .npmrc key alongside the other sources.

aube map settings (allowBuilds, overrides, packageExtensions, …) accept dotted writes at project scope to edit one entry at a time:

aube config set --local allowBuilds.@mongodb-js/zstd true
aube config set --local overrides.lodash 4.17.21

The write lands in the existing workspace YAML at <map>.<entry> when a workspace file exists, otherwise package.json#aube.<map>.<entry> — the same place install reads from. User-scope dotted writes for these maps error: aube only reads them per project. For allowBuilds, aube approve-builds <pkg> is the interactive equivalent.

Workspace YAML

nodeLinker: isolated
minimumReleaseAge: 1440
publicHoistPattern:
  - "*eslint*"
jailBuilds: true
jailBuildPermissions:
  "@vendor/*":
    env:
      - SHARP_DIST_BASE_URL
    write:
      - ~/.cache/sharp
jailBuildExclusions:
  - "@legacy-native/*"

See the settings reference — workspace YAML keys are listed per setting. The jail-related keys are described in Jailed builds.

Environment variables

pnpm-compatible NPM_CONFIG_* aliases are supported:

NPM_CONFIG_REGISTRY=https://registry.example.test aube install
NPM_CONFIG_NODE_LINKER=hoisted aube install

See the settings reference — environment variables are listed per setting.

CLI flags

CLI flags take precedence for the settings they expose:

aube install --node-linker=hoisted
aube install --network-concurrency=32
aube install --resolution-mode=time-based

See the settings reference — CLI flags are listed per setting.

Inspecting config

aube config get registry
aube config set auto-install-peers false
aube config list --json

Writes land in .npmrc only for the npm-shared surface (auth, registries, npm-standard scalars). Everything else — aube settings, pnpm-only knobs, and unknown keys — is stored in aube's own config. --local and --location project write the project-scope equivalents (<cwd>/.npmrc and <cwd>/.config/aube/config.toml).

package.json — pnpm.* and aube.* namespaces

aube reads pnpm's package.json config keys so existing projects keep working unchanged. Every key under pnpm.* is also accepted under aube.* for projects that want to declare aube-native config without piggy-backing on the pnpm namespace:

{
  "aube": {
    "overrides": { "lodash": "4.17.21" },
    "catalog": { "react": "^18.0.0" },
    "supportedArchitectures": { "os": ["current", "linux"] },
    "allowBuilds": { "sharp": true },
    "patchedDependencies": { "foo@1.0.0": "patches/foo.patch" },
    "peerDependencyRules": { "ignoreMissing": ["react-native"] }
  }
}

Merge semantics when both namespaces are present:

• Map-valued keys (overrides, catalog, catalogs, patchedDependencies, allowBuilds, allowedDeprecatedVersions, packageExtensions, peerDependencyRules.allowedVersions): aube.* wins on key conflict; disjoint keys from either namespace merge.
• List-valued keys (onlyBuiltDependencies, neverBuiltDependencies, ignoredOptionalDependencies, peerDependencyRules.ignoreMissing, peerDependencyRules.allowAny, updateConfig.ignoreDependencies, supportedArchitectures.{os,cpu,libc}): entries from both namespaces union. onlyBuiltDependencies and neverBuiltDependencies are legacy build-policy inputs; new review state is written to allowBuilds.
• Top-level npm-standard keys (overrides, packageExtensions, allowedDeprecatedVersions, updateConfig) still take highest precedence, so the aube.* alias doesn't change existing npm / pnpm precedence rules — it only adds a second namespace that beats pnpm.* but loses to the top-level form.