Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

docs: simplify the self-hosting setup (#3676)

robert-inkeepfcea92ac80a1
diff --git a/docs/content/reference/cli.mdx b/docs/content/reference/cli.mdx
index 8937ee0cb..d9bdfbb7b 100644
--- a/docs/content/reference/cli.mdx
+++ b/docs/content/reference/cli.mdx
@@ -119,7 +119,7 @@ Each project runs its own local server. These commands let you see and stop them
## Remote control
-Serve this project's web UI and `/mcp` endpoint to your other devices through any HTTPS tunnel, both on one URL. Full setup (and the access-control model) in the [self-hosting overview](/docs/self-hosting/overview); point agents at the URL with [Connecting agents](/docs/self-hosting/connecting-agents).
+Serve this project's web UI and `/mcp` endpoint to your other devices through any HTTPS tunnel, both on one URL. See the [self-hosting overview](/docs/self-hosting/overview) for the full setup and access-control model. Use [Connect remote agents](/docs/self-hosting/connecting-agents) to point agents at the URL.
| Command | What it does |
| --- | --- |
diff --git a/docs/content/reference/mcp.mdx b/docs/content/reference/mcp.mdx
index 522701450..f258c6450 100644
--- a/docs/content/reference/mcp.mdx
+++ b/docs/content/reference/mcp.mdx
@@ -10,7 +10,7 @@ Every other read tool (`search`, `links`, `history`, etc.) and all write tools r
The surface is **21 tools**. The four write verbs — `write`, `edit`, `delete`, `move` — are native CRUD operations polymorphic over a target. `write`, `edit`, and `delete` nest per-target fields inside the address key (`write({ document: { path, content } })`) and take exactly one target per call: `document`, `folder`, `template`, or `skill` — plus `asset` for `write` and `delete`, and a `documents` batch on `write` that writes several docs in order, each entry carrying its own `summary`. `move` takes flat `from`/`to` paths and auto-detects a document, folder, or asset, with nested `template` and `skill` targets for those two.
-To point an MCP client at this server, locally or over a tunnel from another machine, see [Connecting agents](/docs/self-hosting/connecting-agents).
+To point an MCP client at this server, locally or over a tunnel from another machine, see [Connect remote agents](/docs/self-hosting/connecting-agents).
## Tools
diff --git a/docs/content/self-hosting/authentication.mdx b/docs/content/self-hosting/authentication.mdx
index 0ebc6e3be..b15fda105 100644
--- a/docs/content/self-hosting/authentication.mdx
+++ b/docs/content/self-hosting/authentication.mdx
@@ -5,26 +5,28 @@ description: Control who can reach your knowledge base.
---
## How access works
-To control access, you put a gate in front of the server, and that gate has to cover two kinds of clients that sign in differently:
+Add access control in front of the server. The browser and MCP clients use different authentication methods:
-- **People** use the editor in a browser. They sign in with an ordinary login (Google or your SSO), and the browser then sends a session cookie on every request, including the live-editing connection.
-- **AI agents** connect to `/mcp` with no browser, so an agent presents a token instead. Usually that is a preset token you generate. Some MCP-aware proxies can instead give the agent its own OAuth popup (via [dynamic client registration](https://datatracker.ietf.org/doc/html/rfc7591) or [client ID metadata documents](https://datatracker.ietf.org/doc/draft-ietf-oauth-client-id-metadata-document/)), so it signs in and receives its token automatically instead of using a preset one; see [MCP-native edges](#mcp-native-edges).
+- **Browser users** sign in with Google or your SSO. The browser sends a session cookie with editor and live collaboration requests.
+- **AI agents** connect to `/mcp` without a browser. Use a token or an MCP-aware OAuth proxy. OAuth proxies can authenticate agents through [dynamic client registration](https://datatracker.ietf.org/doc/html/rfc7591) or [client ID metadata documents](https://datatracker.ietf.org/doc/draft-ietf-oauth-client-id-metadata-document/). See [MCP-native edges](#mcp-native-edges).
-A login fits people but not agents, and a token fits agents but not the editor, so a complete setup provides **both**: a login on the editor and a token on `/mcp`. That pairing is the split, and it shapes every recipe below.
+For a public deployment, protect the editor with a browser login. Protect `/mcp` with a token or MCP-compatible OAuth.
-You add the gate in one of two places: on the tunnel or network that reaches the server, or in a proxy in front of it. A tunnel or private network is quickest when you run the server yourself ([npm method](/docs/self-hosting/methods/npm)); a proxy suits a container on a hosting platform ([Docker method](/docs/self-hosting/methods/docker)). The two mix, so a container can sit behind a tunnel and let the tunnel gate it.
+Add access control to the tunnel, private network, or proxy in front of the server. Use a tunnel or private network with the [CLI method](/docs/self-hosting/methods/cli). Use a proxy with the [Docker method](/docs/self-hosting/methods/docker). A container can also run behind a protected tunnel.
## Tunnels and private networks
-If you reach the server through a tunnel or private network, that same layer is the natural place to gate access.
+A tunnel or private network can restrict access before requests reach the server.
### Tailscale
-The simplest option: it sidesteps [the split](#how-access-works). `tailscale serve` admits only devices on your tailnet, so the network itself is the authentication: one gate covering the editor and agents alike, with no login pages and no tokens to mint. Narrow it further with [tailnet ACLs](https://tailscale.com/kb/1018/acls). But `serve` is tailnet-only: it can't reach mobile or cloud agents (Claude iOS, Cursor cloud), which dial from the provider's cloud, not your tailnet. For those, make it public with `tailscale funnel` plus a gate, see [Example: Pomerium](#example-pomerium). If everyone who needs access can join your tailnet, `serve` is usually the right answer.
+`tailscale serve` limits access to devices on your tailnet. It protects both the editor and `/mcp` without a separate login or token. Use [tailnet ACLs](https://tailscale.com/kb/1018/acls) to restrict access further.
+
+`tailscale serve` cannot reach mobile or cloud agents such as Claude on iOS or Cursor cloud because they connect from the provider's network. To support those clients, use `tailscale funnel` with access control such as [Pomerium](#example-pomerium).
### ngrok
-It puts a login at its edge, and expresses the split in a single path-branched policy: an OAuth login for the browser, a Basic credential for agents.
+ngrok can apply separate access rules by path. Use OAuth for the editor and Basic authentication for `/mcp`.
```yaml title="policy.yaml"
on_http_request:
@@ -38,26 +40,26 @@ on_http_request:
config: { provider: google }
```
-Run the tunnel with `--traffic-policy-file policy.yaml`. Browsers get the Google login; an agent connects headlessly by sending the Basic credential as a header (see [Connecting agents](/docs/self-hosting/connecting-agents)). Replace `CHANGE_ME` with a strong secret (`openssl rand -hex 24`). For SSO instead of consumer OAuth, ngrok's `--oidc` covers Okta, Azure AD, and Google Workspace.
+Run the tunnel with `--traffic-policy-file policy.yaml`. Browsers get the Google login. An agent connects by sending the Basic credential as a header. See [Connect remote agents](/docs/self-hosting/connecting-agents). Replace `CHANGE_ME` with a strong secret from `openssl rand -hex 24`. For SSO, ngrok's `--oidc` supports Okta, Azure AD, and Google Workspace.
### Cloudflare Tunnel
-It pairs with [Cloudflare Access](https://developers.cloudflare.com/cloudflare-one/policies/access/): a login policy on the hostname for the browser, and [service tokens](https://developers.cloudflare.com/cloudflare-one/identity/service-tokens/) for agents (standing credentials, with no hourly expiry). Its [Managed OAuth](https://developers.cloudflare.com/cloudflare-one/access-controls/applications/http-apps/managed-oauth/) can go one step further and serve MCP's own OAuth popup to agents (see [MCP-native edges](#mcp-native-edges)); it requires your domain on Cloudflare.
+Pair it with [Cloudflare Access](https://developers.cloudflare.com/cloudflare-one/policies/access/). Use a login policy on the hostname for browsers and [service tokens](https://developers.cloudflare.com/cloudflare-one/identity/service-tokens/) for agents. Service tokens do not expire every hour. [Managed OAuth](https://developers.cloudflare.com/cloudflare-one/access-controls/applications/http-apps/managed-oauth/) can also provide an OAuth popup for agents. See [MCP-native edges](#mcp-native-edges). Managed OAuth requires your domain to use Cloudflare.
## In front of a container
-A container on a hosting platform gets a public domain with no login of its own, so the gate is a proxy you add. Browsers always get a login; the choice is how agents authenticate:
+Hosting platforms provide a public domain without access control. Add an authentication proxy in front of the container. Use one of these methods for agents:
-- A **static bearer token** you generate once and every agent sends as a header. Simplest to run, and the recipe below works this way; the trade-off is one secret shared by everyone.
+- A **static bearer token** sent by every agent as a header. The recipe below uses one shared token.
- An **MCP OAuth popup**, where the agent logs in with nothing to copy, and the only path that reaches mobile and cloud connectors (Claude iOS, Cursor cloud). The [Pomerium recipe](#example-pomerium) below sets it up.
### Example: Caddy + oauth2-proxy
-Two small proxy services sit in front of the server, and the routing is what makes the [split](#how-access-works) clean. **Caddy** is the public ingress: it sends `/mcp` straight to the server behind a shared bearer token, and everything else through **[oauth2-proxy](https://oauth2-proxy.github.io/oauth2-proxy/)**, which runs the Google login for the browser. Agents never touch the login; browsers never see the token; and because `/mcp` bypasses oauth2-proxy, its streaming stays clear of the login proxy entirely. Three services, none needing a database.
+Two small proxy services sit in front of the server. **Caddy** receives public traffic. It sends `/mcp` directly to the server behind a shared bearer token. It sends everything else through **[oauth2-proxy](https://oauth2-proxy.github.io/oauth2-proxy/)**, which handles Google login for the browser. Agents do not use the browser login. Browsers do not see the agent token. Because `/mcp` bypasses oauth2-proxy, its streaming response is not interrupted by the login proxy. None of the three services needs a database.
The hostnames below are Railway's private network (`*.railway.internal`, IPv6-only). On another Docker host, swap them for your compose service names.
-**Caddy** is the public ingress. Bake the config into a small image, since managed platforms can't mount a file:
+**Caddy** receives public traffic. Include its configuration in the image because managed platforms may not support mounting a file:
```dockerfile title="Dockerfile (caddy)"
FROM caddy:2
@@ -66,7 +68,7 @@ COPY Caddyfile /etc/caddy/Caddyfile
```text title="Caddyfile"
:{$PORT} {
- # Agents: a shared bearer token, straight to the server.
+ # Agents use a shared bearer token.
@mcp path /mcp /mcp/*
handle @mcp {
route {
@@ -88,7 +90,7 @@ COPY Caddyfile /etc/caddy/Caddyfile
}
```
-Set `MCP_TOKEN` on the Caddy service to a value from `openssl rand -hex 24`; that string is what agents send.
+Set `MCP_TOKEN` on the Caddy service to a value from `openssl rand -hex 24`. Agents send this value when they connect.
**oauth2-proxy** runs the browser login. Use the `quay.io/oauth2-proxy/oauth2-proxy:v7` image with your own Google OAuth client (a **Web application** client whose redirect URI is `https://<your-domain>/oauth2/callback`):
@@ -124,21 +126,23 @@ An agent then connects with the token and no browser step:
Four settings decide whether this boots the first time:
- **`OAUTH2_PROXY_WHITELIST_DOMAINS` must list your public domain.** Behind Caddy, oauth2-proxy builds its post-login redirect from the forwarded host and refuses any host not on this list, so without it the login silently loops back to itself.
-- **`OAUTH2_PROXY_COOKIE_SECRET` must decode to 16, 24, or 32 bytes.** `openssl rand -hex 16` gives a valid 32-character value; `openssl rand -base64 32` gives 44 characters, and oauth2-proxy refuses to start.
-- **Caddy must send `X-Forwarded-Proto: https`** (the two `header_up` lines above). TLS terminates at the platform edge, so Caddy speaks plain HTTP inward and would otherwise report the request as `http`, so the server hands the editor a `ws://` socket, which the browser blocks as mixed content on an `https` page and the editor hangs. oauth2-proxy relays that header to its upstream on its own; `OAUTH2_PROXY_REVERSE_PROXY=true` is what makes it trust the forwarded headers for its own client-IP and post-login redirect logic, which the `WHITELIST_DOMAINS` note above depends on. `FLUSH_INTERVAL=100ms` is the [never-buffer rule](/docs/self-hosting/methods/docker#rules-for-anything-in-front-of-the-server) for the same path.
+- **`OAUTH2_PROXY_COOKIE_SECRET` must decode to 16, 24, or 32 bytes.** Use `openssl rand -hex 16` to create a valid 32-character value. Do not use `openssl rand -base64 32` because it creates 44 characters and oauth2-proxy will not start.
+- **Caddy must send `X-Forwarded-Proto: https`** using the two `header_up` lines above. TLS ends at the platform edge, so Caddy uses plain HTTP between the edge and the server. Without this header, the server gives the editor a `ws://` connection. The browser blocks it as mixed content on an `https` page and the editor does not load. oauth2-proxy forwards the header automatically. Set `OAUTH2_PROXY_REVERSE_PROXY=true` so oauth2-proxy trusts forwarded headers for client IP addresses and post-login redirects. Set `FLUSH_INTERVAL=100ms` to follow the [never-buffer rule](/docs/self-hosting/methods/docker#rules-for-anything-in-front-of-the-server).
- **Bind to IPv6 where the platform's private network requires it.** Railway's is IPv6-only, so `OK_BIND=::` and `HTTP_ADDRESS=[::]:4180`, and Caddy dials the `*.railway.internal` names.
### Example: Pomerium
-Use this when you need OpenKnowledge from mobile or cloud agents (Claude iOS, Cursor cloud) with a per-user login: a public endpoint where each agent gets its own OAuth token, no shared secret and no tailnet membership. It is two layers, not one. Any public recipe (ngrok, Cloudflare, the Caddy one above) gives you the **public endpoint**; [Pomerium](https://www.pomerium.com/) adds **per-user OAuth** at the gate, serving MCP's own OAuth on `/mcp` and a cookie login for the editor from one config.
+Use this setup when mobile or cloud agents need their own login. Examples include Claude on iOS and Cursor cloud. Each agent gets its own OAuth token, so there is no shared secret or tailnet membership.
+
+This setup has two layers. A public access method such as ngrok, Cloudflare, or the Caddy example above provides the **public endpoint**. [Pomerium](https://www.pomerium.com/) adds **per-user OAuth**. It provides OAuth for `/mcp` and a cookie login for the editor from one configuration.
-The reason those clients specifically need this: Claude iOS and Cursor's cloud agents dial your server from the provider's cloud, not from the device, so the endpoint has to be genuinely public. A phone has no `mcp-remote` fallback and isn't on your tailnet, so `tailscale serve` can't reach it; `tailscale funnel` (public) plus Pomerium can.
+Claude on iOS and Cursor's cloud agents connect from the provider's cloud, not from your device. The endpoint must be publicly reachable. A phone cannot use the `mcp-remote` fallback and is not on your tailnet. `tailscale serve` cannot reach it. You can use the public `tailscale funnel` with Pomerium instead.
```text
Internet (Claude / Cursor cloud dial in from here)
| https://<host>/ (editor) + https://<host>/mcp (agents)
v Tailscale funnel: public TLS on your *.ts.net name
- v Pomerium: per-user Google login; MCP OAuth on /mcp, cookie login on the editor
+ v Pomerium: MCP OAuth on /mcp, cookie session for the browser editor
v OpenKnowledge: loopback, told its public externalUrl
```
@@ -154,7 +158,7 @@ The "external access enabled, no server-side auth" banner is expected here: Pome
**Pomerium** runs as a container with a persistent databroker, so sessions and tokens survive a restart. It needs your own Google OAuth client (a **Web application** client whose redirect URI is `https://<host>:8443/oauth2/callback`), plus two secrets and a signing key you generate locally:
```bash
-# Run this to write .env (the $(...) execute now; they are not literal values).
+# Run this to write .env. The $(...) expressions execute now.
cat > .env <<EOF
SHARED_SECRET=$(openssl rand -base64 32)
COOKIE_SECRET=$(openssl rand -base64 32)
@@ -176,7 +180,7 @@ autocert: false
databroker_storage_type: file
databroker_storage_connection_string: file:///data/databroker
-# Claude authenticates with client ID metadata documents (CIMD); Cursor with
+# Claude uses client ID metadata documents (CIMD). Cursor uses
# dynamic client registration (DCR). Enable both.
runtime_flags:
mcp_dynamic_client_registration: true
@@ -226,7 +230,9 @@ volumes:
pomerium-data:
```
-Bring it up with `docker compose up -d`. Two portability notes: the `pomerium/pomerium:main` tag is required for now, since Pomerium's MCP support is recent and not yet in a stable release. And on Linux without Docker Desktop, `host.docker.internal` may not reach a loopback-bound server (`host-gateway` resolves to the Docker bridge IP, not `127.0.0.1`); run Pomerium with `--network host`, or bind the server to the bridge gateway and restrict it with a firewall rule.
+Start it with `docker compose up -d`. The `pomerium/pomerium:main` tag is required because Pomerium's MCP support is not yet in a stable release.
+
+On Linux without Docker Desktop, `host.docker.internal` may not reach a server bound to loopback. `host-gateway` resolves to the Docker bridge IP instead of `127.0.0.1`. Run Pomerium with `--network host`, or bind the server to the bridge gateway and restrict it with a firewall rule.
**Tailscale funnel** makes it public on your `*.ts.net` name (MagicDNS, HTTPS, and Funnel must be enabled for the node):
@@ -235,30 +241,30 @@ tailscale funnel --bg --https=443 https+insecure://127.0.0.1:8085
tailscale funnel --bg --https=8443 https+insecure://127.0.0.1:8085
```
-Then point a custom MCP connector in Claude (iOS or Desktop) or Cursor at `https://<host>/mcp` and complete the Google login. [Connecting agents](/docs/self-hosting/connecting-agents) has the per-client steps.
+Then point a custom MCP connector in Claude (iOS or Desktop) or Cursor at `https://<host>/mcp` and complete the Google login. [Connect remote agents](/docs/self-hosting/connecting-agents) has the per-client steps.
The settings that are easy to miss:
- **Two routes, not one.** A single `mcp: server` route answers the browser with "This is an MCP route." Split `/mcp` (agents) from the catch-all (editor).
- **`allow_websockets: true`** on the editor route, or the editor loads but never syncs (the `/collab` socket is blocked).
-- **`preserve_host_header: true`** so the public host reaches the server as its `externalUrl`; without it every request is a `403`.
-- **Both DCR and CIMD.** `mcp_dynamic_client_registration: true` covers Cursor; `mcp_allowed_client_id_domains` covers Claude, whose `client_id` is a URL that Pomerium fetches and checks against that list.
+- **Set `preserve_host_header: true`.** This sends the public host to the server as its `externalUrl`. Without it, every request returns `403`.
+- **Enable both DCR and CIMD.** `mcp_dynamic_client_registration: true` supports Cursor. `mcp_allowed_client_id_domains` supports Claude. Pomerium fetches Claude's `client_id` URL and checks it against this list.
- **A persistent databroker** (above), or a restart drops every token.
### MCP-native edges
Alternatives to the Pomerium recipe above, as pointers rather than full recipes:
- **[obot mcp-oauth-proxy](https://github.com/obot-platform/mcp-oauth-proxy)**: an MCP-aware OAuth proxy that implements dynamic client registration, the flavor today's clients (Cursor among them) speak.
-- **[Cloudflare Managed OAuth](https://developers.cloudflare.com/cloudflare-one/access-controls/applications/http-apps/managed-oauth/)**: serves the MCP OAuth popup at Cloudflare's edge, alongside the [Access](#tunnels-and-private-networks) login for the UI; it requires your domain on Cloudflare.
+- **[Cloudflare Managed OAuth](https://developers.cloudflare.com/cloudflare-one/access-controls/applications/http-apps/managed-oauth/)** provides the MCP OAuth popup at Cloudflare's edge. It works with the [Access](#tunnels-and-private-networks) login for the UI and requires your domain to use Cloudflare.
## Troubleshooting
Common symptoms and their fixes:
- **The editor loads but never syncs, and the browser console shows a `ws://` "Mixed Content" error.** The proxy terminates TLS but reports the request to the server as plain HTTP, so the server hands the editor an insecure `ws://` socket. Make the proxy forward `X-Forwarded-Proto: https` (Caddy: `header_up X-Forwarded-Proto https`).
-- **Every request returns `403`.** The `Host` reaching the server doesn't match `OK_EXTERNAL_URL`, usually because the proxy rewrote `Host` to the upstream address. Preserve the client's `Host` (Caddy: `header_up Host {host}`) and point `OK_EXTERNAL_URL` at the public origin. Full [proxy rules](/docs/self-hosting/methods/docker#rules-for-anything-in-front-of-the-server).
-- **The browser login loops back to the login page.** oauth2-proxy is rejecting its own post-login redirect because the domain isn't allowed. Add your public domain to `OAUTH2_PROXY_WHITELIST_DOMAINS`.
-- **An agent gets an HTML login page back from `/mcp`.** The `/mcp` path is behind the browser login instead of a token. Route `/mcp` around the login proxy and gate it with a token, or if you use an MCP-OAuth edge, confirm the client supports it (see [Connecting agents](/docs/self-hosting/connecting-agents)).
-- **`/mcp` hangs or times out.** A proxy in front is buffering the streamed response. Turn buffering off on `/mcp` (nginx `proxy_buffering off;`, oauth2-proxy `FLUSH_INTERVAL=100ms`; Caddy streams by default).
+- **Every request returns `403`.** The request `Host` does not match `OK_EXTERNAL_URL`. Configure the proxy to preserve the client's `Host`. For Caddy, use `header_up Host {host}`. Set `OK_EXTERNAL_URL` to the public origin. See the full [proxy rules](/docs/self-hosting/methods/docker#rules-for-anything-in-front-of-the-server).
+- **The browser login returns to the login page.** oauth2-proxy is rejecting the post-login redirect because the domain is not allowed. Add the public domain to `OAUTH2_PROXY_WHITELIST_DOMAINS`.
+- **An agent gets an HTML login page back from `/mcp`.** The `/mcp` path is behind the browser login instead of a token. Route `/mcp` around the login proxy and gate it with a token, or if you use an MCP-OAuth edge, confirm the client supports it (see [Connect remote agents](/docs/self-hosting/connecting-agents)).
+- **`/mcp` hangs or times out.** A proxy is buffering the streamed response. Turn off buffering for `/mcp`. In nginx, set `proxy_buffering` to `off`. For oauth2-proxy, set `FLUSH_INTERVAL=100ms`. Caddy streams by default.
-Once auth is in place, [Connecting agents](/docs/self-hosting/connecting-agents) covers how each client presents its credential.
+Once auth is in place, [Connect remote agents](/docs/self-hosting/connecting-agents) covers how each client presents its credential.
diff --git a/docs/content/self-hosting/connecting-agents.mdx b/docs/content/self-hosting/connecting-agents.mdx
index b50aec219..e10c9c3b3 100644
--- a/docs/content/self-hosting/connecting-agents.mdx
+++ b/docs/content/self-hosting/connecting-agents.mdx
@@ -1,15 +1,23 @@
---
-title: Connecting agents
+title: Connect remote agents
icon: LuPlug
-description: Point your agents (Claude Code, Cursor, Claude Desktop, and more) at one shared knowledge base.
+description: Connect agents running on another machine or in the cloud to your OpenKnowledge project.
---
-Prerequisite: a running server with [remote control](/docs/self-hosting/overview) set up. OpenKnowledge doesn't authenticate callers itself; the edge in front of it (a tunnel or proxy) decides who can reach the URL (see [Authentication](/docs/self-hosting/authentication)). To add someone else's machine, first get them through that edge (a tailnet invite, an allowlist entry, or the shared token), then send them here.
+Connect agents on another computer or in a cloud service to the OpenKnowledge project on your server. They connect through the project's remote MCP endpoint and do not need a local copy of the knowledge base.
-Every client below points at the same address, `https://<your-external-url>/mcp`, whether the server runs on your laptop, a VPS, or a container.
+<Callout type="info">
+If the agent runs on the same machine as your OpenKnowledge project, follow the [Quickstart](/docs/get-started/quickstart). `ok init` registers supported local agents for you. This page is for agents connecting over the network.
+</Callout>
-## Connect every agent in one command
+## Before you start
-[`add-mcp`](https://github.com/neon-solutions/add-mcp), a community tool, detects which agents are installed on the machine and writes each one's MCP config for you (Claude Code, Cursor, Codex, VS Code, Windsurf, Goose, Zed, and more):
+Set up a running server with [remote control](/docs/self-hosting/overview). Every remote agent connects to the same address, `https://<your-external-url>/mcp`, whether the server runs on your laptop, a VPS, or in a container.
+
+OpenKnowledge does not authenticate callers. The tunnel, private network, or proxy in front of the server controls access. Configure it first. Then give the agent any required network access or credentials. See [Authentication](/docs/self-hosting/authentication).
+
+## Connect agents on another machine
+
+Run this on the machine where the agents are installed. [`add-mcp`](https://github.com/neon-solutions/add-mcp), a community tool, detects supported agents and writes each one's MCP config for you (Claude Code, Cursor, Codex, VS Code, Windsurf, Goose, Zed, and more):
```bash
npx add-mcp https://<your-external-url>/mcp --name ok-remote
@@ -24,9 +32,9 @@ npx add-mcp https://<your-external-url>/mcp --name ok-remote \
For Basic Auth, the header is `Authorization: Basic $(printf 'user:pass' | base64)` instead.
-A plain **OAuth/SSO** login can't be used this way: a headless agent can't complete a browser sign-in. Gate `/mcp` with a token, a [path-branched policy](/docs/self-hosting/authentication#tunnels-and-private-networks), or Tailscale instead.
+A headless agent cannot complete a standard browser login. Protect `/mcp` with a token, a [path-specific access policy](/docs/self-hosting/authentication#tunnels-and-private-networks), or Tailscale.
-The exception is an [MCP-native edge](/docs/self-hosting/authentication#mcp-native-edges) (such as Pomerium), which lets the agent sign in through its own browser popup with no token to set. Pomerium serves CIMD by default (which Claude uses) and DCR when you enable `mcp_dynamic_client_registration` (which Cursor and `mcp-remote` use), so both work; the [Pomerium recipe](/docs/self-hosting/authentication#example-pomerium) turns both on.
+The exception is an [MCP-native edge](/docs/self-hosting/authentication#mcp-native-edges), such as Pomerium. It lets the agent sign in through its own browser popup with no token to set. Pomerium serves CIMD by default for Claude. Enable `mcp_dynamic_client_registration` to add DCR support for Cursor and `mcp-remote`. The [Pomerium recipe](/docs/self-hosting/authentication#example-pomerium) turns both on.
The per-client setups below use a plain `/mcp` URL. If yours is behind a token, add the same `Authorization` header shown above (details in [Authentication](/docs/self-hosting/authentication)).
@@ -78,8 +86,10 @@ If your `/mcp` is behind a token, add it to the `args` array: `"--header", "Auth
Add the `/mcp` URL to your harness's MCP server config, the same way as above. Its agents can then read and write your knowledge base.
-## Cloud connectors (Claude.ai, ChatGPT, etc.)
+## Cloud-hosted agents and connectors (Claude.ai, ChatGPT, etc.)
+
+Cloud-hosted agents and connectors reach the MCP endpoint from the provider's cloud. The URL must be publicly reachable over HTTPS. The Claude and ChatGPT connectors require an MCP-aware OAuth service in front of `/mcp`. The [Pomerium recipe](/docs/self-hosting/authentication#example-pomerium) has been verified with the Claude connector on iOS and Desktop and with Cursor's cloud agents. Support varies by provider.
-Cloud-dialed clients connect from the vendor's cloud, so your URL must be publicly reachable over HTTPS. The Claude and ChatGPT connectors require OAuth, which OpenKnowledge does not serve itself; an MCP-aware OAuth edge in front of `/mcp` supplies it. The [Pomerium recipe](/docs/self-hosting/authentication#example-pomerium) is the path we've verified for the Claude connector (iOS and Desktop) and Cursor's cloud agents, though connector support otherwise varies by vendor. Connectors that accept a bearer token or API key instead (Microsoft Copilot Studio, Perplexity, etc.) can use a token you enforce at the edge: gate `/mcp` with a static bearer token (an ngrok traffic policy, a Cloudflare Access service token, or your auth proxy), then paste that same token into the connector's settings, the way an on-device agent presents its credential as a header.
+Connectors that accept a bearer token or API key can use a token enforced at the edge. This includes Microsoft Copilot Studio and Perplexity. Protect `/mcp` with a static bearer token, then add that token to the connector's settings.
-Claude Desktop is not a cloud connector; it uses the `mcp-remote` bridge covered above.
+Claude Desktop is not a cloud connector. It uses the `mcp-remote` bridge covered above.
diff --git a/docs/content/self-hosting/methods/npm.mdx b/docs/content/self-hosting/methods/cli.mdx
similarity index 59%
rename from docs/content/self-hosting/methods/npm.mdx
rename to docs/content/self-hosting/methods/cli.mdx
index 9fd028b99..2416fffdf 100644
--- a/docs/content/self-hosting/methods/npm.mdx
+++ b/docs/content/self-hosting/methods/cli.mdx
@@ -1,7 +1,7 @@
---
-title: npm
-icon: custom/Npm
-description: Run OpenKnowledge on your own machine, reached through a tunnel or reverse proxy.
+title: CLI
+icon: LuTerminal
+description: Run OpenKnowledge with the CLI on your computer, a VM, or a server.
---
Install OpenKnowledge from npm, then run the server yourself:
@@ -9,11 +9,11 @@ Install OpenKnowledge from npm, then run the server yourself:
npm install -g @inkeep/open-knowledge
```
-Run it on your laptop for the quickest start, or on a server to keep it always available. A tunnel or reverse proxy gives the server its public URL. New to these settings? Read [How exposure works](/docs/self-hosting/overview#how-exposure-works) first.
+Run OpenKnowledge on a laptop or an always-on server. Use a private network, tunnel, or reverse proxy to make it reachable. See the [self-hosting overview](/docs/self-hosting/overview) to choose an access method.
## Your laptop, behind a tunnel
-The quickest path: OpenKnowledge already runs your project, and a tunnel gives it a public HTTPS URL. The catch is that it's only reachable while the machine is awake. Close the lid and your agents lose access. To keep it always available, use [a server you manage](#a-server-you-manage) or the [Docker method](/docs/self-hosting/methods/docker).
+A tunnel gives the OpenKnowledge server on your laptop an HTTPS URL. The server is available only while the laptop is awake. For continuous access, use [an always-on server](#a-server-you-manage) or the [Docker method](/docs/self-hosting/methods/docker).
### 1. Pin a port and open a tunnel
@@ -27,7 +27,11 @@ server:
Any HTTPS tunnel works. It forwards a public URL to that local port. Pick one:
<Callout type="info">
-Install your tunnel's client on the machine first if it isn't already.
+Install the tunnel client on the machine before continuing.
+</Callout>
+
+<Callout type="warn">
+Tailscale Serve stays inside your tailnet. Before starting ngrok or Cloudflare Tunnel, [set up authentication](/docs/self-hosting/authentication) at that edge. Do not open an unprotected public URL.
</Callout>
<Tabs groupId="ok-tunnel" persist items={['Tailscale', 'ngrok', 'Cloudflare Tunnel']}>
@@ -47,7 +51,7 @@ If `serve` says Tailscale is stopped, run `tailscale up` first (on a Linux serve
<Tab>
-Public URL; add edge auth to restrict (see [Authentication](/docs/self-hosting/authentication)).
+Public URL. Add access control at the edge. See [Authentication](/docs/self-hosting/authentication).
```bash
ngrok http 8080
@@ -68,7 +72,7 @@ cloudflared tunnel --url http://localhost:8080
</Tabs>
-Each one gives you a public HTTPS URL. That URL is your `server.externalUrl`.
+Each one gives you an HTTPS URL that clients can reach. Tailscale keeps it private. ngrok and Cloudflare need access control at the edge. That URL is your `server.externalUrl`.
### 2. Configure and start
@@ -81,7 +85,7 @@ server:
```
<Callout type="warn">
-**`server.externalUrl` must be the exact address people will use**: the full tunnel URL, with `https://` and no trailing path. If it doesn't match what the tunnel forwards, the server turns those requests away with a `403` error.
+**`server.externalUrl` must match the public address.** Use the full tunnel URL with `https://` and no trailing path. A mismatch returns `403`.
</Callout>
Then consent on this machine, in the gitignored per-machine config:
@@ -106,17 +110,17 @@ The server prints a warning banner naming the public origin on every exposed sta
OK_ALLOW_EXTERNAL=1 OK_IDLE_SHUTDOWN=off ok start --external-url https://<your-tunnel-url> --port 8080
```
-Now [try it out](/docs/self-hosting/overview#try-it-out).
+If the URL is public, [add access control](/docs/self-hosting/authentication) before opening it. Tailscale Serve already limits access to your tailnet. Once the route is protected, [try it out](/docs/self-hosting/overview#try-it-out).
## A server you manage
-A VPS, Mac mini, or any computer you can leave running. It keeps your knowledge base available at all times, and you keep full control of the box.
+Use a VPS, Mac mini, or another always-on computer. This keeps the knowledge base available continuously.
-### Set up the box
+### Set up the server
-On a VPS, providers like Hetzner, DigitalOcean, and Lightsail all work. Pick Ubuntu 24.04 (1 GB RAM is comfortable; 512 MB runs a small knowledge base), add your SSH key at creation, and `ssh root@<ip>` in. Every step below happens in that shell.
+Create an Ubuntu 24.04 VPS with Hetzner, DigitalOcean, Lightsail, or another provider. Allocate 1 GB of RAM. A small knowledge base can run with 512 MB. Add an SSH key during setup, then connect with `ssh root@<ip>`. Run the following commands in that shell.
-Install OpenKnowledge (and Node 24 first, on a fresh box):
+Install Node 24 and OpenKnowledge:
```bash
curl -fsSL https://deb.nodesource.com/setup_24.x | sudo bash - && sudo apt-get install -y nodejs git
@@ -131,11 +135,11 @@ mkdir ~/knowledge && cd ~/knowledge && ok init
To start from existing notes, `git clone` them as the project directory instead of `mkdir`, then run `ok init` inside.
-### Give it a URL
+### Configure network access
-Two good options:
+Choose one of these access methods:
-- **A tunnel**: exactly the [laptop steps above](#1-pin-a-port-and-open-a-tunnel), run on the server. Tailscale is especially natural here: the box joins your tailnet and only your devices can reach it, with nothing exposed to the public internet.
+- **A tunnel.** Follow the [laptop tunnel steps](#1-pin-a-port-and-open-a-tunnel) on the server. With Tailscale, add the server to your tailnet. Only devices on the tailnet can connect.
- **Your own domain with a reverse proxy.** Point DNS at the server and let [Caddy](https://caddyserver.com/) terminate TLS (it provisions certificates automatically):
```text title="/etc/caddy/Caddyfile"
@@ -150,9 +154,9 @@ Two good options:
externalUrl: https://notes.example.com
```
- Caddy handles the [proxy rules](/docs/self-hosting/methods/docker#rules-for-anything-in-front-of-the-server) (Host preservation, `X-Forwarded-Proto`, no buffering on `/mcp`) automatically; just don't add an `encode` directive on `/mcp`. A different proxy (nginx, etc.) needs those set by hand, or requests 403 and the editor's WebSocket fails.
+ Caddy automatically handles the [proxy rules](/docs/self-hosting/methods/docker#rules-for-anything-in-front-of-the-server), including Host preservation, `X-Forwarded-Proto`, and no buffering on `/mcp`. Do not add an `encode` directive on `/mcp`. Configure these rules yourself when using another proxy such as nginx. Without them, requests may return `403` and the editor's WebSocket may fail.
-Either way, consent on the box (`.ok/local/config.yml` with `allowExternal: true` and `idleShutdown: "off"`, as in the laptop path; the same [config-and-start step](#2-configure-and-start) applies unchanged).
+For either option, allow external access in `.ok/local/config.yml` by setting `allowExternal: true` and `idleShutdown: "off"`. Use the same [configuration and start steps](#2-configure-and-start) as the laptop setup.
### Run it as a service
@@ -173,7 +177,7 @@ Restart=on-failure
WantedBy=multi-user.target
```
-This matches the `ssh root@<ip>` VPS setup above (project at `/root/knowledge`, `server.*` set in config; the unit needs no flags). If you log in as a different user, set `User` and `WorkingDirectory` to that user and their project path. For a hardened setup, run it under a dedicated unprivileged user (`sudo useradd --system --create-home openknowledge`) rather than `root`, with `User` and `WorkingDirectory` set to match.
+This matches the `ssh root@<ip>` VPS setup above. The project is at `/root/knowledge`, and the `server.*` settings are in the config file, so the unit needs no flags. If you use a different account, update `User` and `WorkingDirectory` to match that account and project path. For a more secure setup, create a dedicated unprivileged account with `sudo useradd --system --create-home openknowledge`. Then update `User` and `WorkingDirectory` to match.
Register the service so it starts on every boot, and launch it now:
@@ -182,10 +186,10 @@ sudo systemctl enable --now openknowledge
```
<Callout>
-**On macOS and Windows**, systemd isn't available. For a simple always-on setup, run `ok start` in a terminal and configure the machine not to sleep. For unattended restarts, use the platform's service manager: launchd on macOS or Task Scheduler / a Windows service on Windows.
+**macOS and Windows do not use systemd.** Run `ok start` in a terminal and disable sleep. For automatic restarts, use launchd on macOS, or Task Scheduler or a Windows service on Windows.
</Callout>
-Now [try it out](/docs/self-hosting/overview#try-it-out), then [restrict who can reach it](/docs/self-hosting/authentication).
+If the URL is public, [add access control](/docs/self-hosting/authentication) before opening it. Once the route is protected, [try it out](/docs/self-hosting/overview#try-it-out).
## Back up to a git remote
diff --git a/docs/content/self-hosting/methods/docker.mdx b/docs/content/self-hosting/methods/docker.mdx
index 75b03bc44..b516d1085 100644
--- a/docs/content/self-hosting/methods/docker.mdx
+++ b/docs/content/self-hosting/methods/docker.mdx
@@ -3,17 +3,17 @@ title: Docker
icon: custom/Docker
description: Build the OpenKnowledge container image and run it on Railway, Fly.io, or any Docker host.
---
-For an always-on knowledge base without managing a box, run the server as a container on a hosting platform (Railway, Fly.io, or your own Docker host). The platform provides the domain and TLS; a volume holds the project; the `OK_*` environment variables carry the same declarations as every other path. Read [How exposure works](/docs/self-hosting/overview#how-exposure-works) first if you haven't.
+For an always-on knowledge base without managing a box, run the server as a container on a hosting platform (Railway, Fly.io, or your own Docker host). The platform provides the domain and TLS. A volume holds the project. The `OK_*` environment variables carry the same declarations as every other path. Start with the [self-hosting overview](/docs/self-hosting/overview) if you have not chosen an access path yet.
## What any host must provide
The recipes on this page are examples, not requirements. The server runs anywhere that provides:
-- **One always-on instance.** The collaboration server is single-writer: exactly one server process per project. Don't scale to multiple replicas, and don't scale to zero between requests.
+- **Run one always-on instance.** The collaboration server supports one server process per project. Keep the replica count at one and do not scale to zero between requests.
- **A persistent volume with a real filesystem**, mounted at `/data`. The project is a live git repository the server watches and writes. Container-layer storage is lost on recreate, and network filesystems built for object storage fit it poorly.
-- **HTTP ingress that supports WebSockets and doesn't buffer streaming responses.** Live editing runs over a WebSocket, and `/mcp` streams server-sent events (details in the [proxy rules](#rules-for-anything-in-front-of-the-server) below).
-- **TLS at the edge, with `X-Forwarded-Proto: https` preserved on the way in.** Every platform edge does this out of the box; if you insert your own plain-HTTP proxy, set the header yourself.
-- **The two declarations from [How exposure works](/docs/self-hosting/overview#how-exposure-works)**: `OK_EXTERNAL_URL` naming the public origin, and `OK_ALLOW_EXTERNAL=1` consenting to exposure.
+- **Use HTTP ingress that supports WebSockets and unbuffered streaming responses.** Live editing uses a WebSocket. `/mcp` uses server-sent events. See the [proxy rules](#rules-for-anything-in-front-of-the-server).
+- **Use TLS at the edge and preserve `X-Forwarded-Proto: https`.** Hosting platforms usually handle this automatically. If you add your own plain HTTP proxy, set the header yourself.
+- **The two remote-access declarations from the [configuration reference](/docs/reference/configuration)**: `OK_EXTERNAL_URL` names the public origin, and `OK_ALLOW_EXTERNAL=1` consents to exposure.
Anything that checks those boxes, whether a hosting platform, an orchestrator, or a box under your desk, will run the image.
@@ -33,7 +33,7 @@ RUN apt-get update \
RUN npm install -g @inkeep/open-knowledge
# PORT is the platform-injection contract: Railway/Fly/Cloud Run override
-# it at run time; 8080 is only the local-run default.
+# it at run time. 8080 is only the local default.
# OK_BIND=0.0.0.0 makes the listener reachable from the container network.
# Consent (OK_ALLOW_EXTERNAL=1) is deliberately NOT baked: a run without it
# refuses to boot and names the fix. That refusal is the secure default.
@@ -52,17 +52,20 @@ RUN chmod +x /usr/local/bin/entrypoint.sh
ENTRYPOINT ["/usr/local/bin/entrypoint.sh"]
```
-The entrypoint is the container's boot script, run on every start. `ok start` needs an initialized project, and no one is inside the container to run `ok init` by hand, so the script does it: the first boot against an empty volume initializes the project, and every boot after finds `.ok/` already there and goes straight to the server. It's the same pattern the official database images use for an empty data directory. (`--no-mcp --no-skills` only skip scaffolding local agent config and skill files the container doesn't need; the server's own `/mcp` endpoint is always served.)
+The entrypoint is the container's boot script. It runs every time the container starts. `ok start` needs an initialized project, but no one is inside the container to run `ok init`. The script handles this automatically. The first boot initializes the project on the empty volume. Later boots find `.ok/` and start the server directly. Official database images use the same pattern for empty data directories.
+
+The `--no-mcp --no-skills` flags only skip local agent configuration and skill files that the container does not need. The server still provides its `/mcp` endpoint.
```sh title="entrypoint.sh"
#!/bin/sh
# First-boot init: scaffold the project exactly once, on an empty volume.
-# Any initialized (or restored) volume skips straight to `ok start`.
+# An initialized or restored volume starts the server.
# stdin is closed so `ok init` takes its non-TTY defaults and can never
# hang on a prompt.
set -eu
-if [ ! -d /data/.ok ]; then
- echo "[entrypoint] /data not initialized — running: ok init --no-mcp --no-skills"
+if [ ! -d /data/.ok ]
+then
+ echo "[entrypoint] /data is not initialized. Running ok init --no-mcp --no-skills"
ok init --no-mcp --no-skills < /dev/null
fi
exec ok start
@@ -80,11 +83,11 @@ docker run --rm -p 8080:8080 -e OK_ALLOW_EXTERNAL=1 -v ok-data:/data open-knowle
| Variable | Container default | Meaning |
| --- | --- | --- |
-| `PORT` | `8080` | Listen port. Platform-injected `PORT` (Railway, Fly, Cloud Run) overrides it at run time; don't set it yourself on those platforms. |
-| `OK_BIND` | `0.0.0.0` | Bind address list. On an IPv6-only network set `::` instead (dual-stack, serves IPv4 too); don't combine `0.0.0.0 ::` on one port, since the dual-stack listener collides. |
+| `PORT` | `8080` | Listen port. Railway, Fly, and Cloud Run set `PORT` automatically. Do not set it yourself on those platforms. |
+| `OK_BIND` | `0.0.0.0` | Bind address list. On an IPv6-only network, use `::` instead. It also serves IPv4. Do not combine `0.0.0.0 ::` on one port because the listeners conflict. |
| `OK_ALLOW_EXTERNAL` | unset | Run-time exposure consent. Without it the interlock refuses to boot. |
| `OK_EXTERNAL_URL` | unset | The public origin the deployment is reached at. Required behind any real domain, or hostname requests are rejected with `403`. |
-| `OK_IDLE_SHUTDOWN` | unset | Idle shutdown already defaults to `off` on a non-loopback bind; set a duration (`30m`) to opt back in. |
+| `OK_IDLE_SHUTDOWN` | unset | Idle shutdown defaults to `off` on a non-loopback bind. Set a duration such as `30m` to turn it back on. |
Health endpoints for platform checks: `GET /healthz` (liveness) and `GET /readyz` (readiness).
@@ -94,7 +97,7 @@ The collaboration server is single-writer: one server process per project volume
## Deploy on Railway
-Railway builds the Dockerfile server-side, injects `PORT` and TLS, and hands out a domain; the whole flow is one deploy. From the directory with the `Dockerfile` and `entrypoint.sh`:
+Railway builds the Dockerfile, sets `PORT`, enables TLS, and provides a domain. The full setup takes one deploy. Run these commands from the directory that contains `Dockerfile` and `entrypoint.sh`:
```bash
railway login
@@ -103,15 +106,15 @@ railway add --service my-kb --variables "OK_ALLOW_EXTERNAL=1" # create the se
railway volume --service <service-id> add --mount-path /data # persistent volume (see note below)
railway domain --service my-kb --port 8080 # generate the domain (works pre-deploy)
railway variables --service my-kb --set 'OK_EXTERNAL_URL=https://${{RAILWAY_PUBLIC_DOMAIN}}'
-railway up --service my-kb --detach # one deploy; externalUrl correct from first boot
+railway up --service my-kb --detach # one deploy with externalUrl set on first boot
railway logs --service my-kb # watch the first boot
```
-`${{RAILWAY_PUBLIC_DOMAIN}}` is a Railway reference variable that resolves to the generated domain at deploy time, so `OK_EXTERNAL_URL` is right from the first boot, with no deploy-then-set-then-redeploy loop. On first boot the entrypoint initializes the empty volume, then the server comes up; the log shows the exposure banner naming your domain. Set the platform health check to `/readyz`.
+`${{RAILWAY_PUBLIC_DOMAIN}}` is a Railway reference variable. It resolves to the generated domain during deployment, so `OK_EXTERNAL_URL` is correct on the first boot. The entrypoint initializes the empty volume and starts the server. The log shows an exposure banner with your domain. Set the platform health check to `/readyz`.
A few Railway-specific caveats:
-- **Don't set `PORT`.** Railway injects it, and setting it yourself fights the platform.
+- **Do not set `PORT`.** Railway sets it automatically.
- **Leave replicas at 1** (see the single-writer callout above).
- **`railway volume` wants the service ID, not the name.** Every other command above accepts the service name, but on current CLIs `volume` can crash on a name. Get the ID from `railway status --json`.
- **Subcommand flags drift across Railway CLI versions.** If a command errors, check `railway <cmd> --help` for where the `--service` flag goes.
@@ -119,27 +122,29 @@ A few Railway-specific caveats:
## Other platforms
-The same image runs anywhere Docker does. On Fly.io, mount a volume at `/data`, set the same two `OK_*` variables with the `.fly.dev` domain, and point a check at `/readyz`. With Docker Compose (on a platform *or* your own VPS; the pieces mix and match), you can instead add a `cloudflared` sidecar as the only ingress, skip the public domain entirely, and set `OK_EXTERNAL_URL` to the tunnel hostname.
+The same image runs anywhere Docker is available. On Fly.io, mount a volume at `/data`, set the same two `OK_*` variables with the `.fly.dev` domain, and point a health check at `/readyz`.
+
+With Docker Compose, you can add a `cloudflared` sidecar as the only ingress. This works on a hosting platform or your own VPS. You do not need a separate public domain. Set `OK_EXTERNAL_URL` to the tunnel hostname.
-The big clouds (AWS, GCP, Azure) run the image well on a VM with Docker, or you can use the [npm method](/docs/self-hosting/methods/npm#a-server-you-manage) directly. Their serverless container products are a weaker fit: they don't always provide a persistent disk that meets the [requirements above](#what-any-host-must-provide), and some scale in ways the single-writer server can't use. Fully serverless platforms (Vercel, Netlify) can't host it: the server is one long-lived stateful process, not request-scoped functions.
+AWS, Google Cloud, and Azure can run the image on a virtual machine with Docker. You can also use the [CLI method](/docs/self-hosting/methods/cli#a-server-you-manage) on a virtual machine. Serverless container services must provide persistent storage and support one always-on replica. Vercel and Netlify cannot host OpenKnowledge because they run request-based functions instead of one long-lived stateful process.
## Upgrading
-The image installs whatever version of `@inkeep/open-knowledge` is current at build time, so upgrading means rebuilding the image and redeploying onto the same volume. The entrypoint finds the volume already initialized and goes straight to the server; your content, history, and settings all live on the volume and carry over. On Railway, that's `railway up` again from the Dockerfile directory.
+The image installs the current version of `@inkeep/open-knowledge` when you build it. To upgrade, rebuild the image and deploy it to the same volume. The entrypoint finds the existing project and starts the server. Your content, history, and settings remain on the volume. On Railway, run `railway up` again from the Dockerfile directory.
Two practices make this predictable:
-- **Pin the version in the Dockerfile** (`RUN npm install -g @inkeep/open-knowledge@<version>`) and bump the line to upgrade. An unpinned install can silently reuse Docker's cached build layer, leaving you on the old version while looking freshly deployed; a pinned bump changes the line, which busts the cache, and it gives you an exact version to rebuild if you ever want to go back.
-- **Snapshot the volume before upgrading**: your platform's volume backup, or a plain tar of `/data`. A snapshot restored onto a fresh volume boots straight to the server, since the entrypoint treats any initialized volume as ready.
+- **Pin the version in the Dockerfile.** Use `RUN npm install -g @inkeep/open-knowledge@<version>` and update the version when you upgrade. An unpinned install can reuse Docker's cached build layer and leave you on an older version. Changing a pinned version clears that cache and gives you an exact version to rebuild later.
+- **Back up the volume before upgrading.** Use the hosting platform's volume backup or create a tar archive of `/data`. Restoring the backup to a new volume preserves the initialized project.
## Rules for anything in front of the server
Three rules apply to any proxy you place between clients and the container (an auth proxy, nginx, a CDN layer):
-- **Preserve the original `Host` header.** The server admits requests by their `Host`, matched against `OK_EXTERNAL_URL`. Many reverse proxies rewrite `Host` to the *upstream* address (`ok:8080`) by default, which no longer matches and gets rejected with `403` on **every** request. Forward the client's host instead: Caddy `header_up Host {host}`, nginx `proxy_set_header Host $host;`. Platform edges preserve it automatically; a proxy you add yourself usually does not.
-- **Never buffer `/mcp`.** It's a streaming (server-sent events) endpoint; a proxy that buffers or compresses it hangs every agent connection until timeout. nginx needs `proxy_buffering off;` on that path; Caddy streams by default; platform edges pass SSE through. The rule applies to any proxy *you* add.
-- **A TLS-terminating proxy that speaks plain HTTP to the server must set `X-Forwarded-Proto: https`.** The server derives secure WebSocket URLs (`wss://`) from that header; a proxy that stamps it back to `http` makes the editor try an insecure `ws://` from an `https://` page, which browsers block, leaving the editor stuck on loading skeletons. Platform edges set it correctly; an auth proxy between the edge and the server often does not.
+- **Preserve the original `Host` header.** The server compares each request's `Host` with `OK_EXTERNAL_URL`. Many reverse proxies replace `Host` with the upstream address, such as `ok:8080`. The server rejects these requests with `403`. Forward the client's host instead. In Caddy, use `header_up Host {host}`. In nginx, set the `Host` header to `$host` with `proxy_set_header`. Hosting platform edges usually preserve it automatically. A proxy you add may not.
+- **Never buffer `/mcp`.** It is a streaming endpoint that uses server-sent events. A proxy that buffers or compresses the response causes agent connections to time out. In nginx, set `proxy_buffering` to `off` for this path. Caddy streams by default. Hosting platform edges pass server-sent events through. Apply this rule to any proxy you add.
+- **A TLS proxy that uses plain HTTP to reach the server must set `X-Forwarded-Proto: https`.** The server uses this header to create secure WebSocket URLs with `wss://`. If the proxy reports `http`, the editor tries to open an insecure `ws://` connection from an `https://` page. Browsers block the connection and the editor does not load. Hosting platform edges usually set the header correctly. An authentication proxy between the edge and the server may not.
## Next steps
-[Try the deployment](/docs/self-hosting/overview#try-it-out) with a real MCP handshake against the public domain, then lock it down: the platform domain has no login of its own, so anyone who finds the URL has full read-write control until you [add authentication](/docs/self-hosting/authentication).
+The platform domain has no login of its own, so anyone who finds the URL has full read and write access. [Add authentication](/docs/self-hosting/authentication) before opening the public domain. Once the route is protected, [try it out](/docs/self-hosting/overview#try-it-out), then [Connect remote agents](/docs/self-hosting/connecting-agents).
diff --git a/docs/content/self-hosting/methods/meta.json b/docs/content/self-hosting/methods/meta.json
index f92d690ad..e587e257a 100644
--- a/docs/content/self-hosting/methods/meta.json
+++ b/docs/content/self-hosting/methods/meta.json
@@ -2,5 +2,5 @@
"title": "Deployment methods",
"icon": "LuBoxes",
"defaultOpen": true,
- "pages": ["npm", "docker"]
+ "pages": ["cli", "docker"]
}
diff --git a/docs/content/self-hosting/overview.mdx b/docs/content/self-hosting/overview.mdx
index 5633f0c7a..ee25893a3 100644
--- a/docs/content/self-hosting/overview.mdx
+++ b/docs/content/self-hosting/overview.mdx
@@ -1,73 +1,60 @@
---
title: Overview
icon: LuBookOpen
-description: Run OpenKnowledge on a server or container for shared, always-on access from your other devices and agents.
+description: Set up remote access to your OpenKnowledge server.
---
-By default, your knowledge base is only available on the machine it runs on. Set up remote control to open it from another device, point your agents at it, and let everyone work in the same place. Access control lives outside OpenKnowledge for now: a private network, or a login in front. See [Authentication](/docs/self-hosting/authentication).
+By default, OpenKnowledge is only available on the machine where it runs. Remote access lets your other devices, teammates, and agents connect to one shared project without installing OpenKnowledge on every machine.
-## How exposure works
+The setup has four parts: run the server, make it reachable, add access control, then connect through the browser or MCP.
-Remote control uses three settings:
+## Run the server
-| Setting | What it is | Where it goes |
-| --- | --- | --- |
-| `server.externalUrl` | The address clients will use, e.g. `https://kb.example.com`. | `.ok/config.yml`, committed, so the project's setup is shared with your team. |
-| `server.allowExternal` | Your permission to accept connections from outside the machine. | `.ok/local/config.yml`, which stays on this machine (gitignored), or the `OK_ALLOW_EXTERNAL=1` environment variable. |
-| `server.bind` | Which network addresses the server listens on. Most setups never set it: tunnels work with the default, and the container image sets it for you. | `.ok/local/config.yml`, or the `OK_BIND` environment variable. |
+There are three ways to run an OpenKnowledge server:
-These also exist as environment variables and CLI flags (`OK_EXTERNAL_URL` / `--external-url`) for one-off runs and for containers, where config files aren't the natural home; each walkthrough uses whichever fits. The [Configuration reference](/docs/reference/configuration) has the full details on these settings.
+- [**Desktop**](/docs/get-started/quickstart#install-the-desktop-app-macos-windows-linux)
+- [**CLI**](/docs/self-hosting/methods/cli)
+- [**Docker**](/docs/self-hosting/methods/docker)
-<Callout type="info">
-**Everyone connects as the same owner.** There are no per-person accounts yet, so everyone who connects can read and edit everything, exactly as you can. You choose who that is with the options in [Authentication](/docs/self-hosting/authentication).
-</Callout>
+## Make the server reachable
-## Choose a deployment method
+Choose the instructions that match where your server runs:
-| You want | Method |
+| Your setup | What to follow |
| --- | --- |
-| To reach the machine you already work on, from your other devices | [npm: your laptop, behind a tunnel](/docs/self-hosting/methods/npm#your-laptop-behind-a-tunnel) |
-| An always-on server you run yourself | [npm: a VPS or any box you manage](/docs/self-hosting/methods/npm#a-server-you-manage) |
-| An always-on server, run for you by a hosting platform | [Docker: a container on a hosting platform](/docs/self-hosting/methods/docker) |
-
-These are recommended pairings, not rules; the pieces mix and match. You can run the container on your own VPS, or run a tunnel next to a container on Railway and skip the public domain entirely. However you assemble it, the server reads the same settings, so every method ends at the same [try-it-out step](#try-it-out) and the same [access-control options](/docs/self-hosting/authentication).
-
-## Try it out
+| Desktop or CLI on your computer | [Connect the computer through a private network or tunnel](/docs/self-hosting/methods/cli#your-laptop-behind-a-tunnel). If Desktop already runs the project, skip the CLI installation step. The networking settings are the same. |
+| CLI on an always-on machine | [Set up a server you manage](/docs/self-hosting/methods/cli#a-server-you-manage). |
+| Docker | [Deploy the container](/docs/self-hosting/methods/docker). |
-Whichever method you picked, you now have one URL that works two ways: open it in a browser to edit, or point an agent at `/mcp`. Try both.
+Each method provides an HTTPS URL and the required configuration. See the [configuration reference](/docs/reference/configuration) for all available settings.
-### In a browser
+## Add access control
-```
-https://<your-external-url>/
-```
+<Callout type="warn">
+**Never expose OpenKnowledge directly to the public internet.** Use a private network, or put authentication in front of the server before opening or sharing a public URL.
+</Callout>
-Open it on any device that can reach the address. The editor loads, and edits sync in real time between every connected browser and agent. That's your first proof the whole path works.
+OpenKnowledge does not have built-in user accounts yet. Everyone who can reach the server has full read and write access as the same owner.
-Anyone who can open the URL can edit alongside you, all as the same owner, since there are no per-person accounts. Share it deliberately and only with people you trust.
+A private network such as Tailscale can be the access-control layer. A public URL needs an authentication edge or proxy in front of it. Follow [Authentication](/docs/self-hosting/authentication) before continuing.
-### With agents
+## Try it out
-```
-https://<your-external-url>/mcp
-```
+Once the server is reachable and protected, the same URL provides both connection points.
-For a quick check without configuring an agent, do the handshake by hand from any device that can reach the address:
+Open the editor in a browser:
-```bash
-curl -sS -X POST https://<your-external-url>/mcp \
- -H 'content-type: application/json' \
- -H 'accept: application/json, text/event-stream' \
- -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"0"}}}'
+```text
+https://<your-external-url>/
```
-The server responds with its details:
+Connect agents to the MCP endpoint:
-```json
-{"result":{"protocolVersion":"2025-06-18","capabilities":{"tools":{"listChanged":true}},"serverInfo":{"name":"open-knowledge","version":"…"}},"jsonrpc":"2.0","id":1}
+```text
+https://<your-external-url>/mcp
```
-Then point real agents at that URL. [Connecting agents](/docs/self-hosting/connecting-agents) has per-client setup (Claude, Cursor, Codex, and others), including how a headless agent passes edge-auth credentials. Anyone who can open this URL has full read-write access.
+Open the browser URL first to confirm the editor loads. Then follow [Connect remote agents](/docs/self-hosting/connecting-agents) for Claude, Cursor, Codex, and other MCP clients. Give teammates the browser URL plus any network access or credential required by your access-control setup.
-## Turning it off
+## Turn off remote access
-Withdraw your permission by removing `server.allowExternal` from `.ok/local/config.yml` (or no longer passing `OK_ALLOW_EXTERNAL=1`) and restarting; on the default loopback bind the server goes back to refusing outside connections. A container built from the [Docker method](/docs/self-hosting/methods/docker) bakes a non-loopback `OK_BIND`, so dropping consent there makes it refuse to boot instead of falling back. Stopping the tunnel or removing the container's public domain cuts off access from the other side. If the address may have leaked further than intended, rotate it at the edge: ngrok and Cloudflare mint a fresh URL on restart, Tailscale ACLs can be tightened, and a platform domain can be regenerated.
+Remove `allowExternal: true` from `.ok/local/config.yml`, or remove `OK_ALLOW_EXTERNAL=1`, then restart OpenKnowledge. The Docker setup on this site uses `OK_BIND=0.0.0.0`, so the container will refuse to start without external-access consent. Stop the tunnel or disable the public domain to close network access. If a public URL was exposed, regenerate it or rotate the domain at your tunnel or hosting provider.
diff --git a/docs/next.config.ts b/docs/next.config.ts
index 32d2b78ad..f5694f78c 100644
--- a/docs/next.config.ts
+++ b/docs/next.config.ts
@@ -121,6 +121,16 @@ const nextConfig: NextConfig = {
destination: '/docs/self-hosting/overview',
permanent: true,
},
+ {
+ source: '/docs/self-hosting/methods/npm',
+ destination: '/docs/self-hosting/methods/cli',
+ permanent: true,
+ },
+ {
+ source: '/docs/self-hosting/methods/npm/',
+ destination: '/docs/self-hosting/methods/cli',
+ permanent: true,
+ },
{
source: '/docs/deploy/connecting-agents',
destination: '/docs/self-hosting/connecting-agents',