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 # then: henosis --help
# or run without installing: uvx henosis --help
Installing from source
Not yet on PyPI. Until the first release, install from source 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
Open http://127.0.0.1:8000 for the explorer — a dev UI onto the model with
Ontology, Sources, Query, and Graph tabs. The REST API lives under /v1.
Tip
No external services, no clone, and nothing to download — the example generates
its own SQLite and Parquet sources locally, so init runs offline in about ten
seconds. henosis init --list shows the other examples.
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. Connect an AI agent (MCP)
Most MCP clients (Claude Desktop, Claude Code, …) speak stdio, so they can't
point at an HTTP URL directly. The simplest setup lets the client launch henosis
as a local subprocess with the --stdio transport:
{
"mcpServers": {
"henosis": {
"command": "henosis",
"args": ["serve", "--stdio", "-p", "/abs/path/to/cooper-basin"]
}
}
}
To share one already-running server instead, run henosis serve --mcp (which
mounts Streamable HTTP at /mcp) and bridge stdio↔HTTP with
mcp-remote:
{
"mcpServers": {
"henosis": {
"command": "npx",
"args": ["-y", "mcp-remote", "http://127.0.0.1:8000/mcp"]
}
}
}
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.