Security & Trust¶

In a world where AI agents have tool access and can read files, make API calls, and modify your system, security isn't optional — it's foundational. Quincy is built with the assumption that the environment is adversarial: other software on your machine might try to tamper with Quincy's configuration, and the LLMs Quincy uses should never have direct access to your secrets.

Only Quincy Can Change How Quincy Behaves¶

Every configuration file Quincy manages is digitally signed. If a file was edited by a text editor, a script, or another AI tool, Quincy detects it and rejects the change. This applies to agent configs too: if someone (or something) tampers with an agent's system prompt, Quincy won't load that agent at all.

The signing key lives in the macOS Keychain, protected by the operating system. This means:

• A rogue script can't silently modify an agent's system prompt to inject malicious instructions
• An external tool can't change which model an agent uses or what scope it has
• Even renaming an agent's folder invalidates the signature, because the folder name is part of what's signed

This isn't just about malicious tampering — it also catches accidental corruption. If a backup tool, sync service, or careless edit mangles a config file, Quincy notices immediately.

Your Passwords Never Touch the AI¶

All API keys, passwords, and other secrets are stored in the macOS Keychain — never in config files, environment variables, or any other plaintext location on disk.

Here's the important part: the LLMs that Quincy uses never see your secrets. When an agent calls a tool that needs credentials (like an API call to your smart lock), the tool retrieves the credential from the Keychain at runtime and passes it directly to the external service. The credential is never included in the conversation history, the system prompt, or any message sent to the model.

The LLM sees the tool's name, description, and parameters — but not its implementation. The model knows it can call unlock_door, but it doesn't know how that tool authenticates. Even if the model were tricked by a prompt injection into trying to reveal a password, it simply doesn't have it.

You don't have to trust the model to keep secrets — it was never given any to keep.

Agents Can't Read Each Other's Secrets¶

Each agent's Keychain entries are namespaced under its identity — isolated from every other agent. This provides full isolation:

• The orchestrator can't read a sub-agent's secrets
• One sub-agent can't read another sub-agent's secrets

This matters because Quincy is designed for a world where multiple AI agents coexist on your machine. No agent can intentionally or accidentally read credentials that it's not entitled to.

What Quincy Protects Against¶

Quincy's security model provides tamper detection, not encryption at rest. Configuration files are human-readable — and that's intentional. You can inspect any agent's config to see exactly what its system prompt says, which tools it has access to, and what model it runs on. What you can't do is modify them undetected.

The assumption is:

• Your Mac's disk is protected by FileVault (Apple's full-disk encryption)
• The macOS Keychain provides secure storage for secrets
• The signatures catch unauthorized modifications to config files
• Namespace isolation in the Keychain prevents cross-agent secret access

If someone has full control of your machine, no app can save you — that's true of any software. What Quincy does protect against is the stuff that actually happens: a misconfigured tool that overwrites the wrong file, an AI agent that gets too creative with its permissions, a backup service that silently corrupts a config, or another app on your Mac poking around where it shouldn't be.

Under the Hood: Cryptographic Details¶

The sections below cover the cryptographic primitives Quincy uses. You don't need to understand these to use Quincy safely — the sections above cover everything that matters for day-to-day use.

Configuration Signing¶

Config files are signed with HMAC-SHA256. The signature is embedded directly in the file, and Quincy verifies it on every load.

Agent configs bind the agent's identity into the signature as associated data — so renaming an agent's folder invalidates the signature automatically. This prevents identity-swapping attacks where a malicious config is placed under a different agent's name.

Root Key and Key Derivation¶

All of Quincy's cryptographic operations derive from a single 256-bit root key stored in the macOS Keychain. This key is generated on first run and never leaves the Keychain.

Purpose-specific keys are derived using HKDF-SHA256 with distinct info strings:

Using HKDF with distinct info strings instead of reusing the same key for multiple algorithms is a cryptographic best practice — it ensures that a weakness in one derived key cannot compromise others.

Secret Flow Diagram¶

sequenceDiagram
    participant LLM
    participant Agent
    participant Tool
    participant Keychain as macOS Keychain
    participant API as External API

    LLM->>Agent: Call unlock_door(front)
    Agent->>Tool: Execute unlock_door(front)
    Tool->>Keychain: Retrieve smart lock PIN
    Keychain-->>Tool: PIN
    Tool->>API: Unlock request + PIN
    API-->>Tool: Success
    Tool-->>Agent: "Front door unlocked"
    Agent-->>LLM: "Front door unlocked"
    Note over LLM: Never sees the PIN