CLI

Install OpenKnowledge from npm, then run the server yourself:

npm install -g @inkeep/open-knowledge

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 to choose an access method.

Your laptop, behind a tunnel

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 or the Docker method.

1. Pin a port and open a tunnel

A local start normally picks a free port dynamically, but a tunnel forwards to one fixed port, so pin it first. Add a server: block to the .ok/config.yml that ok init created (the file is all commented defaults until you add keys):

server:
  port: 8080

Any HTTPS tunnel works. It forwards a public URL to that local port. Pick one:

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

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

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

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

Declare the public origin in the project config, next to the port:

server:
  port: 8080
  externalUrl: https://<your-tunnel-url>

Then consent on this machine, in the gitignored per-machine config:

server:
  allowExternal: true
  idleShutdown: "off"

idleShutdown: "off" keeps the server from stopping after 30 idle minutes. The idle timer only counts editor connections, not agent calls, so without it a server busy with a remote agent looks idle and shuts down mid-session.

Now start it from the project directory:

ok start

The server prints a warning banner naming the public origin on every exposed start. For a one-off session, the environment does the same job without touching config files:

OK_ALLOW_EXTERNAL=1 OK_IDLE_SHUTDOWN=off ok start --external-url https://<your-tunnel-url> --port 8080

If the URL is public, add access control before opening it. Tailscale Serve already limits access to your tailnet. Once the route is protected, try it out.

A server you manage

Use a VPS, Mac mini, or another always-on computer. This keeps the knowledge base available continuously.

Set up the server

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 Node 24 and OpenKnowledge:

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.

Configure network access

Choose one of these access methods:

• A tunnel. Follow the laptop tunnel steps 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 terminate TLS (it provisions certificates automatically):

  notes.example.com {
      reverse_proxy 127.0.0.1:8080
  }

  server:
    port: 8080
    externalUrl: https://notes.example.com

  Caddy automatically handles the proxy rules, 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.

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 as the laptop setup.

Run it as a service

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
Restart=on-failure

[Install]
WantedBy=multi-user.target

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:

sudo systemctl enable --now openknowledge

If the URL is public, add access control before opening it. Once the route is protected, try it out.

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 '\nautoSync:\n  mode: full\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.