Self-hosted quickstart

This guide is for teams running Coconut on their own infrastructure. If you’re using the hosted app at app.coconut.md, see the Quickstart instead. It takes you from a clean checkout to a running Coconut stack in under fifteen minutes, covering a page, its metadata, a cross-page query, and a webhook.

Run the stack

pnpm install
./scripts/compose-local.sh up     # Postgres + API (8787) + app (3000), migrated + seeded

Open http://localhost:3000. The seeded identity is demo@local in the demo space.

Create a page (as an agent)

curl -X PUT "http://localhost:8787/pages/demo/customer-acme" \
  -H "Authorization: Bearer dev-agent-key-change-me" \
  -H "Content-Type: application/json" \
  -d '{"title":"Acme Corp","content":"# Acme\n\nResearch notes...","frontmatter":{}}'

Attach structured metadata

curl -X PATCH "http://localhost:8787/pages/demo/customer-acme/metadata" \
  -H "Authorization: Bearer dev-agent-key-change-me" \
  -H "Content-Type: application/json" \
  -d '{"set":{"stage":"diligence","conviction-score":0.8},
       "appendUnique":{"sources":["https://news.example/acme"]}}'

Query across pages

curl -G "http://localhost:8787/search/metadata" \
  -H "Authorization: Bearer dev-agent-key-change-me" \
  --data-urlencode 'filters=[{"key":"stage","op":"eq","value":"diligence"},{"key":"conviction-score","op":"gte","value":0.7}]' \
  --data-urlencode 'orderBy=conviction-score' --data-urlencode 'order=desc'

Humans run the same query in the browser at Views (/views): filters, ordering, and a results table, shareable as a URL.

Get notified

Create a webhook in Admin → Manage webhooks (or POST /admin/webhooks), and every page or metadata change POSTs a signed JSON payload to your endpoint.

Getting Started

Tools

Concepts

API Reference

Operations

Self-hosted quickstart

Run the stack

Next steps

Learn the model

Prompt gallery

​Run the stack

​Next steps

Learn the model

Prompt gallery

Run the stack

Next steps