Miyo for headless Linux

Miyo indexes your notes and documents on your own machine so you and your AI agents can search them by meaning. This package runs Miyo's engine on a Linux machine with no desktop, such as a home server, a NAS or a DGX Spark, so your folders stay indexed while your laptop is off.

On macOS and Windows, or on a Linux desktop, install the Miyo app instead. It runs the same engine.

Requirements

• Linux on x64 with glibc 2.35 or newer (Ubuntu 22.04, Debian 12), or on ARM64 with glibc 2.39 or newer (Ubuntu 24.04, Debian 13)
• Node.js 24 or newer
• Room for the embedding model, about 250 MB, which Miyo downloads from Hugging Face the first time it starts

Alpine and other musl systems are not supported, and neither are ARM64 systems on an older glibc, such as Debian 12 and Raspberry Pi OS.

Install

sudo apt install libgomp1
npm install -g --allow-scripts=better-sqlite3 @brevilabs/miyo

The first command installs the GNU OpenMP runtime, which Miyo's embedding engine needs. Ubuntu's server and cloud images leave it out. Without it, indexing never starts and miyo folders reports "Embedding service is not ready". On Fedora and other distributions the package is called libgomp.

--allow-scripts lets the SQLite driver fetch its native binary when it installs. npm is moving to skip install scripts that you haven't allowed, and Miyo can't start without that binary.

For beta releases, install @brevilabs/miyo@beta.

Run it

miyo serve

This runs the engine in your terminal until you press Ctrl-C. To keep it running in the background and start it on boot, install it as a systemd user service:

miyo service install
sudo loginctl enable-linger $USER

The second command lets the service start at boot and keep running after you log out. Check on it with systemctl --user status miyo, and read its log with journalctl --user -u miyo -f. miyo service uninstall stops and removes it.

The service runs the Node binary that ran miyo service install. If you remove that Node version, for example with nvm, run miyo service install again.

Run it in Docker

On a NAS, such as Synology, QNAP or Unraid, or on any machine where you'd rather not install Node, run the image ghcr.io/brevilabs/miyo instead. It works on x64 and ARM64 and brings its own Node and system libraries, so the glibc and Node requirements above don't apply. For beta releases, use the beta tag.

Save this as compose.yaml and change the paths to your own:

services:
  miyo:
    image: ghcr.io/brevilabs/miyo:latest
    container_name: miyo
    restart: unless-stopped
    user: "1026:100"                    # your NAS account's user and group IDs
    stop_grace_period: 30s
    volumes:
      - /volume1/docker/miyo:/data      # Miyo's index, settings and logs
      - /volume1/notes:/folders/notes   # one line for each folder to index

Start it with docker compose up -d, or create a project from the file in your NAS's container app. Then run miyo inside the container:

docker exec miyo miyo folders add /folders/notes
docker exec miyo miyo search "what did I decide about the kitchen renovation"

The folder, search and connection commands below all run this way. An MCP client connects with docker exec -i miyo miyo mcp. Without -i the server gets no input and exits at once.

• Create the data folder before the first start, as the account in user:. If Docker creates it, root owns it and Miyo can't start. To find your IDs, run id on the NAS over SSH. Without a user: line the container runs as 1000:1000.
• That account also needs to read the folders you index, and to write to them if you let AI apps create and edit files.
• Keep the data folder on the NAS's own disks, not on a network share mounted from another machine.
• Miyo picks up changes to your folders as they happen, including files other computers save to the NAS over the network. Linux caps how many folders one account can watch, and some NAS systems set that cap low. If a library has thousands of sub-folders, raise it on the NAS with sudo sysctl fs.inotify.max_user_watches=524288, and run that at boot, for example as a boot-up task in the NAS's task scheduler.
• A NAS processor is slow at the first index. A large library can take hours, and miyo folders shows how far it got.
• The container opens no port. Only commands run inside it can reach Miyo.

To update, run docker compose pull and then docker compose up -d.

Index your folders

miyo folders add ~/notes     # index a folder and keep it indexed as files change
miyo folders                 # list folders and how far indexing got
miyo folders rescan notes    # pick up changes made while Miyo was stopped
miyo folders remove notes    # stop indexing it and delete its index; files stay

Miyo indexes Markdown, text, PDF, EPUB and Word files, and reads scanned PDF pages with OCR.

Search

miyo search "what did I decide about the kitchen renovation"
miyo files --path projects   # list indexed files
miyo parse report.pdf        # print a document as Markdown, no engine needed

Run miyo <command> -h for each command's options.

Use it from AI agents on this machine

The Miyo agent skills teach an agent to search your index with the miyo CLI. For Claude Code:

claude plugin marketplace add Brevilabs/miyo-releases
claude plugin install miyo@miyo-releases

For other agents, the skills CLI installs them:

npx skills add Brevilabs/miyo-releases --skill miyo-search -g

miyo mcp starts an MCP server over stdio. An app connected through it sees only the folders you share with it. The app shows up after its first call, with nothing shared:

miyo connections                         # apps that have called Miyo, and what each can reach
miyo connections share <app> notes       # let the app read the notes folder
miyo connections share <app> notes --write   # let it create and edit files there too
miyo connections unshare <app> notes     # stop sharing it

Use it from Claude or ChatGPT on any device

With a Miyo account that has remote access, Claude.ai and ChatGPT can search this machine's notes through the Miyo relay, from your phone too. The engine has to be running.

miyo login

This prints a code and a link to miyo.md/activate. Open the link on any device, sign in, type the code and approve. The terminal then prints the MCP URL to add to Claude or ChatGPT as a custom connector. When the app first calls, it shows up in miyo connections with nothing shared. Share folders with it as above:

miyo connections share Claude notes

miyo remote       # account, whether remote access is on, the MCP URL, connected apps
miyo remote off   # stop answering remote apps, staying signed in
miyo remote on    # start again
miyo logout       # sign out, which turns remote access off

An account has one remote-access connection. If the Miyo app on another computer already holds it, miyo remote says so. Turn remote access off there, then run miyo remote on.

Use it from your laptop

The engine answers only on the server, and anyone who reaches its API can read and change your indexed files, so don't open its port to the network. Use SSH instead. Run miyo on the server from your laptop:

ssh my-server 'miyo search "what did I decide about the kitchen renovation"'
ssh my-server miyo folders

An AI app on your laptop can start miyo mcp over SSH and use the server's index through MCP. For Claude Code:

claude mcp add miyo-server -- ssh my-server miyo mcp

Like any MCP app, it starts with nothing shared, so its first search comes back empty. After it calls once, run ssh my-server miyo connections to see its name, and share folders with it as above.

Quote the whole command for the server's shell, as above, when it has spaces or quotes of its own. In Docker, put docker exec in front, with -i for MCP: ssh my-nas 'docker exec miyo miyo search "kitchen renovation"' and ssh my-nas docker exec -i miyo miyo mcp.

If the server replies miyo: command not found, your shell sets up Node only when you log in interactively, which is what nvm does. Install Node 24 system-wide instead, for example from NodeSource, so node and miyo are on the system path for every SSH command, MCP included.

Report a problem

miyo report

This packs Miyo's logs from the last 24 hours, lists what it packed, and asks before sending anything. The logs go privately to the Miyo team, and you get a report ID back. Paste the ID into your GitHub issue so we can find the logs. Only the Miyo team can read them. It works signed out, and while the engine is stopped.

In Docker, run docker exec -it miyo miyo report. Without -it it can't ask, so pass --yes to send without asking.

Update

When a newer release is out, miyo commands say so after their output. Miyo checks with npm once a day. To update:

npm install -g --allow-scripts=better-sqlite3 @brevilabs/miyo
systemctl --user restart miyo

On beta releases, install @brevilabs/miyo@beta instead. Don't use npm update -g. It moves you to the latest stable release, which can be older than the beta you're running.

Some updates change the index format. Miyo then pauses indexing, and miyo folders says so. Run miyo index rebuild to rebuild the index from your folders.

In Docker, pull the new image instead, as Run it in Docker describes, and run miyo index rebuild through docker exec when needed.

Where your data lives

Miyo keeps its index, settings and logs in ~/.config/Miyo, or $XDG_CONFIG_HOME/Miyo when that is set. Set MIYO_APP_DATA_DIR to use another folder, and keep it set in your shell: miyo service install passes it on to the service, and the other miyo commands read it too.

The engine listens on 127.0.0.1:8742 and accepts no connections from other machines. Remote access goes out through the Miyo relay instead, and your laptop reaches the engine over SSH, as Use it from your laptop describes.

miyo login stores your sign-in in plain text in relay.json in that folder, readable only by your user. Anyone who can read it can use your account's remote-access connection, so treat it as a secret.

If you add a hosted embedding model with an API key, this package stores the key in plain text in embedding_config.json in that folder, readable only by your user. A headless machine has no OS keychain to encrypt it with, so treat that file as a secret. The desktop app stores the key encrypted instead.

Don't run this package on a machine that also runs the Miyo desktop app. Both use the same data folder, and miyo serve refuses to start while the app's engine is running.