olai web <directory> serves one directory of outlines to a browser.1
This page is its flags, the dot in the header, and its log.2
Run it
nix run github:juspay/olai -- web ~/notes
olai reads the directory and every folder under it,3 and the page keeps
up with the files on disk.4 A clone of olai’s repository has just
recipes for developers.5
Flags
| Flag | Default | What it does |
|---|---|---|
<directory> |
required | the directory to serve |
--port |
0, which asks the operating system for a port |
the TCP port to listen on |
--host |
127.0.0.1 |
the network interface to listen on |
--profile |
web |
which set of plugins to start6 |
Give --port a fixed number when you deploy olai.7
--hostbinds to127.0.0.1, your own machine, because olai asks for no password: anyone who can reach the port can read and change every outline it serves. Put a proxy in front to reach it from elsewhere (Keep olai running in the background).
The coloured dot in the header
One dot in the header shows whether anything needs your attention.8 Click it for a list with one line per thing it reports on.9
| Colour | Means |
|---|---|
| green | all is well |
| amber | something wants attention10 |
| red | something is broken: the server restarted, the page and the server are different versions, or a fault |
When the connection drops
The page freezes behind a card, a box drawn over it, and works again by itself when the connection returns.11 Other cards ask you to click Reload.12
Logging
The server writes one line per event to stdout.13 Set how much it
writes, and in which format, on the top-level olai node of the settings file
_olai/Settings.olai:
{"id":"olai","ord":"a0","title":"olai","custom":{"log-level":"debug","log-format":"logfmt"}}
| Key | Values | Default |
|---|---|---|
log-level |
debug, info, warn, error |
info |
log-format |
auto, logfmt, pretty |
auto, pretty on a terminal and logfmt elsewhere |
olai picks both up while it runs, with no restart.14
One olai per directory
Only one server can serve a directory at a time. Start a second olai over the same directory and it still shows its plugins panel, but the row for the directory itself, called the vault row, refuses to open it:
$ olai web ~/notes
ERROR: VaultInUse: another olai is serving this directory (pid 48219) — one brain per vault
48219 is the process id of the server that already has the directory, so
ps 48219 tells you which one it is. Reaching the same directory through a
symlink is still the same directory, because olai claims the place the files
are. A refusal that names no process id means the same thing.
The claim is an advisory lock, a marker the operating system keeps for as long
as the process lives. olai puts it outside your notes, in
$XDG_RUNTIME_DIR/olai/ or /tmp/olai-$UID/, and the kernel drops it when the
process ends. After a crash there is nothing to clean up, and no file is left
inside your directory.
Two things the lock does not stop:
- Another program writing the same files: your editor,
git pull, an agent writing by hand. The page shows those writes like any other. - Serving a directory that sits inside another one.
olai web ~/notesandolai web ~/notes/projectscount as two directories, so both servers start and both write the outlines they share. Serve one or the other.
A server that cannot claim the directory still serves its plugins panel and its MCP endpoint. Its vault row reads failed and shows the sentence naming the server that holds the directory, and every tool that needs the directory disappears from the list of tools agents can call. Once the other server stops, switch that row off and on again to retry.
Every line you see when you click the dot
- the connection to the server:
Connected,Connecting…,Reconnecting…,Partly connected, which means some updates are not arriving, orThe server restarted; - git’s Commit row, which opens the commit panel (Git: how olai records what it writes);
- one row for each running integration;
- how long this server has been running, as in
Running for 2h, withRunning since <instant>on its tooltip; - the Plugins row, which shuts that list and opens the plugins panel
(Switch olai's plugins on and off).
Escapeshuts that panel and puts the keyboard focus back on the dot.
What a log line holds, at each level and format
On a terminal olai keeps each line short: the fields sit inline, session identifiers are shortened, and the directory’s path appears only on a change to the directory, a warning or an error. An error still carries its full chain of causes, on indented lines below it.
When you pipe the output elsewhere, the logfmt format keeps the full path and
the full session annotations. At the debug level olai also logs the path and
arguments of every command it runs, the tool checks that succeeded, and
whatever an agent writes to its own stderr.
How to stop it, and the signals it refuses
Ctrl + C writes olai web: received SIGINT to stderr and exits with code
130, which the user service olai ships counts as a clean stop. That line is
how you tell, in the log, a server killed by a signal from one you stopped on
purpose.
On Linux olai obeys a SIGTERM, the polite request to shut down, only when it
comes from the service manager that started it, from the kernel telling it its
parent died, or from olai itself. It refuses every other one and says so on
stderr:
olai web: refused SIGTERM from pid N uid U (cmdline…)
The server keeps serving after a refusal, so a stray pkill -f does not take
it down. No process can refuse a SIGKILL, so kill -9, a service manager
running out of patience while stopping it, and the out-of-memory killer all
still end it. If olai cannot set this guard up, it says so once at startup and
SIGTERM works as it normally would.
olai stops with the program that started it only when that program asked for
it, by setting OLAI_DIE_WITH_PARENT to its own process id before starting
olai. That way a wrapper script can start olai and then exit: olai web … &
from a script that returns, setsid, or a double fork.
Footnotes
-
The page names itself after the computer it runs on:
olai [machine]in the tab title, in the name in the header, and in the name of an installed app. Run olai on a laptop and on a server, and you can tell the two apart wherever you meet them. The name is the computer’s hostname, and setting theOLAI_HOSTNAMEvariable replaces it. ↩ -
New to olai? Start at Set up olai and write your first line. How to stop the server, and what happens when you start a second olai over the same directory, are in the closed blocks at the foot of this page. ↩
-
An outline is a
.olaifile of rows that you can nest under one another. olai reads every outline and every.mddocument in the directory and in the folders under it. It does not look inside folders whose name starts with a dot, or insidenode_modules, so nothing in.gitis served. The directory must already exist:olai webrefuses a path that does not. ↩ -
Save a file in another program, run
git pull, or copy a new outline into the directory, and the open page shows the change straight away. You install nothing in the browser. ↩ -
In a clone of olai’s repository, running
justlists the recipes developers use.just runserves this repository’s own docs on a port the operating system picks.just serve docsdoes the same and also rebuilds the browser code as you edit it. ↩ -
A profile is a named set of plugins to start.
--profile webstarts the browser page, the websocket that updates it and the MCP endpoint agents call.--profile surfaceopens the directory and MCP, with no browser files and no websocket.--profile test-minimalopens the directory and the part that reads its settings, and listens on no port.Which plugins run is not a flag: it is set in the directory’s own settings file,
_olai/Settings.olai(Switch olai's plugins on and off), and so are the git policy and the log level. ↩ -
The home-manager module starts olai with port
7714(Keep olai running in the background). With--port 0, the operating system picks the port, so a restart can land on a different one and you have to read the address off theservingline each time. ↩ -
The dot reports on the connection to the server, on git’s Commit row, and on each running integration, meaning a plugin that reports on another service it talks to. A line with nothing wrong and nothing running, such as
Not a git folderorNo kolu, stays quiet and never colours the dot. The dot’s tooltip, which screen readers also read out, saysStatus: all goodorStatus: <news> · <news>. ↩ -
Click the dot, or press
Tabuntil you reach it and pressEnter. The worst lines come first, red down to quiet, and the last two lines are how long the server has been running and a Plugins row. A plugin that is switched off has no line. On a phone the header has no dot: a banner under the bar carries the news, and the Preferences and Plugins rows sit at the foot of the sidebar drawer. ↩ -
The dot turns amber when writes are waiting to be committed, when a watcher has gone quiet, or when a connection is re-dialling. ↩
-
The card says
Connection lostand thenReconnecting…. Wait, and the page starts working again on its own. The very first connection saysConnecting…instead. ↩ -
The card
The server restarted/Reload the page to keep working.means a reload is the only way on. The cardSomething went wrong on this page/Your files are safe. Reload to try again.offers Reload and Go home, and hides the technical text in a closedDetailsblock. ↩ -
The log says which address the server is listening on, which agents it found on this machine, and anything that went wrong. It also follows a chat: a conversation opening, a prompt sent, a turn that ended or failed, and the agent’s own process starting and stopping. The closed block at the foot of this page says what one line holds. ↩
-
olai rereads both keys while it runs, so you never restart it. Until the directory is open, the server uses the defaults in the table above. You can also edit both in the Server section at the foot of the plugins panel, with the same controls as any other plugin setting (Switch olai's plugins on and off). ↩