machine-root

The Problem

Programs, scripts, and AIs that run on a machine often need to locate resources - a project folder, a service registry, a configuration file. The usual solutions are fragile: hard-coded paths break when things move, environment variables require manual setup, and configuration systems are overkill for something this simple.

The System

Machine Root is a minimal, shared registry for a local machine. It is a single JSON file - machine-root.json - that maps string keys to locations (typically filesystem paths):

{
  "zoo.projects": "C:/lion/zoo/projects",
  "filetalk.registry": "C:/lion/filetalk/service-registry.json",
  "librarian.main": "C:/lion/librarian/registry.json"
}

Any program that knows the convention can read from the same registry. Keys are stable names; values are locations that can change. No metadata, no nesting, no configuration framework required.

Resolution Order

When looking for machine-root.json, the system checks these locations in order and uses the first one found:

1. The path in the MACHINE_ROOT environment variable (if set and the file exists)
2. ./machine-root.json (current working directory)
3. ~/machine-root.json (user home directory)
4. Machine-level: C:/machine-root.json (Windows) or /etc/machine-root.json (Linux)

If none are found, operations fail clearly.

The Package

machine-root is a Python package that implements the Machine Root system. It provides a minimal API and a command-line tool for reading and writing the registry.

Install

pip install machine-root

Python API

import machineroot

machineroot.locate()           # path to the active machine-root.json
machineroot.keys()             # list all keys
machineroot.get("zoo.projects")           # get a value
machineroot.set("zoo.projects", "C:/lion/zoo/projects")  # set a value
machineroot.delete("zoo.projects")        # delete a key

Errors:

• MachineRootNotFoundError - no machine-root.json could be found
• MachineRootKeyError - the requested key does not exist

CLI

machine-root create
machine-root set zoo.projects C:/lion/zoo/projects
machine-root get zoo.projects
machine-root delete zoo.projects
machine-root keys
machine-root locate
machine-root help

The registry file must be created explicitly with machine-root create, which places it in the user's home directory. All other commands fail if the file does not exist.

License

CC0-1.0 - public domain.