contextbox guide

Open app ◐

contextbox is a multi-tenant, multi-KB search engine for your private notes — wired into Claude Code via a one-tap install. This page walks you through searching, reading, sharing, and installing on a phone.

1. What you can do

• Search private knowledge bases from inside Claude Code (mobile + desktop).
• Share a KB with another heivol user as reader or editor.
• Install the Claude Code skill on your phone in one tap.

2. Sign in

Open contextbox.heivol.com and click Sign in with HeivolID. A signed session cookie is set; everything else (UI, install token mint, guide-suggested curls) flows from that session.

3. Get an API token

You need a token for CLI scripts, the Claude Code skill, or any HTTP automation. From a signed-in session, mint one:

curl -sS -X POST https://contextbox.heivol.com/api/me/tokens \
  -H "content-type: application/json" \
  --cookie "contextbox_session=<your session cookie>" \
  -d '{"scope":["read","write"],"label":"laptop","expires_in_days":365}'

Response: { token: "hvcb_...", info: { id, prefix, label, ... } }. The full token is shown only once — save it to ~/.config/contextbox/token with chmod 600.

Rate-limited at 5 mints/hour per user. Scopes are read (search, list, read) and write (KB + doc CRUD). The Claude Code /install deep link does this for you automatically.

4. Search

Hybrid search — BM25 over chunks blended with cosine similarity over BGE-small embeddings. Only KBs you're a member of are searched.

curl -sS -X POST https://contextbox.heivol.com/api/search \
  -H "Authorization: Bearer $TOKEN" \
  -H "content-type: application/json" \
  -d '{"q":"tokyo itinerary","limit":10,"kb_slug":"travel"}'

Response shape:

{
  "results": [
    {
      "kb_slug": "travel",
      "doc_path": "japan/itinerary.md",
      "chunk_idx": 3,
      "heading": "Day 4 — Kyoto",
      "snippet": "...arrive Kyoto Station via shinkansen...",
      "score": 0.812,
      "citation_url": "https://contextbox.heivol.com/api/kbs/travel/docs/japan/itinerary.md"
    }
  ]
}

Omit kb_slug to search across every KB you can see.

5. Browse and read a doc

# list KBs
curl -sS https://contextbox.heivol.com/api/kbs -H "Authorization: Bearer $TOKEN"

# list docs in a KB (prefix + paging)
curl -sS "https://contextbox.heivol.com/api/kbs/travel/docs?prefix=japan/&limit=50" \
  -H "Authorization: Bearer $TOKEN"

# read full markdown
curl -sS https://contextbox.heivol.com/api/kbs/travel/docs/japan/itinerary.md \
  -H "Authorization: Bearer $TOKEN"

Path segments are URL-encoded individually. The web UI's Browse tab does the same thing visually.

6. Upload a doc

Requires editor or owner role on the KB.

curl -sS -X PUT https://contextbox.heivol.com/api/kbs/travel/docs/japan/itinerary.md \
  -H "Authorization: Bearer $TOKEN" \
  -H "content-type: text/markdown" \
  --data-binary @itinerary.md

Re-PUT the same path to update. Embeddings + chunks are recomputed. To delete: curl -X DELETE on the same URL.

7. Create a KB

The creator is automatically inserted as owner.

curl -sS -X POST https://contextbox.heivol.com/api/kbs \
  -H "Authorization: Bearer $TOKEN" \
  -H "content-type: application/json" \
  -d '{"tenant_slug":"dwayne","slug":"travel","name":"Travel notes"}'

Response includes a clone_url for the bare git repo backing the KB.

8. Share a KB

Two paths. Both go through accept/reject — sharing never adds an arbitrary heivol user without their consent.

Invite a known email

UI: Browse → pick the KB → Share → Invite by email tab. API:

curl -sS -X POST https://contextbox.heivol.com/api/kbs/travel/shares \
  -H "Authorization: Bearer $TOKEN" -H "content-type: application/json" \
  -d '{"recipient_email":"[email protected]","role":"reader"}'

The recipient sees a banner the next time they sign in. They accept via POST /api/invites/:id/accept; accept is idempotent.

Share link

UI: same Share modal → Share link tab. API:

curl -sS -X POST https://contextbox.heivol.com/api/kbs/travel/share-links \
  -H "Authorization: Bearer $TOKEN" -H "content-type: application/json" \
  -d '{"role":"editor","expires_in_hours":72,"max_uses":5}'

Response includes a url like https://contextbox.heivol.com/share/<token>. Anyone who can sign in to HeivolID and visit the URL can join, until the link is revoked, expires, or hits max_uses. Share links can never grant owner.

9. Manage members

Owner-only. Get the list, demote/transfer ownership, or remove.

# list
curl -sS https://contextbox.heivol.com/api/kbs/travel/members \
  -H "Authorization: Bearer $TOKEN"

# transfer ownership (or demote)
curl -sS -X PATCH https://contextbox.heivol.com/api/kbs/travel/members/<user_id> \
  -H "Authorization: Bearer $TOKEN" -H "content-type: application/json" \
  -d '{"role":"owner"}'

# remove
curl -sS -X DELETE https://contextbox.heivol.com/api/kbs/travel/members/<user_id> \
  -H "Authorization: Bearer $TOKEN"

The last owner can never be removed or demoted — there must always be at least one owner.

10. Use it from Claude Code

From /install, sign in and click Download skill. The server mints a fresh user-scoped token and packs everything into a self-contained heivol-contextbox/ folder inside the zip. Extract into your Claude Code skills root:

unzip -o ~/Downloads/heivol-contextbox-skill.zip -d ~/.claude/skills/

Lands SKILL.md, the token, a README, and a .gitignore at ~/.claude/skills/heivol-contextbox/. (Project-scoped instead? Replace the destination with ./.claude/skills/.) The zip carries Unix mode 0600 on the token — the unzip CLI honors it; macOS Archive Utility does not, so if you double-click to extract instead, run chmod 600 ~/.claude/skills/heivol-contextbox/token after. Any new Claude Code session then picks up the skill — no curl, no copy-paste.

11. Use it from git

Each KB is backed by a bare git repo. Clone with a token in the URL:

git clone https://x:<hvcb_token>@contextbox.heivol.com/git/<tenant>/<kb>.git

read scope = clone/fetch. write = push (re-runs ingest server-side).

12. Roles cheat sheet

Role	Read / search	Upload / delete docs	Share + manage members	Delete KB
reader	✓	—	—	—
editor	✓	✓	—	—
owner	✓	✓	✓	✓

13. Errors you might see

• 401 unauthorized — token revoked or session expired. Mint a new one.
• 403 forbidden — your role on this KB is too low for the action.
• 404 not_found — the KB doesn't exist or you're not a member of it. Cross-tenant existence is never leaked.
• 410 gone — share link expired / revoked / exhausted, or invite was revoked or already accepted.
• 429 rate_limited — token mint endpoint enforces 5/hour per user.

14. Quick reference

Every endpoint at a glance

Method	Path	Scope
POST	/api/search	read
GET	/api/kbs	read
POST	/api/kbs	write
DELETE	/api/kbs/:slug	write (owner)
GET	/api/kbs/:slug/docs	read
GET	/api/kbs/:slug/docs/:path	read
PUT	/api/kbs/:slug/docs/:path	write (editor+)
DELETE	/api/kbs/:slug/docs/:path	write (editor+)
GET	/api/kbs/:slug/members	read (owner)
PATCH	/api/kbs/:slug/members/:user_id	write (owner)
DELETE	/api/kbs/:slug/members/:user_id	write (owner)
GET / POST / DELETE	/api/kbs/:slug/shares[/:id]	owner
GET / POST / DELETE	/api/kbs/:slug/share-links[/:id]	owner
GET	/api/me	read
GET	/api/me/invites	read
POST	/api/invites/:id/accept	write
POST	/api/invites/:id/reject	write
GET / POST / DELETE	/api/me/tokens[/:id]	read / write
GET	/install/skill.zip	(session) — bundled skill + token
GET	/share/:token	(public, login-walled)
POST	/share/:token/accept	(session)
GET / clone / push	/git/:tenant/:kb.git	read / write