Proxy vs. Environment Injection

AgentSecrets provides two specialized, enterprise-grade execution runtimes designed for different architectural boundaries:

The Credential Proxy (agentsecrets proxy / agentsecrets call / Python SDK): Network transport layer credential substitution.
Environment Injection (agentsecrets env -- <command>): Ephemeral process memory injection with real-time stream redaction.

Both runtimes are 100% Zero-Disk (secrets are retrieved from the hardware-backed OS Keychain and never touch .env files). Each runtime is engineered to maximize security within its operational domain.

Architectural Comparison Matrix

Security & Operational Feature	Credential Proxy (Network Layer)	Environment Injection (Process Layer)
Primary Domain	Autonomous AI Agents, LLM tool calls, HTTP APIs	Databases, background workers, legacy CLIs, Docker
Target Boundary	HTTP / HTTPS outbound requests	OS Process Environment (`os.environ` / `process.env`)
Secrets on Physical Disk	Zero (Never written to disk)	Zero (Never written to disk)
Parent Shell Protection	Immune (Never exported to shell)	Immune (Never exported to parent shell or history)
Sibling Process Snooping	Immune (Protected in daemon RAM)	Immune (OS kernel memory boundary isolates child)
Terminal & Log Output Redaction	Built-in (`credential_echo` defense)	Built-in (`MaskingWriter` multi-encoding scanner)
Exfiltration via Shell `env`	Immune (Key names only)	Neutralized (`env`, `printenv`, `echo $KEY` masked to `[REDACTED]`)
Plaintext in Application Memory	Zero (Application only holds key names)	Localized to Child RAM (Required for DB drivers)
Egress Domain Allowlisting	Enforced at the network boundary (`proxy/domain-allowlist`)	Enforced if combined with proxy or host firewall
Integration Requirement	Route HTTP client through proxy (`localhost:8765`)	Zero code changes (prefix command with `agentsecrets env --`)
Non-HTTP Protocol Support	No (HTTP/HTTPS only)	Universal (Postgres, MySQL, Redis, Kafka, gRPC, raw TCP)

Decision Flowchart: Choosing the Right Runtime

Loading diagram...

Architectural Deep Dive: Two Complementary Security Models

1Network-Layer Proxy Interception (The Zero-Exposure Model)

For autonomous AI agents (LangChain, CrewAI, AutoGen, Claude Desktop, Cursor):

The Security Principle: The strongest way to prevent an AI agent from leaking a secret is to ensure the agent never possesses the secret in the first place.
How It Works: The application code only references the key name (OPENAI_API_KEY=OPENAI_API_KEY). When the application makes an HTTP request, the independent local proxy daemon intercepts the outbound socket, validates the target domain against the egress allowlist, resolves the secret from the OS Keychain, injects it into the HTTP headers, and transmits it over TLS.
The Guarantee: Even if an LLM is completely hijacked via prompt injection and instructed to dump all system memory and variables, it cannot reveal the secret because the secret does not exist anywhere in the application's address space.

2Process-Layer Environment Injection (The Zero-Disk Model)

For full-stack backends, databases, background workers, and containers (Django, FastAPI, Next.js, Celery, Docker):

The Security Principle: Database drivers (Postgres, Redis, MySQL) and compiled runtimes physically require credentials in system memory to establish TCP sockets and cannot be routed through HTTP proxies.
How It Works: agentsecrets env -- <command> creates a dedicated, isolated child process using the OS execve system call. The decrypted secrets are passed directly into the child process's environment array:
- Shell Isolation: The variables are never exported into your terminal shell (~/.bashrc, ~/.zsh_history).
- OS Kernel Memory Isolation: Unrelated processes, sibling terminal tabs, and background scripts running on the machine cannot read the child process's environment block.
- Real-Time Stream Redaction: The agentsecrets supervisor wraps the child's stdout and stderr in MaskingWriter. If the child process, a crash report, or a diagnostic tool prints os.environ, env, or echo $SECRET, the output is intercepted across chunk boundaries and replaced with [REDACTED].
The Guarantee: Complete eradication of plaintext .env files from developer machines and production hosts, total process boundary isolation, and automatic protection against terminal/log leakage.

Combining Both: Enterprise Defense-in-Depth

In modern cloud applications, you don't choose one over the other—you combine both into a seamless defense-in-depth architecture:

Bootstrapping & Internal Services: Use agentsecrets env to inject your database credentials, Redis URLs, and internal secrets into your application process at spawn time.
Third-Party External APIs: Route your outbound API calls (Stripe, OpenAI, Twilio, SendGrid) through the Credential Proxy (agentsecrets call or the Python SDK).

This architectural pattern gives your infrastructure complete zero-disk security for internal systems while providing unbreakable zero-exposure protection for high-value external APIs.