Remote access

By default, only agents on the same machine as your knowledge base can reach it. Remote access puts that same endpoint behind an HTTPS tunnel (ngrok, Cloudflare Tunnel, Tailscale, or your own reverse proxy) so your other devices can connect to one shared knowledge base.

OpenKnowledge does not authenticate remote callers. Once you pass --remote, anyone who can reach your tunnel URL has full read-write control, so restricting who reaches it is up to the tunnel. Put it on a private network like Tailscale, add edge auth like ngrok OAuth or Cloudflare Access, or just keep the URL to yourself. The server ignores tunneled traffic until you start it with --remote, so you never expose the base by accident.

Set up the machine

Remote access runs on the machine that holds your knowledge base. Pick where it lives and get OpenKnowledge running a project there.

Your laptop or desktop

Your laptop or desktop, where OpenKnowledge is already installed and running your project. Nothing to prepare, so skip ahead to Turn on remote access.

The catch is that it's only reachable while that machine is awake. Close the lid and your agents lose access. For around-the-clock access, use a dedicated server instead.

A dedicated server

A VPS, Mac mini, or any computer you can leave running. It keeps your knowledge base reachable around the clock, so agents never lose access. Set it up first.

Install OpenKnowledge (and Node 24 first, on a fresh box):

curl -fsSL https://deb.nodesource.com/setup_24.x | sudo bash - && sudo apt-get install -y nodejs git
npm install -g @inkeep/open-knowledge

Create the project (ok init sets up git for you):

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.

Turn on remote access

Run these on the machine you set up.

1. Open a tunnel

Any HTTPS tunnel works. It forwards a public URL to the server's local port, 24550 by default (change it with remote.port in .ok/config.yml; see the Configuration reference). Point your tunnel at that same port. Pick one:

tailscale serve --bg 24550
# → https://<machine>.<tailnet>.ts.net

ngrok http 24550
# → https://<something>.ngrok.app

cloudflared tunnel --url http://localhost:24550

Each one gives you a public HTTPS URL. That URL is your remote.url.

2. Start the server with --remote

From the project directory:

ok start --remote https://<your-tunnel-url>

Or persist the URL in .ok/config.yml and start with a bare flag:

remote:
  url: https://<your-tunnel-url>

ok start --remote

The flag is required every start. A remote.url sitting in config never turns remote access on by itself, and the server prints a warning banner on every remote start so the exposure is never silent. Without --remote, tunneled requests are refused with a hint rather than served.

On a dedicated server, run it as a service instead, so it survives logout and reboots:

[Unit]
Description=OpenKnowledge server
After=network-online.target

[Service]
User=root
WorkingDirectory=/root/knowledge
ExecStart=/usr/bin/env ok start --remote
Restart=on-failure

[Install]
WantedBy=multi-user.target

This matches the ssh root@<ip> VPS setup above (project at /root/knowledge, remote.url set in config). If you log in as a different user, set User and WorkingDirectory to that user and their project path.

sudo systemctl enable --now openknowledge

3. Verify

From any device that can reach the tunnel, do a real handshake:

curl -sS -X POST https://<your-tunnel-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"}}}'

Your knowledge base introduces itself:

{"result":{"protocolVersion":"2025-06-18","capabilities":{"tools":{"listChanged":true}},"serverInfo":{"name":"open-knowledge","version":"…"}},"jsonrpc":"2.0","id":1}

That's the whole path working. You now have an MCP URL for your knowledge base:

https://<your-tunnel-url>/mcp

4. Restrict who can reach it

The server admits whoever the tunnel lets through, so we recommend adding access control at the tunnel:

• Tailscale serve is restricted by construction: only devices on your tailnet can connect. Use tailnet ACLs to narrow it further. (tailscale funnel makes the URL public — treat it like any public tunnel.)

• ngrok can require a login at the edge before any request reaches you. Use OAuth (or OIDC/SSO — --oidc, for Okta / Azure AD / Google Workspace):

  ngrok http 24550 --oauth google --oauth-allow-email you@example.com

• Cloudflare Tunnel pairs with Cloudflare Access — a login policy on the hostname, checked at Cloudflare's edge.

A public tunnel URL with no edge auth is a capable but open knowledge base: fine for a deliberate share, wrong as a default. The URL itself is the only secret, and URLs leak.

on_http_request:
  - expressions: ["req.url.path.startsWith('/mcp')"]
    actions:
      - type: basic-auth
        config: { credentials: ["agent:CHANGE_ME"] }
  - expressions: ["!req.url.path.startsWith('/mcp')"]
    actions:
      - type: oauth
        config: { provider: google }

Share your knowledge base

Now that it's reachable, there are two ways in: a browser for people, and the MCP endpoint for agents.

In a browser

The same tunnel URL serves the web UI:

https://<your-tunnel-url>/

Open it in any browser that can reach the tunnel to browse and edit the knowledge base. The UI and the MCP endpoint share the one URL (/ is the editor, /mcp is for agents); there is no separate ok ui port in remote mode.

Editing is live: changes sync in real time between every connected browser and agent. A few behaviors to know:

• Every remote browser acts as the server's owner. Same identity, full access.
• The Ask AI panel runs on the server. Each conversation spawns an agent on the machine hosting ok start, using that machine's installed agent and credentials (not anything on your device), and its edits sync back like any agent's. Install and sign in to an agent on the host for Ask AI to work over the tunnel.

Anyone you share the URL with can open it and edit alongside you, all as the same owner, since there are no per-person accounts. Share it deliberately and only with people you trust.

With agents

Point any MCP client at your endpoint:

https://<your-tunnel-url>/mcp

See Connecting agents for per-client setup (Claude, Cursor, Codex, and others), including how a headless agent passes edge-auth credentials.

Anyone who can reach this URL has full read-write access.

Back up to a git remote

Optional, but recommended for a server. Your knowledge base is a plain git repository, and OpenKnowledge has a built-in sync engine: point it at a GitHub remote and it commits and pushes as agents write, on its own.

Create an empty private GitHub repo, then on the machine:

gh auth login              # authorize this machine (or add a deploy key with write access)
cd ~/knowledge
git remote add origin https://github.com/you/knowledge.git
git branch -M main && git add -A && git commit -m "knowledge base" && git push -u origin main

Turn on auto-sync:

printf 'autoSync:\n  enabled: true\n' > .ok/local/config.yml
sudo systemctl restart openknowledge

From now on every edit is committed and pushed automatically. The commit author comes from the machine's git identity (git config user.name / user.email). A fresh server has none set, so commits fall back to a service identity, OpenKnowledge. Signing in with gh handles pushing, not authorship. Set a git identity if you'd rather commits carry your name. See GitHub sync for sync modes, conflict handling, and authentication.

The git remote is also a way to edit locally: git clone it on your laptop and open the clone in OK Desktop. That gives you a separate local copy with the full editor. It syncs with the server through git (each side pushes and pulls), not live, so changes cross over on the next sync rather than instantly.

Turning it off

Stop the tunnel, or restart the server without --remote — either one closes remote access (without the flag, the server refuses tunneled requests outright). If the URL may have leaked further than intended, rotate it at the tunnel (ngrok and Cloudflare mint a fresh URL on restart; on Tailscale, tighten the ACL).