Run the headless broker

The headless broker is Okashic with no UI, for agents that run on a server. It holds the synced vault, serves the local MCP endpoint your agent connects to, applies credentials in-service, and writes the audit log — the same broker the apps carry, without the screen.

You run it on the machine where your agent runs. If your agent runs on your Mac or phone, the app already carries a broker and you can skip this page — go straight to Agents & MCP.

1. Download the broker

Download the okashic-broker binary for your server’s architecture from your account, then make it runnable and put it on your path:

terminal

chmod +x okashic-broker
sudo mv okashic-broker /usr/local/bin/
okashic-broker version

2. Point it at your account

The broker reads its configuration from the environment. For a server joining an account you already created on your phone or Mac, set the cloud URL and your credentials:

terminal

export OKASHIC_CLOUD_URL=https://api.okashic.io
export OKASHIC_EMAIL=you@example.com
export OKASHIC_PRIMARY_PASSWORD=…        # your primary password

Then join the account. This recovers the shared vault key on this device, the same way a second app does when you sign in:

terminal

okashic-broker login

If you’re setting up a brand-new account from the server instead, set OKASHIC_INVITE to your invite code and run okashic-broker enroll in place of login.

Keep the primary password out of your shell history

OKASHIC_PRIMARY_PASSWORD unlocks the vault. Don’t leave it in your shell history or a world-readable file. Put it in a root-owned EnvironmentFile with chmod 600, or load it from your secret manager — see the service unit below.

The vault lives at ~/.okashic/vault.sqlite by default; set OKASHIC_VAULT to move it.

3. Run it

terminal

okashic-broker serve

serve is also the default, so okashic-broker with no subcommand does the same thing. It serves the local API and the MCP endpoint on 127.0.0.1:8765 and syncs with the cloud. Leave it running; the next step points an agent at it.

The endpoint is loopback-only by default, so only processes on this machine can reach it. If your agent runs in a container, set OKASHIC_LOCAL_HOST to the bridge address the container can reach (for example 0.0.0.0) and OKASHIC_LOCAL_PORT to change the port — the agent still authenticates with its API key, so widening the bind doesn’t widen access.

4. Run it as a service

To keep the broker running across reboots, run it under systemd. Put the environment in a root-owned file so the password isn’t in the unit:

/etc/okashic/broker.env (chmod 600)

OKASHIC_CLOUD_URL=https://api.okashic.io
OKASHIC_EMAIL=you@example.com
OKASHIC_PRIMARY_PASSWORD=…

A ready-to-copy user unit ships in the repo at clients/broker/okashic-broker.service (with notes on providing the password as a systemd encrypted credential). The system unit below is equivalent:

/etc/systemd/system/okashic-broker.service

[Unit]
Description=Okashic headless broker
After=network-online.target
Wants=network-online.target
# Back off a crash-looping start (corrupt vault / failed migration) instead of hammering.
StartLimitIntervalSec=300
StartLimitBurst=5

[Service]
EnvironmentFile=/etc/okashic/broker.env
ExecStart=/usr/local/bin/okashic-broker serve
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

terminal

sudo systemctl daemon-reload
sudo systemctl enable --now okashic-broker
sudo systemctl status okashic-broker

Next: connect an agent

With the broker running, create an agent, point its MCP client at http://127.0.0.1:8765/mcp, and give it a connection. That’s the Agents & MCP walkthrough.

Common commands

okashic-broker runs the service and owns account and vault lifecycle; okashic --help lists everything. The ones you’ll reach for most:

• okashic-broker sync — push local records and pull the account’s newer ones. Writes sync on their own, so this is mostly for an explicit catch-up.
• okashic-broker connection add … / connection list — manage connections. connect and session capture cover the browser-based OAuth and website-session logins.
• okashic-broker audit verify — check the local audit log’s hash chain and signatures.
• okashic-broker device pair … — link a new device over the channel.

Creating agents and connections is owner work, so it lives in the okashic CLI, which drives whatever broker is running: okashic agent create, okashic connection add, okashic audit tail, okashic device list. See the Agents & MCP walkthrough.