cellar-door

Local-first automation gateway + memory system for agents — model-agnostic, safe by default, and auditable.

cellar-door is designed for power users and teams who want automation and memory without opaque behavior or runaway context. It is retrieve-first, default-deny, and explicit about side effects.

Why cellar-door

Most agent tools either:

• load too much context, burning tokens and slowing down over time
• hide or bypass dangerous actions
• lock you into a specific model vendor

cellar-door fixes this by enforcing retrieval over loading, policy-gated tool execution, and provider-agnostic model access.

Core Principles

• Retrieve, don’t load. Memory is retrieved under a strict token budget.
• Default-deny dangerous actions. Side effects require explicit approval.
• Make power visible and auditable. Every tool call is logged with intent and outcome.
• Model-agnostic by design. Bring your own model (cloud or local).
• No silent escalation. Permissions are explicit and time-bounded.

Installation

Run without installing

npx cellar-door setup
npx cellar-door doctor

Install locally (project-only)

npm install cellar-door
npm exec -- cellar-door setup

You can also run the local binary directly:

./node_modules/.bin/cellar-door setup

Install globally

npm install -g cellar-door
cellar-door --help

Setup (Local)

cellar-door is local-first. Configuration and data live in ~/.cellar-door/.

1. Initialize config:

cellar-door setup

If you already have a config and want to re-run setup prompts:

cellar-door setup --force

2. Configure a model provider in ~/.cellar-door/config.json:

Secrets are stored in ~/.cellar-door/.env (recommended) and referenced by config.json. The setup wizard fetches available models from your provider and lets you select one, so you don't need to type model IDs manually. The base URL is the API root (e.g., https://api.openai.com/v1), and the wizard can save secrets so you don't need to export env vars in your shell.

OpenAI-compatible HTTP

{
  "version": 1,
  "modelProvider": {
    "kind": "http",
    "baseUrl": "https://api.openai.com/v1",
    "model": "gpt-4o-mini",
    "headers": { "Authorization": "Bearer $OPENAI_API_KEY" }
  }
}

Ollama

{
  "version": 1,
  "modelProvider": {
    "kind": "ollama",
    "model": "llama3"
  }
}

LM Studio

{
  "version": 1,
  "modelProvider": {
    "kind": "lmstudio",
    "model": "local-model"
  }
}

3. (Optional) Set policy and tooling defaults:

{
  "approvedModelProviders": ["http", "ollama", "lmstudio"],
  "workspaceRoot": "~/dev/my-project",
  "userIdentity": "alice",
  "network": { "allowDomains": ["api.github.com"] },
  "tools": {
    "execEnabled": false,
    "browserEnabled": false,
    "browserHeadless": false,
    "desktopEnabled": false
  },
  "policy": {
    "allowTools": ["fs.read", "git.status"],
    "allowDomains": ["api.github.com"],
    "allowUi": false,
    "allowDesktop": false,
    "allowHeadless": false
  },
  "tokenBudgets": {
    "bootstrapMax": 2000,
    "hotMax": 1500,
    "warmMax": 2500
  }
}

Quickstart

cellar-door setup
cellar-door doctor
cellar-door run "Summarize the repo"

CLI Commands

| Command | Description | | --- | --- | | cellar-door setup | Initialize config and local data directory | | cellar-door init | Alias for setup | | cellar-door doctor | Verify environment and config | | cellar-door version | Print installed version | | cellar-door run "<task>" | Execute a task using retrieval and policy gating | | cellar-door memory add|search|compact|gc | Manage memory cards, retrieval, and compaction | | cellar-door tool list|describe | Inspect built-in tools and schemas | | cellar-door policy check|explain|approve|check-path|check-domain|check-ui|check-model | Inspect and reason about policy decisions | | cellar-door audit tail | View recent audit log entries | | cellar-door plugin add|remove|list|verify|template | Manage plugins and scaffold new ones | | cellar-door team init|join|sync | Configure shared team directory |

How It Works

Runtime flow

User → CLI → Runtime
              ├─→ Memory Retrieval (budgeted)
              ├─→ Policy Check
              ├─→ Tool Calls (schema validated)
              ├─→ Results
              ├─→ Audit + Session Log
              └─→ Compaction (when needed)

Memory model

• Bootstrap (tiny, always loaded)
• Hot (hard-capped summary)
• Warm (retrieved on demand)
• Cold (audit only, never injected)

Tooling model

• Tools are schema-defined and classified by side-effect class.
• Policies allow/deny per tool/path/domain/UI.
• Approvals are time-bounded and audited.

Memory Model (Design)

Storage layout

~/.cellar-door/
├── bootstrap/
├── memory/
│   ├── hot.md
│   ├── cards/
│   └── index.json
├── sessions/
├── audit/
└── config.json

Development

npm install
npm run lint
npm run typecheck
npm run test
npm run build
npm run smoke

Benchmarks

npm run bench:retrieval
npm run bench:tokens

Security Checklist

npm run security:check

Publishing (npm)

This repo is configured for a public npm package with a files whitelist. Publishing runs tests and build automatically:

npm publish

Docs & Community

• CHANGELOG.md
• CONTRIBUTING.md
• docs/recipes/

License

MIT