Running Any Process

The agentsecrets env command allows you to run any script, application, or tool with secrets injected directly from your secure local OS Keychain. It acts as a lightweight parent process wrapper, completely eliminating the need for plaintext .env configuration files on your system.

Process Spawn Mechanics

When you execute a command using agentsecrets env -- <command>, AgentSecrets performs a secure, multi-stage spawn operation:

1. Target Context Verification: The CLI reads the active workspace, project, and environment config in the execution directory.
2. Local Keychain Read: It queries the OS Keychain (macOS Keychain, Windows Credential Manager, or Linux Secret Service) for the secrets belonging to the active environment namespace.
3. Decryption: It decrypts the stored values locally.
4. Child Process Spawning: The CLI spawns the target command as a child process, passing the decrypted secrets directly into the environment variable array of the child process.
5. Memory Clean: The parent CLI process immediately overwrites the plaintext secrets in its own RAM and exits, leaving the child process running with the injected variables in its process memory.

Because the values are passed directly to the OS spawn call, they are ephemeral:

• They are never written to any file on disk.
• They are not accessible to other users or unrelated processes on the machine.
• They disappear completely from system RAM the moment the child process exits.

Language & Runtime Examples

Because environment injection happens at the operating system level, it is completely language-agnostic.

Python

Run django, flask, fastapi, or custom scripts:

agentsecrets env -- python main.py

Inside your script:

import os
# Accessible as standard environment variables
openai_key = os.environ.get("OPENAI_KEY")

Node.js / TypeScript

Run Next.js, Express, Vite, or NestJS servers:

agentsecrets env -- npm run dev

Inside your JavaScript code:

// No dotenv packages required
const stripeKey = process.env.STRIPE_KEY;

Go

Run compiled Go binaries:

agentsecrets env -- ./my-server

Inside Go:

package main
import (
    "fmt"
    "os"
)
func main() {
    stripeKey := os.Getenv("STRIPE_KEY")
}

Docker Compose

You can pass credentials into container runtimes without exposing them in your Compose files:

agentsecrets env -- docker compose up

In your docker-compose.yml:

services:
  web:
    image: my-app:latest
    environment:
      - STRIPE_KEY # Docker inherits this from the host shell environment

Real-Time Output Stream Masking & Redaction

Even when credentials reside in child process memory, agentsecrets env includes a real-time bidirectional stream interceptor on stdout and stderr.

If the spawned child process, a crash report, or a debugging log prints injected secrets to the terminal, AgentSecrets automatically scans the output stream and redacts them before display:

Multi-Encoding Detection

The stream masking engine detects and redacts secret values across multiple encoding formats:

• Raw plaintext strings: sk_live_51ABC... -> [REDACTED]
• Base64 encoded variants: c2tfbGl2ZV81MUFCQy4uLg== -> [REDACTED]
• Hexadecimal encoded variants: 736b5f6c697665... -> [REDACTED]
• URL/Percent-encoded variants: sk_live_%35%31ABC... -> [REDACTED]

$ agentsecrets env -- python -c "import os; print('My key is:', os.environ['STRIPE_KEY'])"
My key is: [REDACTED]

Security Guarantees and Constraints

While environment injection provides compatibility with existing applications, it has a different security model than the transport-layer proxy:

Process Memory Context: Secrets injected into environment variables reside in the target child process RAM. If you are building an AI agent that is given direct tool access to run system commands (like env, printenv, or arbitrary shell scripts), the agent could inspect its own process environment.

For autonomous AI agents, always use the Credential Proxy (client.call) or Transparent HTTP Interception (init()) instead of environment variable injection.