AgentSecrets Cloud Overview & Architecture
AgentSecrets Cloud is the zero-knowledge credential data plane for distributed workloads, CI/CD pipelines, and autonomous AI agents in production.
While the local AgentSecrets CLI secures credentials on developer workstations using native OS Keychains (macOS Keychain, Linux Secret Service, Windows Credential Manager), AgentSecrets Cloud extends these zero-knowledge guarantees to cloud environments: resolving credentials in volatile, non-swappable RAM on the wire, enforcing workspace-wide egress domain allowlists, and streaming tamper-evident audit logs across your fleet.
The Security Problem in Cloud Deployments
When deploying AI agents or microservices to cloud environments (Docker, AWS ECS, Render, Vercel, Kubernetes), the operating system's native keychain is unavailable.
Traditionally, teams are forced to fall back on passing plaintext API keys as environment variables. In modern AI architectures, this creates severe vulnerability surfaces:
- Prompt Injection & Context Exfiltration: An autonomous agent processing untrusted user input can be manipulated into outputting its environment variables or secret strings into chat responses or LLM prompt context.
- Supply Chain & Dependency Compromise: Third-party packages (via NPM, PyPI, or Go modules) running in the same process space can inspect
process.envor read local disk files to exfiltrate keys. - Observability & Error Leakage: Unhandled exceptions, stack traces, and debug logs frequently reflect raw authorization headers into centralized logging systems (Datadog, CloudWatch, Sentry).
AgentSecrets Cloud eliminates these failure modes by keeping plaintext credentials completely outside the application runtime.
Loading diagram...
Core Architectural Guarantees
1Ephemeral In-Memory Execution
Decrypted workspace encryption keys and credential values never touch disk, swap space, or persistent storage. Decrypted key material exists solely in volatile memory buffers locked with mlock(2) system calls via memguard. Memory buffers are immediately overwritten with cryptographic zeros upon process termination.
2Client-Encrypted Delegation (CEDK)
AgentSecrets Cloud utilizes X25519 asymmetric cryptography and NaCl SealedBoxes. Your workspace master Data Encryption Key (DEK) is encrypted client-side on your workstation before upload. The central control plane stores opaque ciphertext; only the isolated Cloud Resolver unseals the DEK in temporary RAM during authorized execution.
3Egress Domain Allowlist Firewall
Before any credential placeholder is resolved, the Cloud Resolver evaluates the outbound target URL against your workspace allowlist using sub-microsecond radix tree matching. If an agent attempts to route a credential to an unauthorized host, the request is terminated immediately with 403 Forbidden (domain_blocked), and no secret is ever decrypted or sent.
4Active Response Redaction
Upstream API responses are scanned in real time across multiple encoding variants (Plaintext, Base64, Hex, URL-encoded, and JSON-escaped). If an upstream provider echoes a credential in an error message or response payload, the scanner replaces the value with [REDACTED] before returning data to the calling agent.
Execution Modes in the Cloud
AgentSecrets Cloud supports three execution models depending on your infrastructure:
1Container Startup Ingestion ()
Runs your application or container entrypoint directly:
agentsecrets env -- node server.js
The CLI authenticates using a scoped Workload Token (AGENTSECRETS_TOKEN), retrieves project secrets over TLS, and injects them directly into child process memory. No .env files are written to disk.
2Python SDK & Transparent Proxy
Integrates directly into your application codebase:
from agentsecrets import AgentSecrets, credential secrets = AgentSecrets() response = secrets.call( "https://api.stripe.com/v1/charges", method="POST", headers={"Authorization": f"Bearer {credential.STRIPE_KEY}"}, body={"amount": 2000, "currency": "usd"} )
The SDK passes the placeholder reference (credential.STRIPE_KEY). The Cloud Resolver injects the real key on the wire over TLS and returns the clean API response.
3Direct REST Resolution ()
Enables serverless functions (AWS Lambda, Cloudflare Workers) and custom tool-calling agents to resolve credentials via standard HTTP requests without running a local proxy daemon.
Local Engine vs. AgentSecrets Cloud
| Capability | Local Engine (Workstation) | AgentSecrets Cloud (Production) |
|---|---|---|
| Primary Environment | Developer Laptops (macOS, Linux, Windows) | Containers, VMs, Serverless, AI Agents |
| Secret Storage | Local OS Keychain (Apple Keychain, Secret Service) | Ephemeral Volatile RAM via Client-Encrypted DEK |
| Connection to AgentSecrets servers? | Not required (Resolves locally from OS Keychain) | Required (Connects to Cloud Resolver) |
| Authentication | Local login session | Scoped Workload Tokens (agt_prod_...) |
| Audit Logging | Local SQLite file | Centralized real-time log stream on Web Dashboard |
| Domain Firewall | Local allowlist | Central workspace domain allowlist |
Next Steps
- The Dual-Engine Model: Learn how the CLI and SDK route between local and cloud environments.
- Cloud Resolver Data Plane: Explore the internal architecture, memory isolation, and redaction engine.
- Workload & Agent Tokens: Issue and scope cryptographic tokens for Docker and CI/CD.
- Egress Allowlists & Audit Streams: Configure domain firewalls and monitor live execution logs.
- Cloud REST API Reference: Review endpoint contracts, request schemas, and error codes.