Install in five minutes

Draft for review

This page takes you from nothing to a running OrchKernel server with its first admin signed in. It is for the person who runs OrchKernel for a company. To look around first, the demo company in Quickstart with the demo company needs no install of this kind; it is for trying things, not for real work.

Once the server runs, Production hardening covers HTTPS on your own domain, email, backups and the checklists, and the Operations reference has every setting, the backup format, upgrades and troubleshooting. Serving several organizations from one server is in Hosting several organisations.

No release has been published yet. The one-command install, the docker run one-liner and Compose with a published image all wait for the first tagged release. Until then, build the program or the image yourself (From a checkout); the install script and Compose work with what you built.

Before you start#

What you need#

Alpine and other musl systems, and Linux with an older glibc, use the Docker image. Windows is not supported.

What one server is, and is not#

• One company, one server, one file. Everything the company has lives in one SQLite file, the state file, on the server's own disk. There are no replicas and no failover: a restart takes a few seconds, and work waiting for a person survives it. If you need zero downtime, OrchKernel is not ready for you yet.
• Sizes measured: about a million items per company, with saving, lists and search answering in a fraction of a second for 16 people at once. The numbers and their two caveats are in How big it can get.
• Your data stays on your server. The only things that leave it are what you connect: the prompts agents send to the model providers you choose (each model sees only data up to the sensitivity you allow it), calls to the tool servers you configure, mail through your mail server, and backups, which are encrypted before they leave. On its own OrchKernel contacts only Hugging Face, once, to download the search-by-meaning model, and Let's Encrypt when you use --domain: no telemetry, no update checks. The details are in Your data.

Install with one command#

On the machine that will run OrchKernel:

curl -fsSL https://github.com/<owner>/<repository>/releases/latest/download/install.sh | sh

<owner>/<repository> is where the release is published; the release page gives the exact line. The script:

1. checks the system (macOS or Linux, the processor, glibc 2.28 or later on Linux; anything else gets the Docker one-liner below instead);

2. downloads the release archive for it and its SHA256SUMS, and checks the archive against it. With cosign installed it also checks the signature of SHA256SUMS, made by the release workflow; OK_REQUIRE_SIGNATURE=1 refuses to install without that check. It says which checks it made:

   textCopy

   Checksum: matches https://github.com/.../SHA256SUMS (9b1c...)
   Signature: verified with cosign (made by the release workflow of <owner>/<repository>)
   

   Any mismatch installs nothing and exits with status 1;

3. installs orchkernel (and an ok link when no other ok is on your PATH) and the bundled modules;

4. creates the data folder, readable only by you (0700), and says where everything is:

   textCopy

   Installed OrchKernel 0.3.0
     binary:  /home/ada/.local/bin/orchkernel (and ok)
     data:    /home/ada/.local/share/orchkernel (state.db, secrets.key; keep both private)
     backups: /home/ada/.local/share/orchkernel/backups/
     packs:   /home/ada/.local/share/orchkernel/packs
   

5. starts the server in the foreground, so you see its first-admin link (below). Ctrl-C stops it.

Where things go:

OK_INSTALL_DIR and OK_DATA_DIR choose other folders, and --prefix DIR puts the program under DIR/bin.

Keep it running: --service#

curl -fsSL .../install.sh | sh -s -- --service

On Linux this writes a systemd unit (as root, a system service running as the user orchkernel; otherwise a user service), starts it, waits up to 30 seconds for it to answer, and prints the first-admin link from its log. On macOS it writes a launchd agent that logs to orchkernel.log in the data folder. The service restarts the server if it stops, and starts it at boot.

HTTPS on your own domain: --domain#

curl -fsSL .../install.sh | sudo sh -s -- --service --domain work.acme.example

Before you run this, point the name's DNS at the server and open ports 80 and 443 to it: the certificate is obtained from Let's Encrypt over port 80. --domain needs root with --service on Linux, which gives the service the right to listen on ports 80 and 443 and nothing more. Try it against Let's Encrypt's test server first, which has generous limits: Domain and HTTPS shows how.

Other flags#

Without --domain, the server listens on 127.0.0.1:8080 (OK_BIND changes it). On a remote server you reach over SSH, that address is only reachable from the server itself, and the script says so: use --domain, or open a tunnel from your computer (ssh -L 8080:127.0.0.1:8080 <server>) and open the link in your browser.

Running the script again upgrades in place and says Upgraded OrchKernel 0.3.0 -> 0.4.0; the data is left as it is.

Docker#

docker run -d --name orchkernel --restart unless-stopped -p 8080:8080 \
  -v orchkernel-data:/data -e OK_PUBLIC_URL=http://localhost:8080 \
  ghcr.io/<owner>/orchkernel:latest
docker logs orchkernel 2>&1 | grep 'No admin yet'

The second line prints the first-admin link. The image runs as the non-root user orchkernel (uid 10001), keeps everything in the orchkernel-data volume (/data, 0700), checks its own health on /api/health, and carries the bundled modules at /opt/orchkernel/packs. OK_PUBLIC_URL is needed because the container listens on 0.0.0.0, which is no address a browser opens; http://localhost:8080 works on the machine itself. On a server, use your https address, or the Compose file below with HTTPS.

Tags: the release version (0.3.0) and latest; -embed tags (0.3.0-embed, latest-embed) carry the local embedding model for search by meaning, so the server never downloads it.

Docker Compose#

From a checkout of the repository (or with docker-compose.yml and deploy/compose.https.yml copied beside each other):

docker compose up -d
docker compose logs orchkernel | grep 'No admin yet'

By default Compose builds the image from the checkout as orchkernel/orchkernel:local; OK_IMAGE=ghcr.io/<owner>/orchkernel:0.3.0 uses a published one instead. Settings go in a .env file beside it (.env.example lists them all, commented out).

HTTPS with Compose. With the DNS name pointing at the host and ports 80 and 443 open:

OK_DOMAIN=work.acme.example OK_ACME_DIRECTORY=staging \
  docker compose -f docker-compose.yml -f deploy/compose.https.yml up -d

That gets a test certificate from Let's Encrypt's staging server (browsers will warn about it). When it works, run the same line without OK_ACME_DIRECTORY=staging for a real one. Docker lets the container's non-root user listen on 80 and 443.

From a checkout#

Until a release is published, build it yourself, in the repository folder:

(cd ui && npm ci && npm run build)      # the web workspace, built into the program
cargo build --release -p ok-cli

Then either run the install script on what you built:

mkdir -p dist && tar -C target/release -czf dist/orchkernel-local.tar.gz orchkernel
shasum -a 256 dist/orchkernel-local.tar.gz > dist/orchkernel-local.tar.gz.sha256   # sha256sum on Linux
OK_INSTALL_FILE=dist/orchkernel-local.tar.gz sh deploy/install.sh

(The flags above work here too: sh deploy/install.sh --service.)

or copy it into place yourself (install -m 0755 target/release/orchkernel /usr/local/bin/orchkernel and ln -sf orchkernel /usr/local/bin/ok), or build the image: docker build -t orchkernel/orchkernel:local ., then use orchkernel/orchkernel:local in the docker run line above.

Build inside the repository: its .cargo/config.toml turns on the SQLite settings that make many people at once fast. A build made without them works, says so once at start, and ok doctor repeats it under Build.

The first admin#

A server starting on an empty data folder creates the state file and the secrets key, and prints:

No admin yet. Open this link to create the first admin: http://127.0.0.1:8080/welcome#t=okl_... (valid 24 hours, once; the next start replaces it)

Open it. The page asks for your name, your email address (twice) and a password of at least 12 characters, makes you the first admin and signs you in. The link works once; if it expires, restart the server for a new one.

If you prefer the command line, ok init --admin ada --email ada@acme.example (with the server stopped) does the same and prints a setup link for Ada; see Setting up a company.

The setup wizard#

After the first sign-in, Get started walks through five steps, each with Continue and Skip:

1. Company: the company's name, your name, and two-step sign-in for yourself (optional).
2. Connect a model: below.
3. Search by meaning: the small model that runs on the server itself (on by default; it downloads once, about 91 MB).
4. Modules: the departments the company uses, or a blueprint that sets up a whole company.
5. Invite people: invite links to copy, or email once mail is set up.

Finish later leaves the wizard; a banner reminds admins of the steps left. Setting up a company explains each step.

Connect a model#

In the wizard's second step, or Models in the sidebar later: pick the provider (Anthropic, OpenAI, Gemini, Ollama or another OpenAI-compatible server), paste its key, choose Test, then pick the default model and how sensitive the data each model may see is. The key is sealed with the server's secrets key at once and never shown again. Without a model the workspace works, but agents cannot run, and every page says so. More in Models.

Where your data lives#

Everything is in the data folder:

Every file is readable only by the user the server runs as. Backups start on their own, daily, into backups/, but a copy on the same disk goes with the disk: the next step is to add an off-site copy and a recovery key.

Next#

Production hardening: your domain and HTTPS, email, off-site backups and the recovery key, sign-in settings, and the checklists to go through before people rely on it.