Codicent Logbook — Standalone MCP logbook runtime

Quick start

Running in 60 seconds.

One command downloads the right binary for your platform from GitHub Releases and puts it on your PATH.

Install script · bash

curl -fsSL https://logbook.codicent.ai/install.sh | bash
logbook-server
# → open http://localhost:5100 — MCP ready at /mcp

Install script · PowerShell

iwr https://logbook.codicent.ai/install.ps1 | iex
logbook-server
# → open http://localhost:5100 — MCP ready at /mcp

Direct download · pick your platform

# Linux x64 (also: linux-arm64, osx-arm64, osx-x64, win-x64.exe)
curl -Lo logbook-server \
  https://github.com/izaxon/codicent-logbook/releases/latest/download/logbook-server-linux-x64
chmod +x logbook-server && ./logbook-server

All binaries: github.com/izaxon/codicent-logbook/releases

Public HTTPS tunnel · Cloudflare Quick Tunnel, no account

export LOGBOOK_PROJECT="myapp"
export LOGBOOK_API_KEY="mysecretkey"
logbook-server --tunnel
# Tunnel:  https://abc123.trycloudflare.com
# MCP:     https://abc123.trycloudflare.com/mcp

Always set LOGBOOK_API_KEY before enabling a tunnel — without it the endpoint is open to the public internet. --relay gives a stable {project}.logbook.codicent.com URL instead.

Features

Everything you need. Nothing to operate.

A personal, AI-accessible logbook with the same message-and-tags data model as the full Codicent platform.

📦

Single executable

Pre-built binaries for Linux, macOS, and Windows. No .NET SDK, no installer — download and run.

🤖

MCP server

Full Model Context Protocol server over stdio or HTTP. Works with Claude Desktop, Cursor, OpenAI Agents SDK, and any MCP client.

📄

OpenAPI schema

Standard OpenAPI 3.0 at /openapi.json — integrate with LangChain, Semantic Kernel, AutoGen, or plain curl.

📂

File inbox

Drop any file into ./inbox/ — indexed automatically, tagged #inbox #file, moved to processed/.

🌐

Public tunnel

--tunnel starts a Cloudflare Quick Tunnel: an instant public HTTPS URL, no account needed. --relay for a stable subdomain.

🔒

API key auth

Set LOGBOOK_API_KEY to protect /mcp and /api/* with Bearer token authentication.

🪝

Webhooks

HMAC-SHA256-signed notifications for message.created and file.uploaded — no Redis required.

🧠

Agentic memory

Tagged messages with JSON payloads give AI agents persistent memory — facts, conventions, and context across sessions.

🗃️

Versioning built in

Updates create child messages; queries return the latest version. Soft delete with #hidden. Same semantics as full Codicent.

Integrations

Point your AI at it.

Any MCP client or OpenAPI-compatible tool connects in one config block.

Claude Desktop · stdio, recommended

// claude_desktop_config.json
{
  "mcpServers": {
    "codicent-logbook": {
      "command": "/path/to/logbook-server",
      "args": ["--stdio"],
      "env": { "LOGBOOK_PROJECT": "myproject" }
    }
  }
}

Remote HTTP · tunnel running

{
  "mcpServers": {
    "codicent-logbook": {
      "url": "https://abc123.trycloudflare.com/mcp",
      "headers": { "Authorization": "Bearer mysecretkey" }
    }
  }
}

Cursor / VS Code · .cursor/mcp.json

{
  "mcpServers": {
    "logbook": {
      "command": "/path/to/logbook-server",
      "args": ["--stdio"],
      "env": { "LOGBOOK_PROJECT": "myproject" }
    }
  }
}

OpenAPI tools · LangChain, Agents SDK, …

tools = load_tools_from_openapi(
  "http://localhost:5100/openapi.json")

# then ask your agent:
#  "Post a message to the logbook: Hello!"
#  "Get data messages tagged 'customer'"
#  "What files are in the logbook?"

MCP tools

Sixteen tools. One data model.

Everything is a message — a string with #tags, @mentions, and optional embedded JSON. Tags are indexed into relational tables for fast querying. Tool names are snake_case on the wire (MCP).

Messages

post_messageget_messagesget_data_messagesget_message_by_idget_message_historyhide_message

Post with #tags and JSON, search full-text, filter data messages by tag, version via parentId, soft-delete with #hidden.

Memory

store_memoryrecall_memoryreflect

First-class agent memory helpers on top of the same tagged-message store.

Files

upload_filedownload_fileget_file_infoget_files

Base64 upload/download with content-addressed SHA-256 storage — or just drop files in ./inbox/.

Webhooks

register_webhookunregister_webhooklist_webhooks

HMAC-SHA256-signed POSTs with X-Logbook-Event, X-Logbook-Event-Id, and X-Logbook-Signature headers.

Agentic memory pattern

Persistent agent memory · tools + tagged JSON

# store / recall (first-class tools)
store_memory(key: "auth", value: "Use JWT for API auth")
recall_memory(query: "authentication")

# or raw tagged messages
post_message("@myproject #memory #fact #auth
  {\"fact\": \"Use JWT tokens for API auth\", \"citations\": \"src/auth.ts:15\"}")
get_data_messages(tags: "memory,auth")

# update (new version) / expire
post_message(message: "...", parentId: "original-id")
hide_message(messageId: "fact-id")

Configuration

Environment variables only.

No config file. Sensible defaults for everything — set variables only for what you change.

Variable	Default	Description
`LOGBOOK_PROJECT`	`default`	Project name; creates a dedicated `{project}/` folder for database and files.
`LOGBOOK_PORT`	`5100`	HTTP server port.
`LOGBOOK_API_KEY`	(none)	Protects `/mcp` and `/api/*` with Bearer auth. Set it before tunneling.
`LOGBOOK_DATABASE`	`{project}/logbook.db`	SQLite database path.
`LOGBOOK_FILES`	`{project}/files/`	Content-addressed file store.
`LOGBOOK_INBOX`	`{project}/inbox/`	Watched folder; files auto-index on arrival.
`LOGBOOK_TUNNEL`	`false`	Start a Cloudflare Quick Tunnel on boot (same as `--tunnel`).
`LOGBOOK_RELAY`	`false`	Connect to the Codicent relay for a stable `{project}.logbook.codicent.com` URL.
`LOGBOOK_RELAY_TOKEN`	(none)	Relay auth token.
`LOGBOOK_WEBHOOK_URL`	(none)	Endpoint for `message.created` / `file.uploaded` events.
`LOGBOOK_WEBHOOK_SECRET`	(none)	HMAC-SHA256 secret for webhook signatures.

REST API

Path	Method	Description
`/`	GET	Web UI
`/health`	GET	Health check
`/mcp`	POST/SSE	MCP server (HTTP Streamable + SSE)
`/openapi.json`	GET	OpenAPI 3.0 schema
`/api/messages`	GET/POST	List or create messages
`/api/files`	GET/POST	List files or upload
`/api/files/{id}`	GET	Download a file

Authenticated endpoints require Authorization: Bearer <key> when LOGBOOK_API_KEY is set.

Scope

Logbook vs full Codicent.

Same data model and semantics — the logbook trades multi-tenancy and cloud services for a zero-dependency local runtime. Outgrow it? Your messages port straight to codicent.com.

	Logbook runtime	Full Codicent
Runs as	Single binary	Docker / cloud
Database	SQLite	SQL Server / PostgreSQL
Files	Local, hash-based	Azure Blob Storage
Projects	Single	Multi-tenant
Auth	API key	Azure AD, Auth0, JWT
Real-time	Webhooks	Redis + SignalR
Dependencies	None	Azure, Redis, SQL