The Dual-Engine Model

AgentSecrets is architected as a Dual-Engine System. This ensures that the exact same application code, CLI commands, and SDK calls operate consistently across local development workstations and cloud production environments without modification.

                                    DUAL-ENGINE ROUTING
                                             │
                       ┌─────────────────────┴─────────────────────┐
                       ▼                                           ▼
             [ LOCAL ENGINE ]                            [ CLOUD ENGINE ]
             - Local Workstations                        - Cloud Containers / CI / Serverless
             - Resolves from OS Keychain                 - Resolves via Cloud Resolver
             - Zero calls to AgentSecrets servers        - Scoped Workload Tokens (agt_prod_...)
             - Local development credentials             - Centralized production credentials

The 4-Tier Precedence Hierarchy

Whether executing CLI commands or dispatching HTTP requests via the Python SDK, AgentSecrets evaluates the execution environment using a strict 4-tier precedence hierarchy:

Loading diagram...

Tier	Trigger Mechanism	Target Engine	Primary Use Case
1. CLI Flag / Code Config	`--cloud` flag OR `settings.use_cloud = True`	Cloud Engine	1-off local debugging against Cloud staging secrets
2. Global Environment Var	`AGENTSECRETS_USE_CLOUD=true` (or `1`)	Cloud Engine	Global shell configuration or local Docker emulation
3. Headless Auto-Detection	`AGENTSECRETS_TOKEN=agt_...` present	Cloud Engine	Production containers (Docker, ECS, Kubernetes, Vercel)
4. Default Fallback	None (Standard workstation)	Local Engine	Zero-network local development from OS Keychain

Code & Integration Patterns

1Python SDK Integration

Applications using the Python SDK utilize the built-in credential helper. The SDK routes requests to the local proxy or Cloud Resolver based on your settings configuration, automatically defaulting to cloud resolution when running in headless container environments:

from agentsecrets import AgentSecrets, credential

# Routes via local proxy on developer laptops, Cloud Resolver in headless containers
secrets = AgentSecrets()

response = secrets.call(
    "https://api.stripe.com/v1/customers",
    method="GET",
    headers={"Authorization": f"Bearer {credential.STRIPE_KEY}"}
)

print("Response Status:", response.status_code)
print("Data:", response.json())

2Transparent Interception (Stripe, OpenAI, LangChain)

For applications that interface with third-party SDKs (such as the official openai or stripe packages), enable ambient proxying with install_interceptor():

import openai
from agentsecrets import install_interceptor

# Transparently intercepts outbound HTTP traffic
install_interceptor()

# Injects OPENAI_API_KEY on the wire automatically
client = openai.OpenAI()
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Analyze system performance"}]
)

3Programmatic Configuration Overrides

You can explicitly configure resolution behavior in code:

from agentsecrets import settings

# Explicitly force cloud resolution
settings.use_cloud = True

# Optionally override Cloud Resolver endpoint (for self-hosted clusters)
settings.cloud_resolver_url = "https://resolver.agentsecrets-website.vercel.app"

4Headless Container Execution ()

For containerized applications that read environment variables on initialization:

# On your workstation: resolves from local OS Keychain
agentsecrets env -- npm run dev

# Testing against cloud secrets locally:
agentsecrets env --cloud -- npm run dev

# In Docker: automatically detects AGENTSECRETS_TOKEN and reads from Cloud
agentsecrets env -- node server.js

5Production Dockerfile Specifications

Install the CLI in container images using standard package managers:

# Node.js Container:
FROM node:20-alpine
WORKDIR /app
COPY . .
RUN npm install -g @the-17/agentsecrets
ENTRYPOINT ["agentsecrets", "env", "--", "node", "server.js"]

# Python Container:
FROM python:3.11-slim
WORKDIR /app
COPY . .
RUN pip install agentsecrets-cli
ENTRYPOINT ["agentsecrets", "env", "--", "python", "main.py"]

Architectural Benefits

Elimination of .env Drift: Eliminates the risk of developers sharing unencrypted .env files or running stale credentials locally.
Autonomous Local Development: Local secret resolution executes entirely within the operating system keychain without depending on an external network connection or remote secret vault.
Zero Application Refactoring: Moving an application from local development to production Kubernetes clusters requires zero changes to application code.