Getting started

This guide gets a local Quilombo instance running and records the first inventory facts.

Run locally

Quilombo requires Python 3.14 and uv.

uv sync
uv run python manage.py migrate
uv run python manage.py runserver

Open http://127.0.0.1:8000/ and create an account. New accounts receive a private Home workspace automatically.

Create a workspace token

From an authenticated browser session, issue a token through:

POST /api/workspaces/{workspace-slug}/tokens/

The raw qlo_... token is displayed once. Store it securely and send it as a bearer token:

curl \
  -H 'Authorization: Bearer qlo_...' \
  https://quilombo.life/api/workspaces/home/

Record inventory

Use POST /api/workspaces/{workspace-slug}/bulk-upsert/ for related changes. Include a unique idempotency_key; the operation is transactional and quantities replace the current recorded values.

{
  "idempotency_key": "workshop-2026-08-15-001",
  "provenance": {
    "source_kind": "agent",
    "source_reference": "Processed from a workshop photo on 2026-08-15"
  },
  "locations": [
    {"key": "drawer-1", "name": "Drawer 1", "kind": "drawer"}
  ],
  "items": [
    {
      "key": "aaa-batteries",
      "name": "AAA batteries",
      "category": "battery",
      "aliases": ["AAA cells", "AAA battery"],
      "attributes": {"size": "AAA"},
      "unit": "lot"
    }
  ],
  "holdings": [
    {
      "item_key": "aaa-batteries",
      "location_key": "drawer-1",
      "quantity": "1",
      "approximate": true
    }
  ]
}

Then search with GET /api/workspaces/{workspace-slug}/search/?q=AAA%20batteries or use the MCP find_inventory tool.