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:
- The path in the
MACHINE_ROOTenvironment variable (if set and the file exists) ./machine-root.json(current working directory)~/machine-root.json(user home directory)- 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- nomachine-root.jsoncould be foundMachineRootKeyError- 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.
Metadata
Release files for machine-root 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| machine_root-0.1.0.tar.gz | 5.8 kB | Without provenance | Details for machine_root-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| machine_root-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for machine_root-0.1.0-py3-none-any.whl |
Total release size: 11.3 kB
Release files / machine_root-0.1.0.tar.gz
| Download URL | machine_root-0.1.0.tar.gz |
|---|---|
| Size | 5.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
2ba80f6ba6e1cce3a070e0923af5da26d4e96c7b9ced75c5d56edaae551f5fcd
|
|
BLAKE2b-256 checksum How to use checksums |
f5855346a979e8677f4cba842aa6a497b9950f492978f9d86b3872186e31add1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.7
|
Release files / machine_root-0.1.0-py3-none-any.whl
| Download URL | machine_root-0.1.0-py3-none-any.whl |
|---|---|
| Size | 5.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
f39808b57b4595d6ce2bd42ea5dabc6ebfbee537fbe8486ce9b3988f4577a96f
|
|
BLAKE2b-256 checksum How to use checksums |
dfba96b9f89a3c2916b9c05b40edbb2d18ca81dbb9937db9aaf17817d46292a4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.7
|
Security for machine-root 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.