Lucentive Labs

Lucentive Labs · agent-tooling

Ferry

Beta

Broker declared secrets into an authorized child process without printing their values.

Ferry is a Node CLI and library that resolves declared secrets from configured backends, checks command arguments against policy, injects authorized values into a child environment, redacts those values from child output, and appends value-free JSONL audit records.

Read the docsView on GitHubView on npm

Backends

Values come from where they already live

1Password

External CLI

op(ref)

Resolves a 1Password secret reference through the separately installed op CLI.

Encrypted file

Encrypted local

file(name)

Headless reuse. AES-256-GCM, scrypt key from FERRY_FILE_KEY.

Process env

Development

env(varName?)

Local dev; reads process.env / a local .env.

Documented boundary

Declared values stay inside a scoped broker path

  • Ferry resolves a declared value in memory, injects it into an authorized child environment, and does not write that value to its own return value or audit record.
  • Child stdout and stderr share one boundary-safe redactor that replaces every occurrence of an injected value with [redacted:NAME] — across chunk boundaries and even when a value is split across the two streams.
  • A declared secret is injected only when argv matches its allow rules. Use --clean-env when undeclared ambient environment variables must not be inherited by the child.
  • Every access appends one JSONL audit row { ts, secret, command, backend, decision } — a decision record, never a value.

Limitations

What Ferry does not claim

  • Ferry requires Node.js 20 or newer.
  • Ferry governs only declared secrets; undeclared ambient environment variables remain inherited unless --clean-env is used.
  • An allowed child process, a compromised host, and trusted configuration remain outside Ferry's guarantee.
  • The file backend requires FERRY_FILE_KEY; the 1Password backend requires the external op CLI; TypeScript configuration requires consumer-installed tsx.
  • Headless no-prompt operation is available only after the relevant cache, decryption key, and backend setup have been completed.

Get started

ferry init → ferry run -- your command

Install @lucentive-labs/ferry from npm, declare your secrets, then prefix an authorized command with ferry run --. MIT-licensed, zero runtime dependencies. Review the canonical README for backend setup and the trust boundary before use.

Read the docsnpm