miyodocs← Home

Run miyo on a server

Headless miyo runs on a machine with no screen, such as a NAS, a Linux box at home or a VPS, so your folders stay searchable while your laptop is off. It is the same engine as the desktop app, driven from the terminal.

On a Mac mini or any computer with a desktop, install the app instead.

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 the first time it starts

Alpine and other musl systems aren't supported, and neither are ARM64 systems on an older glibc, such as Debian 12 and Raspberry Pi OS. On those, and on a NAS, run it in Docker.

Install with npm

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

The first command installs a runtime library miyo's embedding engine needs. Ubuntu's server and cloud images leave it out, and without it indexing never starts. On Fedora and other distributions the package is called libgomp.

Then install miyo as a service, so it runs in the background and starts on boot:

miyo service install
sudo loginctl enable-linger $USER

The second command keeps the service running after you log out of SSH.

On a NAS, run it in Docker

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

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 IDs (run id)
    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.

  • 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. Run id on the NAS over SSH to find your IDs.
  • 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.
  • If a library has thousands of sub-folders, raise the NAS's limit on watched folders with sudo sysctl fs.inotify.max_user_watches=524288, and run it at boot from the NAS's task scheduler.

Every miyo command on this page runs inside the container. Put docker exec miyo in front of it, as in docker exec miyo miyo folders add /folders/notes.

Add 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 indexes Markdown, text, PDF, EPUB and Word files, and reads scanned PDF pages. It picks up changes as they happen, including files other computers save to the server. A NAS or a small VPS is slow at the first index, so a large library can take hours.

Connect Claude and ChatGPT

With remote access, Claude and ChatGPT reach the server through the miyo relay, on the web and on your phone. Nothing on your network has to accept connections.

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. If you haven't tried remote access yet, miyo.md offers the 7-day free trial there, with no card. The terminal then prints your MCP URL. Add miyo to Claude and ChatGPT as in Getting Started, using that URL.

Each app starts with no folders. After it first calls miyo, share a folder with it:

miyo connections                          # apps that have called miyo, and what each can reach
miyo connections share Claude notes       # let Claude read the notes folder
miyo connections share Claude notes --write   # let it create and edit files there too

An account has one remote-access connection. If the desktop app on another computer holds it, turn remote access off there, then run miyo remote on on the server. miyo remote shows where things stand, and miyo logout signs out.

Use it from your laptop

Don't open miyo's port to the network: anyone who reaches it can read your indexed files. Use SSH instead, which needs no account:

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

The second command gives Claude Code on your laptop the server's index over MCP. In Docker, use ssh my-nas docker exec -i miyo miyo mcp.

Use it from agents on the server

The miyo agent skills teach Claude Code and other agents to search your index with the miyo command. For Claude Code:

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

For other agents:

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

Update

miyo commands tell you when a newer release is out. With npm:

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

In Docker, run docker compose pull, then docker compose up -d.

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

What leaves your server

miyo listens only on the machine it runs on, so nothing on your network or the internet can connect to it. It sends data out only in these cases:

  • On first start, it downloads the embedding model, about 250 MB, from Hugging Face, or from its mirror at hf-mirror.com if that fails. If you pick a hosted embedding model instead, your text goes to that provider.
  • When you run a miyo command, the CLI asks npm whether a newer release is out, at most once a day.
  • With remote access on, the server stays connected to the relay and renews its sign-in with miyo.md. Each request from Claude or ChatGPT, and miyo's answer, travel through the relay's encrypted tunnel. We keep connection times and daily tool-call counts, never file names, queries or file content.
  • When you run miyo report, miyo asks you to confirm, then sends us your logs.

The engine sends no usage analytics. The privacy policy has the rest.

What's next