# CLI (https://openknowledge.ai/docs/remote-control/methods/cli)

Run OpenKnowledge with the CLI on your computer, a VM, or a server.

Install OpenKnowledge from npm, then run the server yourself:

```bash
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 [Remote Control overview](https://openknowledge.ai/docs/remote-control/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](https://openknowledge.ai/docs/remote-control/methods/cli#a-server-you-manage) or the [Docker method](https://openknowledge.ai/docs/remote-control/methods/docker).

### 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):

```yaml title=".ok/config.yml"
server:
  port: 8080
```

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

> **Info**
>
> Install the tunnel client on the machine before continuing.

> **Warn**
>
> Tailscale Serve stays inside your tailnet. Before starting ngrok or Cloudflare Tunnel, [set up authentication](https://openknowledge.ai/docs/remote-control/authentication) at that edge. Do not open an unprotected public URL.

### Tailscale

Private, only devices on your tailnet can reach it. Requires [HTTPS enabled in your tailnet](https://tailscale.com/kb/1153/enabling-https).

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

If `serve` says Tailscale is stopped, run `tailscale up` first (on a Linux server you may also need `sudo systemctl start tailscaled`).

### ngrok

Public URL. Add access control at the edge. See [Authentication](https://openknowledge.ai/docs/remote-control/authentication).

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

### Cloudflare Tunnel

A quick public URL on a `*.trycloudflare.com` address, fresh each run. For a stable URL on your own domain, and to pair with [Cloudflare Access](https://openknowledge.ai/docs/remote-control/authentication), set up a [named tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/) instead.

```bash
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:

```yaml title=".ok/config.yml"
server:
  port: 8080
  externalUrl: https://<your-tunnel-url>
```

> **Warn**
>
> **`server.externalUrl` must match the public address.** Use the full tunnel URL with `https://` and no trailing path. A mismatch returns `403`.

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

```yaml title=".ok/local/config.yml"
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:

```bash
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:

```bash
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](https://openknowledge.ai/docs/remote-control/authentication) before opening it. Tailscale Serve already limits access to your tailnet. Once the route is protected, [try it out](https://openknowledge.ai/docs/remote-control/overview#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:

```bash
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):

```bash
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](https://openknowledge.ai/docs/remote-control/methods/cli#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"
  notes.example.com {
      reverse_proxy 127.0.0.1:8080
  }
  ```

  ```yaml title=".ok/config.yml"
  server:
    port: 8080
    externalUrl: https://notes.example.com
  ```

  Caddy automatically handles the [proxy rules](https://openknowledge.ai/docs/remote-control/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.

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](https://openknowledge.ai/docs/remote-control/methods/cli#2-configure-and-start) as the laptop setup.

### Run it as a service

So it survives logout and reboots:

```ini title="/etc/systemd/system/openknowledge.service"
[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:

```bash
sudo systemctl enable --now openknowledge
```

> **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.

If the URL is public, [add access control](https://openknowledge.ai/docs/remote-control/authentication) before opening it. Once the route is protected, [try it out](https://openknowledge.ai/docs/remote-control/overview#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:

```bash
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:

```bash
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](https://openknowledge.ai/docs/features/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.