Quickstart
This walks you from install to a live server — REST API, dev explorer, and MCP tools — running against the worked example that ships with henosis. It takes a few minutes and needs no external services.
1. Install
henosis is a CLI tool. It requires Python 3.11+. Install it with
uv (or pipx):
uv tool install henosis-engine # then: henosis --help
# or run without installing: uvx henosis-engine --help
Installing from source
To work against the source instead, clone the repo and read henosis as
uv run henosis in the commands below:
git clone https://github.com/henos-io/henosis && cd henosis && uv sync
2. Scaffold an example, then serve it
A henosis project is a directory containing a henosis.yaml. henosis init
writes a full worked example — a synthetic upstream gas operation in the Cooper
Basin — and takes it all the way to runnable, so you can follow along without
authoring anything yet.
# Scaffold ./cooper-basin, generate its data, compile the ontology, sync the graph
henosis init cooper-basin
# Serve the REST API (/v1) + dev explorer, and mount the MCP server at /mcp
henosis serve -p cooper-basin --mcp
What init does, and what you'd run by hand to repeat any step:
| Command | Purpose |
|---|---|
init | Scaffolds an example project, runs its seed script, then compiles and syncs it. --no-seed / --no-compile / --no-sync stop after any step. |
compile | Validates every YAML file and rebuilds the ontology store from it. Rerun it after any model change — there is no migration system; compile drops and recreates. |
sync | Reads the relationship bindings and populates the graph store so traversals resolve. |
serve | Starts the HTTP server. --mcp also mounts MCP tools at /mcp; --stdio serves MCP over stdio only. |
3. Open the explorer
Now open http://127.0.0.1:8000. That's the explorer — a dev UI onto the running model, and the fastest way to see what you just built. Four tabs:
| Tab | What it shows |
|---|---|
| Ontology | Every entity type: its properties, units, allowed values and what each one means, plus a graph of how the types relate. |
| Sources | The systems the model federates, each testable from the page. |
| Query | Every REST endpoint as a form, with the URL it builds — the API without writing any code. |
| Entity | Search across every type, then walk the model: click any relationship to open that entity, see its latest readings, its location on a map, and download its documents. |
Start on Entity, search for Moomba, and click through a well's
relationships — that's the whole model, live, in about a minute of clicking.
The REST API behind all of it lives under /v1, and MCP at /mcp.
Tip
No external services, no clone, and nothing to download — the example generates
its own SQLite and Parquet sources locally, so init runs offline. Most of its
runtime is spent generating the demo's synthetic history.
henosis init --list shows the other examples.
4. Connect an AI agent (MCP)
Run the server with MCP mounted, then point your client at it through
mcp-remote. This is the
recommended setup — it works with any MCP client, and several clients can share
one running server:
henosis serve -p cooper-basin --mcp
{
"mcpServers": {
"henosis": {
"command": "npx",
"args": ["-y", "mcp-remote", "http://127.0.0.1:8000/mcp", "--http"]
}
}
}
Clients that speak Streamable HTTP natively can point at /mcp directly, with
no bridge.
Alternatively, a client can launch henosis as a local subprocess over the
--stdio transport. This needs no running server and no Node, but each client
gets its own instance:
{
"mcpServers": {
"henosis": {
"command": "henosis",
"args": ["serve", "--stdio", "-p", "/abs/path/to/cooper-basin"]
}
}
}
TLS is required beyond localhost
MCP clients and mcp-remote refuse plaintext remote transports — any deployment
reachable off-box must terminate HTTPS in front of /mcp (e.g. a reverse
proxy), or clients won't connect.
The CLI
henosis init <example> # scaffold a worked example, seeded and compiled
henosis validate # validate all resources
henosis compile # build the ontology store from YAML
henosis sync # populate the graph store from relationship bindings
henosis graph # inspect/traverse the graph store
henosis serve # HTTP: REST API (/v1) + explorer; --mcp mounts /mcp
henosis explorer # REST API + explorer only (serve without --mcp)
henosis export --owl # RDF/OWL + SHACL view of the ontology taxonomy
Every command except init takes -p <project-dir> (defaulting to the current
directory). Run henosis --help for the full set.
Next: author your own model
Ready to model your own operation? Head to Ontology & data sources — it covers the project manifest, how to declare connections to the systems you already run, and how an EntityType binds identity, observations, relationships, and documents onto them.