OneCLI: Securing AI Agents with a Rust-based Vault

OneCLI is an open-source vault and proxy gateway that eliminates the need for AI agents to handle raw API credentials. Built in Rust with a Next.js dashboard, it sits between your agents and external services, intercepting HTTP requests and swapping placeholder keys for real secrets. The architecture uses AES-256-GCM encryption for data at rest and runs entirely in a single Docker container with an embedded Postgres instance. Unlike traditional secret managers that require SDK integration or environment variable injection, OneCLI works transparently via HTTPS_PROXY, making it compatible with any agent framework including OpenClaw, NanoClaw, or IronClaw without code changes.

Why are raw API keys dangerous for AI agents?

AI agents process unstructured data and execute autonomous workflows, making them unpredictable attack vectors that lack the contextual judgment of human developers. When you embed raw API keys in agent prompts, environment variables, or configuration files, you expose credentials to prompt injection attacks, log leakage, and memory dumps during crash reports. Agents might accidentally paste a Stripe key into a chat log, include it in an error message sent to a logging service, or transmit it to an untrusted third-party API during tool use. Unlike human developers who understand context sensitivity and can recognize when data should remain confidential, LLMs treat tokens as interchangeable data without inherent sensitivity classification. OneCLI eliminates this risk by ensuring agents never possess actual secrets, operating instead with opaque placeholders that are meaningless if leaked, printed, or intercepted by malicious skills. This fundamental shift in credential handling mitigates the risk of insider threats and external attackers compromising your AI infrastructure.

How does OneCLI’s proxy architecture work?

OneCLI functions as a transparent HTTP/HTTPS proxy that intercepts outbound requests from AI agents before they reach external services. When an agent attempts to call an API, the request routes through OneCLI’s Rust-based proxy layer running on ports 10254 (proxy) and 10255 (dashboard). The proxy examines the Host header and request path to match against configured routes in its encrypted database. It validates that the requesting agent has permission to access that specific endpoint based on identity headers or mTLS certificates. Upon validation, OneCLI extracts the placeholder credential from the request headers, queries its encrypted vault for the corresponding real secret, and reconstructs the request with authentic authentication headers. The modified request forwards to the target service, with responses streaming back through the proxy transparently without buffering entire payloads in memory. This design ensures low latency and high throughput, crucial for real-time AI agent interactions.

What is the placeholder key system?

The placeholder key system is OneCLI’s core abstraction that decouples agent configuration from actual secrets to prevent credential exposure. Instead of storing OPENAI_API_KEY=sk-abc123 in an agent’s environment, you store OPENAI_API_KEY=onecli://prod/openai and register the real key in OneCLI’s vault. These placeholders follow a URI scheme that includes the environment and service identifier, making them human-readable and versionable. When the agent makes a request, it presents the placeholder in the Authorization header or environment variable exactly as it would a real key. OneCLI’s proxy intercepts this, validates the agent’s identity against access policies, and performs the substitution server-side before forwarding the request. If an attacker extracts the placeholder from logs or memory dumps, they gain nothing of value. The placeholder contains no cryptographic material and only resolves within OneCLI’s trusted runtime context. This system provides a robust defense against credential exfiltration.

How does OneCLI handle encryption at rest?

OneCLI encrypts all sensitive data using AES-256-GCM, the authenticated encryption standard recommended by NIST. The encryption keys are derived from a master key that you provide during initialization via environment variable or Docker secret. This master key never persists in the database; it resides only in memory during runtime. The embedded Postgres instance (PGlite) stores encrypted blobs for all credential values, route configurations, and audit logs. Each encryption operation generates a unique nonce to prevent pattern analysis. The Rust implementation uses the ring cryptographic library for constant-time operations, mitigating timing side-channel attacks. When you back up OneCLI’s data volume, you export encrypted ciphertext that remains useless without the master key, ensuring credential safety even if storage media is compromised. This robust encryption strategy is a cornerstone of OneCLI’s security posture.

Why did OneCLI choose Rust for the proxy layer?

OneCLI’s proxy layer is written in Rust to maximize performance while minimizing the attack surface and resource footprint. The proxy handles high-throughput HTTP traffic from concurrent agents without introducing latency that degrades LLM response times. Rust’s zero-cost abstractions and async runtime (Tokio) allow the proxy to process thousands of concurrent connections with minimal memory overhead, typically using less than 200MB RAM. Rust’s memory safety guarantees eliminate entire classes of vulnerabilities like buffer overflows and use-after-free errors that plague C-based proxies. The type system enforces thread safety at compile time, preventing race conditions in the credential cache. For a security-critical component that terminates TLS and handles secrets, Rust’s combination of performance and safety makes it the optimal choice over Go or C++ alternatives. This choice underscores OneCLI’s commitment to delivering a secure and efficient solution.

How does the embedded Postgres architecture work?

OneCLI uses PGlite, an embedded PostgreSQL implementation compiled to WebAssembly, to eliminate external database dependencies and simplify deployment. Traditional vault solutions require a separate Postgres, MySQL, or etcd cluster, adding operational complexity and network attack surface. OneCLI embeds the database directly in the application process, storing data in a local volume that you mount via Docker. The PGlite instance runs inside the Rust process using the pglite crate, providing full SQL compatibility without TCP sockets or UNIX domain sockets exposed to the host. This architecture means you can run OneCLI on a single machine, edge device, or air-gapped environment without configuring database connections or worrying about network partitions. Backups are simple volume snapshots, and the data directory contains standard Postgres files that you can inspect with standard tools if needed. The embedded approach trades horizontal scalability for operational simplicity and reduced network exposure, making it ideal for self-contained deployments.

What agent frameworks work with OneCLI?

OneCLI is framework-agnostic and works with any AI agent system that can route HTTP traffic through a proxy. This includes OpenClaw, NanoClaw, IronClaw, AutoGPT, and custom Python or Node.js agents. Integration requires no code changes or SDK imports. You simply set the HTTPS_PROXY environment variable to point to OneCLI’s proxy port (default 10254) in your agent’s environment. For OpenClaw specifically, you can configure the proxy in the .env file or container orchestration definitions. The agent continues using standard HTTP clients like requests, axios, or fetch; the underlying operating system or HTTP library handles the proxy routing transparently. OneCLI also supports MCP (Model Context Protocol) tools, allowing agents to invoke tools that route through the vault without exposing credentials in the MCP server configuration. This universal compatibility makes OneCLI viable for heterogeneous agent ecosystems where teams run multiple frameworks simultaneously. Its ease of integration minimizes friction for existing agent deployments.

How do you deploy OneCLI in production?

Production deployment of OneCLI centers on the single Docker container with proper volume management and network isolation. Start by pulling the official image: docker pull ghcr.io/onecli/onecli. Run the container with a named volume for data persistence and port mappings for the proxy (10254) and dashboard (10255). You must provide a strong master key via environment variable or Docker secret; this key initializes the encryption layer. For high availability, run multiple OneCLI instances behind a load balancer with shared storage (NFS or block storage) mounted to each container’s data directory. The proxy is stateless except for the embedded database, so you can scale horizontally by sharing the volume. Place OneCLI in a private subnet with restricted egress, allowing it to reach only approved API endpoints while agents route through it. Monitor container health and log aggregation to detect anomalies or unauthorized access attempts. Regular backups of the data volume are also crucial for disaster recovery.

Example Docker Compose Configuration for OneCLI

For a robust production deployment, using Docker Compose can simplify the setup and ensure all necessary configurations are in place. Here’s an example:

version: '3.8'
services:
  onecli:
    image: ghcr.io/onecli/onecli:latest
    container_name: onecli_proxy
    restart: unless-stopped
    ports:
      - "10254:10254" # Proxy port
      - "10255:10255" # Dashboard port
    volumes:
      - onecli_data:/app/data # Persistent storage for PGlite database
    environment:
      # IMPORTANT: Replace with a strong, securely generated master key
      # Use `openssl rand -hex 32` to generate a 64-character hex string
      - ONECLI_MASTER_KEY=${ONECLI_MASTER_KEY} 
      # Optional: Configure dashboard authentication
      - ONECLI_ADMIN_USER=${ONECLI_ADMIN_USER}
      - ONECLI_ADMIN_PASSWORD=${ONECLI_ADMIN_PASSWORD}
    networks:
      - onecli_network

volumes:
  onecli_data:
    driver: local

networks:
  onecli_network:
    driver: bridge

This configuration ensures data persistence, proper port mapping, and network isolation. Remember to manage the ONECLI_MASTER_KEY and dashboard credentials securely, ideally through Docker secrets or an environment variable management system, rather than hardcoding them directly in the compose file.

How does OneCLI compare to traditional secret managers?

Traditional secret managers like HashiCorp Vault, AWS Secrets Manager, or Doppler require SDK integration or sidecar injection, adding complexity to agent architectures. OneCLI eliminates code changes by operating at the network layer as a transparent proxy. Traditional solutions often return secrets to the application, which then stores them in memory or environment variables where agents might leak them. OneCLI never transmits real secrets to agents; it performs the substitution server-side within the proxy. This architecture prevents credential exfiltration even if the agent host is compromised. However, traditional secret managers offer more granular policy engines and native cloud integrations. OneCLI trades some enterprise features for simplicity and agent-specific security. It is not a replacement for enterprise PKI or complex rotation schemes, but rather a specialized tool for the unique threat model of autonomous AI agents that process untrusted inputs. It serves as an excellent complement to existing enterprise security infrastructure.

OneCLI vs traditional secret managers: Feature comparison

When evaluating OneCLI against enterprise secret management solutions, you must consider the trade-offs between agent-specific security and general-purpose flexibility. OneCLI optimizes for the unique threat model of autonomous AI agents that process untrusted inputs and may leak memory contents through logs or error messages. Traditional managers like HashiCorp Vault or AWS Secrets Manager optimize for broad infrastructure support, complex rotation schemes, and enterprise compliance certifications. OneCLI operates on a different model: it assumes agents are compromised by default and ensures they never touch real secrets. The following table breaks down the key differences across architecture, security model, and operational characteristics to help you decide which approach fits your agent infrastructure.

Feature	OneCLI	Traditional Secret Managers (e.g., HashiCorp Vault)
Primary Use Case	Securing AI agent API keys, preventing exfiltration	General-purpose secret management for applications, infrastructure
Integration Method	Transparent HTTP/HTTPS proxy (no code changes)	SDK integration, sidecar injection, CLI tools
Secret Exposure to Application	Never; substitution happens within proxy	Secrets provided to application memory/environment
Architectural Model	Single Docker container, embedded database	Distributed cluster, external database dependencies
Encryption at Rest	AES-256-GCM, master key in memory	Varies (often AES-256), supports KMS/HSM integration
Deployment Complexity	Low (single container, volume mount)	Moderate to High (HA clusters, network configuration)
Protocol Support	HTTP/HTTPS only	Broad (databases, SSH, cloud APIs, custom)
Access Control Granularity	Host/path-based policies, agent identity	Fine-grained, role-based access control (RBAC), ACLs
Compliance Certifications	Limited (new software)	Extensive (SOC 2, ISO 27001, PCI DSS, FIPS 140-2)
Key Rotation	Hot reload from vault, manual/API driven	Automated, policy-driven, integrated with PKI
Audit Logging	Local audit logs	Centralized, integrated with SIEM systems
Scalability	Horizontal via shared volume + load balancer	Highly scalable, designed for enterprise workloads
Dependency Management	Self-contained (embedded PGlite)	External database, possibly other services

OneCLI sacrifices some enterprise features like automatic secret rotation and HSM support for simplicity and agent-specific security guarantees that prevent credential exfiltration even during total host compromise. It is a specialized tool designed to solve a specific, critical security problem in the AI agent ecosystem. When paired with a broader enterprise secret management strategy, OneCLI can significantly enhance the security posture of your autonomous systems.

What are the access policy capabilities?

OneCLI implements host and path-based access policies that restrict which APIs each agent can reach, creating a zero-trust perimeter around external service access. You define rules in the dashboard or via API that map specific agent identities (e.g., source IP, mTLS certificate common name, or custom header) to allowed destination hosts and URL paths. For example, you can configure a policy that dictates an “OpenClaw-Finance” agent can only access api.stripe.com/v1/payments and api.plaid.com/*, but is explicitly denied access to api.openai.com. This prevents malicious or misconfigured agents from accessing unauthorized services, even if they somehow obtain a valid placeholder key for that service. The policy engine evaluates these rules before any secret substitution occurs, ensuring that only legitimate requests proceed. This capability is vital for enforcing least privilege principles in your AI agent deployments.

Defining Access Policies

Access policies in OneCLI are structured around a combination of agent identification and target resource specification. When an incoming request arrives at the OneCLI proxy, it first attempts to identify the requesting agent. This can be done via:

1. Source IP Address: Restricting access based on the IP address of the machine running the AI agent.
2. Custom HTTP Headers: Agents can send a unique header (e.g., X-Agent-ID: my-finance-agent) which OneCLI uses for identification.
3. mTLS Certificates: For higher security, agents can present a client certificate, and OneCLI can use the certificate’s Common Name (CN) or other attributes for identification.

Once the agent is identified, OneCLI consults its policy database. A policy typically consists of:

• Agent Identifier: The specific ID or pattern that matches the requesting agent.
• Allowed Hosts: A list of external domain names (e.g., api.openai.com, api.stripe.com) that the agent is permitted to communicate with.
• Allowed Paths: Granular URL paths (e.g., /v1/chat/completions, /v1/payments/*) within those allowed hosts that the agent can access.
• Denied Hosts/Paths: Explicitly forbidden resources, which can override broader allow rules for more precise control.

This multi-faceted approach allows administrators to craft detailed security boundaries for each AI agent, preventing lateral movement or unauthorized data access, even if an agent’s internal logic is compromised.

How does OneCLI ensure high availability and load balancing?

Achieving high availability (HA) with OneCLI involves deploying multiple instances behind a load balancer, mirroring common patterns for stateless microservices. Since OneCLI’s proxy layer is stateless and its embedded database (PGlite) stores data in a persistent volume, you can scale horizontally by mounting a shared storage volume (like NFS, EFS, or a clustered block storage solution) to each OneCLI container. A load balancer (e.g., Nginx, HAProxy, AWS ALB, Kubernetes Ingress) then distributes incoming agent traffic across these OneCLI instances.

When an instance receives a request, it accesses the shared encrypted database for credential lookups and policy evaluations. If one OneCLI instance fails, the load balancer reroutes traffic to healthy instances, ensuring continuous service without interruption to agent operations. This architecture provides fault tolerance and allows for zero-downtime updates by draining traffic from old instances and directing it to new ones. Health checks configured on the load balancer can monitor the /health endpoint of each OneCLI instance, automatically removing unhealthy instances from the rotation and adding them back once they recover. This distributed setup is crucial for production environments where AI agents require constant access to external services.

What is the dashboard and API for OneCLI?

OneCLI provides a user-friendly Next.js-based dashboard and a RESTful API for managing secrets, policies, and configurations. The dashboard, accessible on port 10255 by default, offers a visual interface for:

• Secret Management: Securely adding, editing, and deleting API keys and other credentials, which are immediately encrypted and stored in the vault.
• Policy Configuration: Defining and managing access control policies for specific agents and external services, specifying allowed hosts and paths.
• Audit Logs: Viewing a chronological record of all proxy requests, credential access, and policy enforcement decisions, providing an essential trail for security monitoring and compliance.
• System Health: Monitoring the operational status of the OneCLI instance and its embedded database.

The RESTful API provides programmatic access to all dashboard functionalities, enabling automation of secret rotation, policy updates, and integration with CI/CD pipelines or infrastructure-as-code tools. For example, you can use the API to dynamically inject new secrets when a service key expires or to update access policies as your agent ecosystem evolves. Both the dashboard and API are secured with optional basic authentication or can be integrated with more robust identity providers in enterprise setups, ensuring that only authorized personnel or systems can manage your OneCLI instance.

Example API Usage for Adding a Secret

To add a new secret for an OpenAI API key using the OneCLI API, you might send a POST request to the /api/secrets endpoint with a JSON payload.

curl -X POST \
  http://localhost:10255/api/secrets \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Basic YWRtaW46cGFzc3dvcmQ=' \
  -d '{
    "name": "prod/openai",
    "value": "sk-your_actual_openai_key_here",
    "description": "Production OpenAI API key for general agent use"
  }'

In this example, YWRtaW46cGFzc3dvcmQ= is the Base64 encoding of admin:password (replace with your actual credentials). The name field corresponds to the onecli:// placeholder format, making it easy to map secrets to their usage. This programmatic interface allows for seamless integration into existing operational workflows.

What is the future roadmap for OneCLI?

The roadmap for OneCLI includes several key enhancements aimed at expanding its capabilities and further hardening its security posture. High on the priority list is the implementation of gRPC and WebSocket protocol support, which will enable OneCLI to secure a broader range of AI agent communications, including real-time streaming data and microservice interactions. This will involve developing new interception and substitution logic tailored to these protocols.

Another significant area of development is enhanced identity management, including deeper integration with external identity providers (IdPs) like OAuth2/OIDC and SAML. This will allow for more sophisticated agent authentication and authorization, moving beyond simple IP or header-based identification to leverage existing enterprise identity frameworks.

Automated secret rotation is also a planned feature, enabling OneCLI to automatically generate new secrets, update them in the vault, and potentially even trigger updates in external services, reducing manual overhead and improving security hygiene. This could involve integration with KMS providers or external secret generation tools.

Furthermore, the team plans to explore HSM (Hardware Security Module) integration for master key management, offering the highest level of protection for the root of trust. This would be particularly relevant for highly regulated industries and compliance-driven environments. Community feedback and contributions will also play a crucial role in shaping the ongoing development and prioritization of new features for OneCLI, ensuring it continues to meet the evolving security needs of the AI agent landscape.