docs

Getting started

inkcap is one stateful process: web server plus agent runtime. Bring PostgreSQL and an LLM provider; the server keeps runs moving even when every browser disconnects.

Requirements

A PostgreSQL database URL, provided through DATABASE_URL.
An LLM provider: llama-server, an OpenAI-compatible API, or ChatGPT via Codex.
Either Docker or Bun.

Run it

Docker Bun

1. Start PostgreSQL

docker run -d --name inkcap-postgres --restart unless-stopped -p 54329:5432 -v inkcap-postgres:/var/lib/postgresql/data -e POSTGRES_USER=inkcap -e POSTGRES_PASSWORD=inkcap -e POSTGRES_DB=inkcap docker.io/postgres:17

Already have PostgreSQL? Skip this step and set DATABASE_URL to your database below. Otherwise, keep port 54329 private in your firewall.

2. Start inkcap

docker run -d --name inkcap --restart unless-stopped --add-host=host.docker.internal:host-gateway -p 3000:3000 -e DATABASE_URL=postgresql://inkcap:inkcap@host.docker.internal:54329/inkcap -e SESSION_SECRET="$(openssl rand -base64 32)" -e REGISTRATION=open ghcr.io/jakswa/inkcap:latest sh -lc 'bun build/tasks/migrate.js && exec bun build/index.js'

Source checkout for hacking on inkcap or running tests.

git clone https://github.com/jakswa/inkcap
cd inkcap
bun install
cp .env.example .env.local   # set DATABASE_URL and SESSION_SECRET
bun run db:migrate
bun run dev

Open http://localhost:3000, register, add a provider, and start chatting.

Add a provider

Providers live server-side; API keys are stored in PostgreSQL and never reach the browser. Add one under Providers → Add provider. Supported paths include llama-server, OpenAI-compatible APIs, and ChatGPT via Codex.

# source checkout helper; uses DEV_LLAMA_SERVER / DEV_LLAMA_KEY
bun src/tasks/seed-provider.ts --user you@example.com

Chat on your ChatGPT subscription (Codex)

Providers → Add provider → “Sign in with ChatGPT”. inkcap uses Codex device-code auth by default: approve the one-time code in any browser, then tokens stay server-side and refresh automatically.

You may need to enable Allow device code login in ChatGPT settings or workspace policy. The old localhost:1455 PKCE callback remains as an advanced fallback, including paste-to-finish for remote browsers.

Import llama.cpp web UI history

The importer is idempotent and accepts JSONL or zip exports, including attachments and branch trees:

bun src/tasks/import-llama-ui.ts export.jsonl --user you@example.com

Environment reference

Variable	What it does
`DATABASE_URL`	PostgreSQL connection string
`SESSION_SECRET`	Encrypts the session cookie; use a fixed, non-placeholder value at least 32 bytes long outside throwaway dev
`ASSET_VERSION`	Static-asset version; required when building a production image
`PORT`	HTTP port inside the container/process (default 3000)
`REGISTRATION`	`open` or `closed`; defaults to closed in production, open elsewhere
`PUBLIC_ORIGIN`, `CSRF_TRUSTED_ORIGINS`, `OUTBOUND_TRUSTED_HOSTS`	Split-origin and local-network deployment opt-ins; see `.env.example`
`DEV_LLAMA_SERVER` / `DEV_LLAMA_KEY`	Feed the development seed-provider task

Digging deeper

README — architecture, scripts, development rules
docs/STATUS.md — current project state
docs/specs/ — provider, export, and MCP protocol notes