Ymer Node

Ymer Node is the local half of Ymer: a headless MCP server you run on your own machine, giving an LLM that works with you capability that has to live where you are. Today that is a notebook — a private SQL store with vector search, which the LLM creates its own tables in — and a registry of references to where knowledge lives. Neither leaves this machine.

The other half is ymer, the hosted side, which holds the tasks, projects and documents any client can reach from anywhere. Neither replaces the other, and the split is deliberate: things worth having on every device belong there, and things that belong to this machine belong here. A node keeps working whether or not anything else is reachable.

Requirements are real

Running it

Build the image in this checkout:

mise exec -- mix deps.get

mise exec -- mix ymer_node.build

Then make the install: copy docker-compose.yml into the directory you have chosen for it, and bring the node up there:

docker compose up -d

The build task tags the image it produces ymer-node:<version>, ymer-node:latest and ymer-node:<revision> — the last naming the commit it was built from. The compose file runs ymer-node:latest and never builds it, so an up here cannot pick up code you did not build; what does move that tag is written where the tag is moved, in Mix.Tasks.YmerNode.Build's moduledoc. Without Elixir, docker build -t ymer-node:latest . builds the same image minus the version and revision tags.

To deploy new code, run mise exec -- mix ymer_node.deploy with the install's container stopped (docker compose stop there; the deploy refuses while it runs). It builds this checkout's committed main, carries the compose file into the install, recreates the container on the new image, and does not report success until the node answers on that image. The store is untouched.

Each deploy also points ymer-node:previous at the revision the install was running before it, so going back is two commands in the install and no sha to look up:

docker tag ymer-node:previous ymer-node:latest

docker compose up -d

The deploy says what previous ended up naming, or why it named nothing — the first deploy onto an install built before revisions has no label to read.

The node then serves MCP at http://127.0.0.1:8012/mcp. Its store lives in data/, beside the compose file.

Point your MCP client at that URL. For Claude Code:

claude mcp add --transport http ymer-node http://127.0.0.1:8012/mcp

For Claude Desktop — and for Cowork, which reads the same file — add it to the mcpServers object in claude_desktop_config.json:

"ymer-node": {

  "type": "http",

  "url": "http://127.0.0.1:8012/mcp"

}

Set script_author to ask before it runs. Of the tools the node serves, it is the one that decides what code this machine will run: storing a script accepts it, and the node will run those bytes with its own permissions until someone changes or removes them. A run is isolated from crashes and loops, and it is not sandboxed — so the question worth your attention is not what a script does but whether you meant to accept it. The other tools reach nothing but this machine's own store and the scripts you already accepted.

The operator's verbs run on the machine itself, and are the door for anything that should not travel through a model's context:

docker exec -i <container> /app/bin/ymer-node scripts list

docker exec -i <container> /app/bin/ymer-node scripts push < /path/to/script.exs

printf 'the-value' | docker exec -i <container> /app/bin/ymer-node secrets set NAME

docker exec -i <container> /app/bin/ymer-node throttles list

A secret's value is read from stdin and never taken as an argument: an argument is visible in ps to every user on the machine, and in your shell's history to you. A pushed script arrives on stdin the same way; scripts push <file> takes a path inside the node's own filesystem instead. The -i is load-bearing for both: without it nothing arrives, and the verb says so. ymer-node help lists every verb.

A script may send its requests through a throttle it declares, which the node starts the first time a request names it. When a run is refused because a throttle's breaker is open — the system behind it answered 401 too many times in a row — throttles list shows every throttle's state, and once the cause is fixed, throttles reset <name> closes the breaker. The reset is this machine's alone: no session can reach it.

TZ in a .env beside the install's compose file sets the node's time zone — an IANA name such as Europe/Helsinki, applied with docker compose up -d there, and what every script reads through YmerNode.Script.Context.time_zone/1; unset, the node runs in Etc/UTC, and a name the node does not know refuses boot, so the node never starts serving and the refusal, naming TZ and the value, is read with docker compose logs rather than through an operator's verb, each of which is a call into a serving node.

Store and backup layout

Inside that directory the store is data/db/notebook.db, and each backup the node takes is one file, data/backups/notebook-<id>.db. The backups directory is also how a kept notebook comes back into an install: put the file there under that name, then call the notebook tool's restore with its id. The node backs up the current store before it swaps, so the step itself can be undone.

Beside the store sits data/db/node.db, the node database — the registry the references tool serves. It is migrated at every boot and never backed up: delete it and the next boot recreates it, empty and current, which is why the backups above are the store's alone. One thing to know while registry sync is still to come: a reference you add lives only on this machine, so node.db holds the only copy of it. DATABASES_PATH names the directory both files sit in — /data/db in the compose file — and the file names inside it are fixed.

Beside both sits data/files/, the files directory — the one place a file crosses between you and a script. Drop a file there, or have Cowork or Claude Code drop it, and a script reads it; what a script writes there, you open. Arrange sub-directories as you like: a script reaches the directory through YmerNode.Script.Context.files_dir/1 and File, never a path of its own, so the same script works on every node. FILES_PATH names it in the compose file as DATABASES_PATH names the databases' directory, /data/files, and it stays inside the mount. The files are yours, not the node's: it creates the directory at boot and never backs it up.

On a brand-new store the node's first boot logs database is locked once while its connections race each other to put the fresh file into WAL mode. It is expected, it is over in milliseconds, and nothing is lost. A restore does not produce it: the node switches the restored copy to the journal mode the pool is configured for before the pool ever sees it.

That address is not a default — it is the security model. /mcp carries no authentication, and not being reachable from the network is the whole compensating control, which is why the published port is hardcoded to 127.0.0.1. Do not widen it without putting authentication in front of it first.

Writing a script

A script is a small Elixir module the node compiles and runs — how it reaches a system it has no built-in support for. Your session writes it: tell it to read scripts guide first, which renders the script contract and the functions a script is handed from the node's own docs — and scripts info <name> for a package the guide promises, which renders that package's own docs from the release at the version it carries — and to check the code with script_author before it creates anything. Published, the same text — less the list of applications the guide ends with, which the node computes — is the YmerNode.Script and YmerNode.Script.Context pages of the docs, which mix docs builds here. Keep script_author set to ask, as Running it says: what it creates, the node runs. What a script can reach beyond that contract — the standard library, a library, a service, the batteries the node plans — and the test that decides when the node itself grows are mapped in Scripts — batteries and their boundary.

A secret a script declares is set on this machine, by you, under the name the script declares — never through the session: the secrets set line under Running it, with that name.

Sharing a script is sharing its code. From a session, scripts describe with code: true answers the code, to be saved to a file; on the machine, scripts export <name> prints exactly the bytes the node holds and scripts push reads them back, so the pair moves a script between nodes unchanged. In the compose install the container is <project>-ymer-node-1, the project being the install directory's name unless COMPOSE_PROJECT_NAME says otherwise — docker ps shows it:

# on the sending machine

docker exec <container> /app/bin/ymer-node scripts export hex > hex.exs

# on the receiving one, with hex.exs carried across

docker exec -i <container> /app/bin/ymer-node scripts push < hex.exs

A release run on the host rather than in the image has the same verbs at bin/ymer-node:

bin/ymer-node scripts export hex > hex.exs   # sending machine

bin/ymer-node scripts push < hex.exs         # receiving one

The two halves are two machines. Pushing an exported script back into the node it came from is a write like any other: it re-lands the row through the push door, so a script the build planted stops reading as the build's.

On the receiving node the session checks the code and creates it — acceptance is that node's own — and whoever runs that machine sets the secrets it declares. The example script the image ships, hex, is already there on a fresh install, to be read as much as run; remove it and it stays gone.

Developing it

mise exec -- mix deps.get

mise exec -- mix test

mise exec -- mix precommit

precommit is the gate: compile with warnings as errors, format, Credo, a dependency audit, and the test suite.

A fresh clone with no sibling checkouts must build and pass that gate on its own. That is a standing requirement rather than a happy accident — if you find yourself reaching for a neighbouring directory to make something work, the fix belongs in this repository.

To smoke-test the compose file against this checkout's build, run it here under a project name and a port of its own, so it never collides with the install:

mise exec -- mix ymer_node.build

PORT=4013 docker compose -p ymer-node-smoke up -d

docker compose -p ymer-node-smoke down

Between up and down the node answers at http://127.0.0.1:4013/mcp — that address, not the 8012 of "Running it", where the node you keep may be answering and would pass for this build. 4013 is the test port config/test.exs reserves and leaves unbound.

Where to look next