Skip to content
deedglassdocs

Quickstart

Five minutes from an empty directory to a blocked DROP TABLE and an UPDATE that Postgres’s own change log confirms.

Before you start

  • Docker is running, with about 2 GiB of free disk.
  • Node 22.12 or later (for npx), or Go 1.27 to build the CLI yourself.
  • macOS or Linux. On Windows, use WSL 2.

1. Get the CLI

Section titled “1. Get the CLI”

npx fetches the CLI for your platform. It has no install script.

Terminal
$ npx -y deedglass version
deedglass … · api 2026-10-01 · …

Prefer a binary on your PATH? go install github.com/deedglass/deedglass/cmd/deedglass@latest, then use deedglass in place of npx -y deedglass below.

2. Set up a local stack

Section titled “2. Set up a local stack”

In a new, empty directory:

Terminal
$ mkdir acme-agents && cd acme-agents
$ npx -y deedglass init --yes
deedglass init · setting up Deedglass in …
✓ Docker …
✓ Postgres …
✓ Deedglass               http://127.0.0.1:…
✓ Agent                   quickstart-agent · key saved to .deedglass/quickstart.key …
✓ Policies                postgres-safe v1 · enforce …
✓ Smoke · postgres.query  Claimed · Matches · deed_…
✕ Smoke · DROP TABLE      Blocked by policy "block-destructive-sql": DROP and TRUNCATE are never allowed for agents.
✓ Smoke · UPDATE 1 row    Proven · Matches · Postgres committed the row in public.orders · deed_…
✓ Sealed. Your first record is in the ledger.

init starts Postgres 18.6 in Docker, runs deedglass serve on 127.0.0.1:8080, creates an org, an agent with a test key, the Acme demo database behind a Postgres connector, and the postgres-safe policy. Then it sends three actions through Deedglass:

  • a read, which runs: Claimed ·Matches
  • a DROP TABLE, which the policy blocks before Postgres sees it
  • an UPDATE of one row, which waits for a person (in dev, init countersigns as you), runs, and is checked at Proven: Proven ·Matches

With the Postgres image already pulled this takes 6 to 8 seconds on an M-series Mac. Run it again and it prints Nothing to change.

3. Check everything

Section titled “3. Check everything”
Terminal
$ npx -y deedglass doctor
deedglass doctor · 16 checks · …
…
16 ok

Each line is one check. A problem prints its fix; every check is explained in Doctor checks.

4. See the blocked action and the verified one

Section titled “4. See the blocked action and the verified one”

The admin key init saved lets the CLI read the Ledger:

Terminal
$ export DEEDGLASS_API_KEY="$(cat .deedglass/admin.key)"
$ npx -y deedglass actions list --limit 3
…postgres.execute…

The DROP TABLE is sealed as denied: its record names the rule and says that nothing ran. The UPDATE waited for a person, ran once approved, and was checked at Proven: Postgres’s change log shows exactly one row of public.orders changed.

5. Connect your agent

Section titled “5. Connect your agent”

Pick your client. Each page shows the exact config, generated from the CLI’s own snippets.

6. Look in the Console

Section titled “6. Look in the Console”

Open http://127.0.0.1:8080/app and sign in as you@localhost.test. In dev, Deedglass writes mail to its log instead of sending it, so the sign-in link is in .deedglass/serve.log.

What just happened

Section titled “What just happened”
  1. The agent asked Deedglass to run a tool, and Deedglass checked its key.
  2. Your rules (the enforced policy) decided: allow, deny, or require approval.
  3. The denied call was sealed as a record and never reached Postgres.
  4. The allowed call ran through the Postgres connector as the least-privilege role deedglass_agent.
  5. The check compared what the tool reported with Postgres’s change log (Proven).
  6. Each result was sealed into the org’s record chain, which anyone can check offline.

What it doesn’t do

Section titled “What it doesn’t do”
  • The local stack is for a laptop: 127.0.0.1 only, dev mode, throwaway data. Run in production on one VM is the next step.
  • init doesn’t edit your MCP client’s config file. It prints what to paste.
  • It doesn’t use an existing database yet. Put Deedglass in front of Postgres covers your own database.
  • deedglass init --stop stops the stack. It keeps .deedglass/ and the Docker volumes, so a later init picks up where you left off.

Next

Section titled “Next”