Using a hosted instance

FractalEngine works without any hosted service: the database is local and peers sync directly. Three optional pieces can be hosted, and this page covers each: a package registry, relays for peer-to-peer traffic, and the API.

The package registry

A registry is a small web service that lists and serves signed .hexon packages: map tilesets and, through the API, other package types. A public one runs at:

https://hexon-registry-production.up.railway.app

Anyone can search and download. Publishing needs a token that only the operator holds. Packages are signed, and the desktop app checks them before installing. The status page shows whether the registry is reachable and lists what it currently holds.

In the desktop app

Open the Hexon Manager. Registry packages are listed there and install with one action. Today the Hexon Manager lists terrain tilesets only; other package types are reachable through the API below.

The registry address comes from, in order of priority: the FE_HEXON_REGISTRY_URL environment variable, the Map registry setting, then the built-in default. In builds made after 2026-11-14 the default is the public registry above. Earlier builds have no default and need the setting.

# point the app at a different registry for this run
FE_HEXON_REGISTRY_URL=https://registry.example.com ./fractalengine

From a script

# list everything; optional filters: q (text), tags (comma separated), type
curl https://hexon-registry-production.up.railway.app/api/v1/hexons/search
curl "https://hexon-registry-production.up.railway.app/api/v1/hexons/search?q=terrain"

# download one package: {id}@{version}
curl -O -J https://hexon-registry-production.up.railway.app/api/v1/hexons/alpine-demo-terrain@0.1.0/download

Every response carries an x-hexon-registry-protocol header with the protocol version. Search answers {"ok":true,"data":[...]}, where each entry has hexon_id, version, hexon_type, name, description, tags, publisher_did, size_bytes, content_hash and sealed.

Relays

Peers find and talk to each other through iroh relays, which also help them connect across firewalls.

By default the app uses the public relays run by n0, the iroh developers. They are shared and rate-limited, which is fine for a trial and not for production. All peers of a swarm need builds on the same iroh generation (iroh 1.x); older peers cannot talk to newer ones.

Set the relay with an environment variable or in the app under Settings, Network. The variable wins if both are set.

`FE_SYNC_RELAY` value	Effect
`default` (unset)	n0’s public relays
`disabled`	no relay: peers on the same network only
`https://relay.example.com`	your own iroh relay; separate several with commas

For a deployment, run your own iroh 1.x relay and point FE_SYNC_RELAY at it. A separate headless FractalEngine node, fe-relay, ships beside the desktop app and can host verses around the clock; its runbook also covers pointing sync at your own iroh relay: relay-operations.md.

A members-only relay from the desktop app

The desktop app can also act as a relay for the verses it created. It then admits only people who hold a role of Viewer or above in those verses, and nobody else. It is off by default, because it turns your machine into a listener for verse traffic. It starts only after you consent and a reachability self-test passes, and it needs a build that includes the relay-server feature. The project documentation does not say whether the preview download includes that feature; if the setting is missing from your build, build from source.

The local API and tokens

The desktop app serves REST, WebSocket and MCP on 127.0.0.1:8765, reachable from the same computer only. The headless relay binary serves the same API on a configurable address, 0.0.0.0:8765 by default. See API overview for examples.

Every call except health and readiness checks needs a bearer token. A token is scoped to a verse, a fractal or a petal, and carries a role at that scope:

Role	Can
Viewer	read
Editor	read and change scene content
Manager	also manage roles at the scope
Owner	everything, including the most sensitive operations

A token can never do more than its role allows at its scope, and a request outside the scope is answered as if the thing did not exist.

Where tokens come from:

In the app: the API tab mints scoped tokens. Pick the scope and role, and copy the token.
For a local agent: set FE_API_DEV_TOKEN_OUT to a file path. The app writes loopback-only tokens for every local verse there (Owner where this machine owns the verse, valid for 8 hours).
For a headless relay: the repository ships a token-minting example, described in bi-egress.md.

Some capabilities are off unless you opt in with an environment variable. For example, FE_API_INPUT_ALLOW=1 enables synthetic input and UI inspection tools, and FE_API_SCREENSHOT_ALLOW=0 turns the agent screenshot surface off. The full list is in the README.

The MCP tool list is not published as a document: ask the server. tools/list (shown in the API overview) returns every tool the host offers, and the set differs between the desktop app and the headless relay.