Icebox CLI

Icebox gives AI agents powerful tools without storing secrets in agent state.

Secure credential broker for AI agents. Never expose API keys or passwords to OpenClaw (or any agent) -- local Mac CLI using Secure Enclave + encrypted vault.

WARNING -- ALPHA SOFTWARE Icebox is in early alpha. While it is designed to be a security product, it has not yet been independently audited. There may be bugs, incomplete implementations, or undiscovered vulnerabilities. Do not rely on Icebox as your sole security layer for production secrets. Use with caution, review the code, and report any issues you find.

Pre-MVP — Not production-ready; not rolled out or released yet.

---

Vision

Icebox is a credential broker for AI agents with strict secret-handling boundaries.

It is designed so secrets are encrypted at rest, unwrapped only at execution time, and never persisted in agent state.

Why

AI agents need API keys to do useful work -- but most approaches leak those keys into agent memory, logs, or files. Icebox is the middleman that injects secrets into trusted command execution with explicit isolation controls.

"Give your agent superpowers. Keep keys out of agent memory and logs."

Install

Coming soon. Icebox is not yet released. Once E1 (bootstrap) is complete:

# Option 1: Cargo install (dev only — unsigned binary, limited enclave access)
cargo install icebox-cli

# Option 2: Download signed binary (macOS) — recommended for production
# curl -sSL https://icebox.my/install.sh | sh

Requires macOS (Apple Silicon or Intel T2) for full security flow in MVP. ~/.icebox/ must be on a local filesystem -- not iCloud Drive, Dropbox, NFS, or any synced/network drive (see Architecture and Vault & Integrity).

Secure Enclave Prerequisites (MVP)

For real Secure Enclave key creation (register-agent local-enclave path), ensure:

• Supported hardware (Apple Silicon, or Intel Mac with T2-class Secure Enclave support)
• Signed binary with required entitlements (for example keychain-access-groups) and hardened runtime for release
• Normal user Terminal context (not root/system daemon context)

Quick local prereq check:

scripts/verify_secure_enclave_prereqs.sh target/release/icebox-cli

Environment

• ICEBOX_HOME: override Icebox storage root (default: ~/.icebox).
• Example:

  ICEBOX_HOME=/tmp/icebox-dev icebox-cli register-agent claw

Key Features (MVP)

Feature	Description	Status
Agent Identity	icebox register-agent claw -- creates Ed25519 keypair (Secure Enclave-wrapped) + isolated vault per agent	Planned
Identity Lanes	local-enclave (MVP-first) and paired-remote-signer (post-MVP) share identity contract with backend-specific implementation	Planned
Recovery Model (MVP)	If a device is lost, regenerate provider API keys/tokens and re-add them to a new agent. Seed-based recovery is deferred.	MVP
Seed Backup (Optional)	icebox register-agent claw --seed -- 24-word recovery phrase for portability/cross-device recovery (guide)	Phase 1.5
Secure Vault	Per-agent encrypted vault (~/.icebox/identities/<name>/vault.enc) using crypto_box_seal (libsodium-compatible)	Planned
Add Secret	icebox add openai sk-... -- encrypted to the agent's public key	Implemented (MVP slice)
List Secrets	icebox list -- shows service names (no values)	Planned
Service Inventory	icebox list --services outputs service names only (no secret values) for regeneration checklists	Planned
Remove Secret	icebox remove openai -- deletes a stored secret	Planned
Run Secure Command	icebox run openai "curl ..." -- decrypts, injects, runs, returns result	Planned
Multi-Agent	--agent <name> one-shot targeting on all commands + use-agent <name> to change persistent default; isolated vaults per agent	Planned
DID Support	did:key identity commands and did:web publishing	Phase 1.5
Secret-Handling Boundary	Icebox keeps secrets out of long-lived agent state and injects them only at execution time into trusted subprocesses; those subprocesses can still exfiltrate via stdout/stderr/files/network	Planned

Current State

v0.1.0-alpha -- E1 foundation + initial E2 identity bootstrap (register-agent).

Status tracking split:

• Short project snapshot lives here.
• Detailed execution status lives in docs/plan/CURRENT_STATE.md.
• Packet lifecycle source of truth lives in docs/plan/task-status.json.

The CLI runs and supports --help, --version, and --debug.

register-agent is available for initial identity bootstrap (creates identity directory + identity.pub, enclave.keyref, wrapped key.enc, and updates config.json). Agent names must match [a-z0-9-]{3,32} (lowercase, 3–32 chars).

Identity Artifacts (register-agent)

Under ~/.icebox/ (or $ICEBOX_HOME/), bootstrap creates config.json (agent registry and activeAgentId) and under identities/<name>/:

File	Format	Purpose	Security
enclave.keyref	UTF-8 text label	Stable lookup label/reference for per-agent device wrapping key	Not key material
identity.pub	32-byte binary (Ed25519 public key)	Public identity key for verification/derivation flows	Safe to share
key.enc	Binary wrapped blob	Wrapped Ed25519 private key bytes for local-enclave lane	Opaque private-key material (not plaintext)

Notes:

• identity.pub is raw 32-byte Ed25519 in current MVP sequencing; multicodec-prefixed encoding is planned in E2-05.
• key.enc is intentionally treated as opaque storage bytes. Its exact production encoding is backend-defined and not a stable public format contract.

Credential execution is not available yet (run pending), but credential storage is now available via add.

Current implementation lane: local-enclave bootstrap path only.

Non-Functional Requirements

• Platform: macOS only (Apple Silicon + Intel T2; Secure Enclave hardware key wrapping)
• Language: Rust (single binary, no runtime, memory-safe by default)
• License: MIT (open source from day 1)
• Security: No logs, no clipboard, no outbound network from the icebox process in v1
• Performance: < 50ms overhead per credential use
• Install: cargo install (dev) or signed binary (production)

Linux Status

• Today (MVP): Full-flow operation is macOS-only due to Secure Enclave dependency.
• What works on Linux now: contributors can build/test non-enclave paths (CLI/config/vault/crypto/schemas).
• Linux full-flow plan: post-v0.1.1 discovery track (earliest Phase 2 planning), no committed GA date yet.
• Candidate Linux key backends: TPM-backed wrapping, OS keyring-backed wrapping, software-only fallback mode for CI/dev (lower security guarantees), and external hardware token paths (for example YubiKey via PIV/PKCS#11), all subject to evaluation.

See docs/architecture/platform-and-distribution.md for the canonical platform strategy.

Roadmap

Phase	Focus
Phase 1 (MVP)	CLI core -- agent identity, encrypted vault, secure run
Phase 1.5	DID support (did:key + did:web) + seed backup (--seed, recovery, export/import)
Phase 2	Unix socket server + OpenClaw skill integration
Phase 3	Browser extension (token-based login)

Project Management

• Repository: github.com/torbenanderson/icebox-cli
• Issues: GitHub Issues
• Pull requests: GitHub Pull Requests
• Releases: GitHub Releases
• Roadmap: docs/plan/ROADMAP.md | Backlog
• Architecture decisions: docs/architecture/decisions/
• Discussion log: docs/process/DISCUSSION_LOG.md

Documentation

• Docs index: docs/README.md
• Architecture: docs/architecture/README.md
• Planning: docs/plan/README.md
• Maintenance: docs/maintenance/README.md
• Reference: docs/reference/VERSIONING.md, docs/reference/error-codes.json
• Guides: docs/guides/BACKUP.md
• Contributing: CONTRIBUTING.md
• Security policy: SECURITY.md
• Code of conduct: CODE_OF_CONDUCT.md
• OpenClaw community on-ramp: .github/OPENCLAW_COMMUNITY_ONRAMP.md

Local Docs Commands

# mdBook (guides/architecture/planning docs from docs/)
mdbook build
mdbook serve --open

# Rust API docs (from source comments /// and //!)
cargo doc --workspace --all-features --no-deps
RUSTDOCFLAGS="-D warnings" cargo doc --workspace --all-features --no-deps

# Optional: run rustdoc examples as doctests
cargo test --doc

Rustdoc output path:

• target/doc/icebox_cli/index.html

Local CI Commands

# Rust checks (matches .github/workflows/ci.yml)
cargo fmt --all --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test --all-targets --all-features

# Docs checks (matches .github/workflows/docs-site.yml)
mdbook build
cargo doc --workspace --all-features --no-deps

Start Coding

• Planning index: docs/plan/README.md
• Current state: docs/plan/CURRENT_STATE.md
• Status model: docs/plan/STATUS_MODEL.md
• Issue drafts for MVP Core: docs/plan/BOOTSTRAP_ISSUES.md

First Run

To create your first agent, run:

icebox register-agent claw

This creates the agent identity, Secure Enclave wrapping key, and updates the config registry. Each agent gets its own identity and vault. Use --agent <name> to target a specific command invocation, or icebox use-agent <name> to change the persistent default.

(Interactive first-run prompt is planned in E2-10.)

Backup & Recovery

Icebox stores rotatable credentials (API keys/tokens), not irreplaceable assets. In MVP, if a device is lost, the practical recovery flow is to register a new agent, regenerate keys from providers (OpenAI, GitHub, Stripe, etc.), and re-add them.

Phase 1.5 adds optional seed-based recovery (--seed) for portability/cross-device workflows. MVP prioritizes hardening the core security model first. See the Backup & Recovery Guide for full details.

Debugging

Icebox shows minimal, non-technical errors by default. For troubleshooting, add --debug:

icebox run openai "curl ..." --debug

Do not use --debug in production or when sharing output -- it includes internal paths and crypto details.

Trust Boundary

icebox run should execute trusted commands only. Icebox controls secret handling in its own process and avoids persisting secrets in agent state, but the executed subprocess still receives the injected credential and can exfiltrate it via stdout/stderr, files, or network.

Approval/session note: protected-operation flows are moving toward explicit outcomes (ok, pending_approval, denied, expired) as broker/mobile lanes are introduced.

License

MIT

---

Version: 0.1 (MVP) | icebox.my | Date: March 2026