Set up omajot

Try it locally first Optional

You can try the web app on one computer, without Tailscale. This example uses the sample notes from the repository.

$ git clone https://github.com/renerocksai/omajot && cd omajot
$ tools/install-release.sh
$ bin/omajot hub --port 8787 --data /tmp/omajot-demo --no-auth &
$ tools/seed_sample.py --data /tmp/omajot-demo-replica --hub http://127.0.0.1:8787

Open http://127.0.0.1:8787 in your browser. --no-auth turns off the login check. The hub accepts it only on the loopback address.

What you need

• A computer that is always on, for the hub. macOS and Linux work. Windows is experimental. A Mac mini, a home server or a small VPS is a good choice.
• A Tailscale account. Tailscale is free for personal use.
• On macOS: Homebrew. On Linux: Homebrew, or curl and Python 3 for tools/install-release.sh.
• For the plugin: an Omarchy desktop. The plugin is optional: the web app is a complete client.
• No compiler. If you want to build omajot yourself, see Build from source.

Choose your path

Every setup needs the hub (step 1) and Tailscale (step 2). Then choose:

The labels on each section show where it applies: Hub computer Every device Omarchy only Optional

1 · Run the hub Hub computer

The hub stores all changes and sends them to your devices. It also serves the web app. Do these steps on the computer that is always on.

Install omajot. On macOS, use Homebrew. On Linux, use Homebrew or the install script.

Homebrew installs the released binary for this computer. tools/install-release.sh downloads it from the GitHub release and checks its SHA-256 against release.json in the repository. It installs the binary into ~/omajot/bin/omajot and links ~/.local/bin/omajot to it, so omajot works from any folder. It tells you if ~/.local/bin is not on your PATH.

Tell the hub your login. Make the file ~/.config/omajot/config.json, or add the key if the file exists already. Replace you@example.com with your Tailscale login name. The Tailscale admin console shows it on the Users page. The hub accepts API requests only from this login.

{ "hub_login": "you@example.com" }

Start the hub:

$ tmux new -s omajot-hub
$ omajot hub

The hub listens on 127.0.0.1:8787 only. It writes all changes to ~/omajot-data/batches.jsonl and all images to ~/omajot-data/blobs/. Include this folder in your backups. The web app is in the omajot binary. To use other values, add "hub_port" or "hub_data" to the config file, or use the flags --login, --port and --data (see omajot hub).

The tmux line is optional. tmux keeps the hub running when you close the terminal window. You can also use another tool for this, or keep a terminal window open. With Homebrew, you can also start the hub as a service now: see Start the hub at boot.

On Windows (experimental), download omajot-x86_64-windows.exe from the releases. The Windows binary builds on the IOCP backend of bounded/http. We did not run it as a hub yet. If there is no release for your computer, build from source.

$ brew services start omajot
$ tailscale serve --bg --https=8443 http://127.0.0.1:8787

2 · Publish the hub with Tailscale Hub computer Every device

Install Tailscale on the hub computer and on every device that uses omajot: your phone, your laptop, your Omarchy computer. On Omarchy, run omarchy install service tailscale. Log in with the same account on all devices. Then, on the hub computer, run:

$ tailscale serve --bg --https=8443 http://127.0.0.1:8787

Tailscale gives the hub a real HTTPS certificate. Your hub URL is now https://your-mac.your-tailnet.ts.net:8443. The hub prints this URL and a QR code when it starts. Restart the hub after you run tailscale serve, so that it finds the URL. You can also put the URL into ~/.config/omajot/config.json on the hub computer as "hub" (see step 4); the hub then uses it and does not ask Tailscale.

• Enable HTTPS certificates for your tailnet: admin console → DNS → HTTPS Certificates.
• The first HTTPS request can take about 30 seconds, because Tailscale gets the certificate then. Open the URL once with curl.
• Do not use Tailscale Funnel. Funnel makes the hub public on the internet.

3 · Install the plugin Omarchy only

Do this step on your Omarchy computer:

$ omarchy plugin add https://github.com/renerocksai/omajot --enable

When the plugin starts the first time, it runs tools/install-release.sh. The script downloads the omajot binary for this computer, checks its SHA-256 and installs it into bin/omajot. If the plugin folder has a local build in zig-out/bin/omajot, the plugin uses that build. The plugin also puts the omajot command on your PATH: it links ~/.local/bin/omajot to the binary it uses.

A note icon appears in the bar. Click it to open the dropdown. Middle-click it to open the main window.

4 · Tell omajot where your hub is Plugin and CLI

The plugin needs this step. On other computers, do it only if you want to use omajot qr or the note commands there. On the hub computer, it tells the hub its phone URL. Create ~/.config/omajot/config.json, or add the key if the file exists already (on the hub computer, it has hub_login):

{
  "hub": "https://your-mac.your-tailnet.ts.net:8443"
}

The plugin and the command line both read this file. Restart the shell, or change a plugin setting, to reload it. Without a hub, omajot keeps your notes on this computer only. See the config file for all fields.

5 · Open omajot in the browser and on your phone Every device

On a computer: open the hub URL, https://your-mac.your-tailnet.ts.net:8443, in the browser. To install it as an app, use Install app in Chrome or Edge (in the address bar or in the browser menu).

On your phone: use a QR code. You do not type the URL. There are three ways to show the code:

1. The hub

   omajot hub prints its phone URL and a QR code in the terminal when it starts. It finds the URL in tailscale serve status. --url sets the URL. Look at the start output in the tmux session of the hub.

2. omajot qr

   Run omajot qr on any computer where ~/.config/omajot/config.json has your hub.

3. The web app or the plugin

   Open the hub URL once in a desktop browser. Click the phone button in the web app. It shows the address of the page as a QR code. The phone button in the plugin shows the hub URL.

Then point the phone camera at the QR code and open the link. The phone needs Tailscale. It is free for personal use: https://tailscale.com/download. On an iPhone or iPad, tap Share → Add to Home Screen. On Android, tap Install app in the browser menu. The web app then starts like a normal app, also offline.

$ omajot qr
Open omajot on your phone:
  https://your-mac.your-tailnet.ts.net:8443
                                     
                                     
    █▀▀▀▀▀█  ▀█▀ █▀▄   ▀█ █▀▀▀▀▀█    
    █ ███ █ ██▄▀▀▄ ██▄▀▄▀ █ ███ █    
    █ ▀▀▀ █ █▀▄▀ ▀▀▄█ █▀  █ ▀▀▀ █    
    ▀▀▀▀▀▀▀ █ █ █ ▀▄█ ▀▄▀ ▀▀▀▀▀▀▀    
    █▄██▀▀▀ ▄█▄█ ▀▄▀▄█▄▄█▄█▀█▀▀ ▄    
     █▄▀▄█▀▄▄▀▀█  ▀▀▄ ▀ █ ▀ ▄▄ ▄     
    █ ██▄█▀ ▀▀▀▄▄▀▄ ▄█▄▄█▄▄█▄▀▀ ▄    
      ▀█ ▀▀▀▄ ███ ▀▀▄ ▄▄█ ▀██▀▀▄     
    █▄ ▄▄█▀▄█ ▄█▀▀▄  █▄█▄▄▄█▄▀█ ▄    
    █  █▄▄▀▀▀▄██▄▀▄▀▀▀▄ ▀▀ █  ▀▄     
    ▀ ▀   ▀ ▄  ██▄ ▀█▀▄██▀▀▀█▄███    
    █▀▀▀▀▀█ ▄█▄ ██▀█▄  ██ ▀ █▀▀      
    █ ███ █ ██▀  ▄▀▀█▀  █▀▀▀▀▄███    
    █ ▀▀▀ █ ▀█     ▀▄ ▄▀██▀███▀█     
    ▀▀▀▀▀▀▀ ▀▀ ▀▀▀▀  ▀▀   ▀  ▀▀      
                                     
                                     
Your phone needs Tailscale. It is free for personal use:
  https://tailscale.com/download

The plugin and tools/install-release.sh link ~/.local/bin/omajot, so omajot is on your PATH. They never replace a file or a link that is not from omajot. Set OMAJOT_NO_LINK=1 to skip the link.

Without a hub, every QR view shows these steps instead:

Build from source Optional

omajot needs Zig 0.16.0 exactly.

• Omarchy and Arch Linux: run omarchy pkg add zig. Arch ships Zig 0.16.0 today. If Arch has a newer Zig, install 0.16.0 with mise: mise use -g zig@0.16.0.
• macOS: download Zig 0.16.0 from ziglang.org, or use mise: mise use -g zig@0.16.0.

Check the version with zig version. It must show 0.16.0.

For the plugin, build in the plugin folder that omarchy plugin add made. The plugin then uses zig-out/bin/omajot:

$ cd ~/.config/omarchy/plugins/io.github.renerocksai.omajot
$ zig build -Doptimize=ReleaseSafe
$ omarchy restart shell

For the hub, build in your clone and start zig-out/bin/omajot hub … instead of bin/omajot hub ….

Coming from Joplin? Optional

This is only for Joplin users. Skip it if you start fresh. The importer needs Python 3. It reads your Joplin database. It does not change it. It copies all notebooks, notes, tags and images into omajot and keeps the dates of your notes.

Run the importer on the computer that has Joplin, in an omajot folder:

• With the Omarchy plugin: in the plugin folder. omarchy plugin add made it in step 3: ~/.config/omarchy/plugins/io.github.renerocksai.omajot. The plugin has already installed the omajot program there.
• Without the plugin: in your omajot clone, for example ~/omajot from step 1. Run tools/install-release.sh there first.

With the Omarchy plugin:

$ cd ~/.config/omarchy/plugins/io.github.renerocksai.omajot
$ tools/import_joplin.py --dry-run
$ tools/import_joplin.py --data ~/omajot-import

The importer uses your own build (zig-out) if there is one, else the release binary (bin/omajot).

• Start Joplin once and let it sync before you import. Then the database has your latest notes.
• Use a separate --data folder, as shown. The importer then has its own copy. It sends the notes to the hub, and the plugin gets them from there.
• You can run the importer again. It remembers what it imported in ~/omajot-import/import-joplin.json and skips those notes.
• Notebooks become folders. The note title becomes the first line. Joplin tags become #tags on the last line. Images become attachments.

Update the hub Hub computer

With Homebrew:

$ brew upgrade omajot

Without Homebrew, in your omajot clone on the hub computer:

$ cd ~/omajot && git pull
$ tools/install-release.sh

Then restart the hub: in its tmux session, press Ctrl+c and start it again. As a service, use brew services restart omajot, systemctl --user restart omajot-hub or the launchd commands in start at boot. The web app is in the omajot binary, so the browsers and phones get the new web app from the new hub. tools/install-release.sh downloads a binary only if bin/omajot does not match the release in release.json. If you build from source, run zig build -Doptimize=ReleaseSafe instead.

Update the plugin Omarchy only

On your Omarchy computer. The plugin folder is the one that omarchy plugin add made:

$ omarchy plugin update io.github.renerocksai.omajot
$ ~/.config/omarchy/plugins/io.github.renerocksai.omajot/tools/install-release.sh
$ omarchy restart shell