CortexAuth — Agent-Centric Secrets & Configuration Service
A lightweight, Rust-based secrets vault designed for AI agents and automated pipelines. Store API keys and configuration securely, discover which secrets your project needs, and inject them at runtime — without ever hardcoding secrets in source code.
Architecture
┌──────────────────────────────────────┐
│ cortex-server │
admin API │ · stores secrets (AES-256-GCM) │
Admin ─────────────►│ · authenticates agents (JWT) │
(curl / API) │ · issues project tokens │
└───────────────┬──────────────────────┘
│ ② project_token
│ ③ env vars
│
┌───────────────────────────────────┼────────────────────────┐
│ Agent │ │
│ (autonomous pipeline) │ │
│ ▼ │
│ ① cortex-cli gen-token ┌─────────────────┐ │
│ ──────────────────────► │ cortex-cli │ │
│ │ │ │
│ ④ cortex-cli run │ gen-token │ │
│ ──────────────────────► │ run → exec() │ │
└──────────────────────────┴────────┬────────┘──────────────┘
│
exec() with env vars injected
│
▼
┌─────────────────────┐
│ Project Process │
│ python main.py │
│ node app.js … │
│ │
│ OPENAI_API_KEY=... │
│ DB_PASSWORD=... │
│ AUTH_TOKEN=... │
└─────────────────────┘
Flow:
- Admin pre-loads project secrets into
cortex-servervia the admin API - Agent calls
cortex-cli gen-tokento sign a JWT (auth_proof) proving its identity - Agent posts
auth_proofto/agent/discover→ receives aproject_token - Agent calls
cortex-cli run --project <name> --token <project_token>which fetches secrets from the server andexec()s the target process with them injected as environment variables
Agent Key Management Principles
- Agents never touch secret values — secrets flow directly from
cortex-serverinto the process environment viaexec(); agent code never reads or stores them - No human intervention per task — agents autonomously obtain and inject secrets across any number of projects and tasks without requiring manual input for each run
- Fully autonomous secret injection — unattended agent pipelines retrieve all required credentials on demand at runtime; no operator in the loop
- Secrets never written to disk — API keys, database credentials, tokens, and passwords exist only in process memory as environment variables; nothing is persisted to files
Installation
Homebrew (macOS Apple Silicon)
brew tap davideuler/cortex-auth brew install cortex-auth
Note: The Homebrew tap provides pre-built binaries for Apple Silicon (M1/M2/M3) only. macOS Intel users should build from source.
Pre-built binaries (Linux / macOS Apple Silicon)
Download from the GitHub Releases page.
VERSION=v0.1.2 # Detect platform case "$(uname -s)-$(uname -m)" in Darwin-arm64) TARGET=aarch64-apple-darwin ;; Linux-x86_64) TARGET=x86_64-unknown-linux-musl ;; Linux-aarch64) TARGET=aarch64-unknown-linux-musl ;; *) echo "No pre-built binary for this platform — see Build from source below"; exit 1 ;; esac ARCHIVE="cortex-auth-${VERSION}-${TARGET}" curl -fLO "https://github.com/davideuler/cortex-auth/releases/download/${VERSION}/${ARCHIVE}.tar.gz" tar xzf "${ARCHIVE}.tar.gz" sudo mv "${ARCHIVE}/cortex-server" "${ARCHIVE}/cortex-cli" /usr/local/bin/ rm -rf "${ARCHIVE}" "${ARCHIVE}.tar.gz"
| Platform | Pre-built binary |
|---|---|
| macOS Apple Silicon (M1/M2/M3) | cortex-auth-v0.1.2-aarch64-apple-darwin.tar.gz |
| macOS Intel | — build from source |
| Linux x86_64 | cortex-auth-v0.1.2-x86_64-unknown-linux-musl.tar.gz |
| Linux ARM64 | cortex-auth-v0.1.2-aarch64-unknown-linux-musl.tar.gz |
Build from source
Requires Rust (stable).
git clone https://github.com/davideuler/cortex-auth.git cd cortex-auth cargo build --release # Binaries at: target/release/cortex-server target/release/cortex-cli
Quick Start
# Generate keys ENCRYPTION_KEY=$(openssl rand -hex 32) ADMIN_TOKEN=$(openssl rand -hex 16) # Start the server DATABASE_URL=sqlite://cortex-auth.db \ ENCRYPTION_KEY=$ENCRYPTION_KEY \ ADMIN_TOKEN=$ADMIN_TOKEN \ cortex-server # In another terminal — add a secret curl -X POST http://localhost:3000/admin/secrets \ -H "Content-Type: application/json" \ -H "X-Admin-Token: $ADMIN_TOKEN" \ -d '{"key_path":"openai_api_key","secret_type":"KEY_VALUE","value":"sk-your-key"}' # Discover project secrets (authenticate with agent_id + signed JWT) AUTH_PROOF=$(cortex-cli gen-token --agent-id my-agent --jwt-secret <agent_jwt_secret>) curl -X POST http://localhost:3000/agent/discover \ -H "Content-Type: application/json" \ -d "{\"agent_id\":\"my-agent\",\"auth_proof\":\"$AUTH_PROOF\",\"context\":{\"project_name\":\"my-app\",\"file_content\":\"OPENAI_API_KEY=\"}}" # Save the returned project_token! # Launch your app with secrets injected cortex-cli run \ --project my-app --token <project_token> --url http://localhost:3000 \ -- python3 main.py
Components
| Component | Description |
|---|---|
cortex-server |
HTTP API server (axum + SQLite). Stores secrets encrypted with AES-256-GCM. |
cortex-cli |
CLI launcher that fetches secrets and exec()s your process with them injected as env vars. |
Agent Skills Integration
The cortex-skills/ directory contains a ready-to-use skill following the
Agent Skills open standard — the same
SKILL.md format works across all major agent frameworks. Once installed, your agent
autonomously authenticates with Cortex and injects secrets without any human prompting.
| Agent | Skills directory | Docs |
|---|---|---|
| Claude Code | ~/.claude/skills/ (global) · .claude/skills/ (project) |
Extend Claude with skills |
| Codex CLI | ~/.codex/skills/ (global) · .agents/skills/ (project) |
Agent Skills – Codex |
| OpenCode | ~/.opencode/skills/ (global) · .opencode/skills/ (project) |
Agent Skills · OpenCode |
| OpenClaw | ~/.openclaw/skills/ (global) · skills/ (workspace) |
Skills – OpenClaw |
| Hermes Agent | ~/.hermes/skills/ (local) · ~/.agents/skills/ (shared) |
Skills System · Hermes |
# 1. Clone (or use your existing copy of) cortex-auth git clone https://github.com/davideuler/cortex-auth.git /tmp/cortex-auth # 2. Install the skill for your agent — pick one: # Claude Code (global) cp -r /tmp/cortex-auth/cortex-skills ~/.claude/skills/cortex-secrets # Codex CLI (global) cp -r /tmp/cortex-auth/cortex-skills ~/.codex/skills/cortex-secrets # OpenCode (global) cp -r /tmp/cortex-auth/cortex-skills ~/.opencode/skills/cortex-secrets # OpenClaw (global) cp -r /tmp/cortex-auth/cortex-skills ~/.openclaw/skills/cortex-secrets # Hermes Agent (local) cp -r /tmp/cortex-auth/cortex-skills ~/.hermes/skills/cortex-secrets
To keep the skill in sync with future cortex-auth updates, use symlinks instead of copying:
ln -sf /tmp/cortex-auth/cortex-skills ~/.claude/skills/cortex-secretsFor project-scoped installation (committed alongside your code), copy into the
agent-specific project directory (e.g. .claude/skills/cortex-secrets/).
Documentation
- Design & Architecture — System design, security model, data flow
- Usage Guide — Admin API examples, cortex-cli usage, production setup
- Open Questions — Items needing stakeholder decisions
- Roadmap — Security hardening, features, optimizations
Development
# Run all tests cargo test --workspace # Check for lint issues cargo clippy --workspace -- -D warnings # Build release binaries cargo build --release
Security Model
- Secrets encrypted at rest with AES-256-GCM (unique nonce per write)
- Agent JWT secrets stored encrypted; project tokens stored as SHA-256 hashes
- Admin operations protected by static
ADMIN_TOKEN /agent/discoverauthenticates agents directly via signed JWT (no separate session token)- Project access via one-time-issued
project_token(must be saved — cannot be recovered) - Full audit log of all secret accesses
cortex-cliusesexec()— secrets never visible to a parent process