README
¶
The living map of your infrastructure.
Toise is an open-source backend that maintains a live, queryable graph of your infrastructure — hosts, processes, network interfaces, addresses, routes, services, and the relationships between them.
LLM-first. A native Model Context Protocol server lets an AI assistant query the graph on an operator's behalf, in plain language — inventory, topology, dependencies, and what changed. Humans can also query it directly via GraphQL or a built-in debug UI.
OpenTelemetry-native. Toise ingests OTLP entity events from any OpenTelemetry producer — for example senhub-agent, an OpenTelemetry Collector, or your own instrumentation. Toise itself runs no collectors.
Temporal by construction. An event-sourced, bi-temporal log makes history and change first-class: not just "what is the state", but "what changed", "why is this different from yesterday", and "show me the timeline".
Toise ships as a single Apache-2.0 Go binary with no external runtime dependencies — no cluster, no orchestrator. It is the missing inventory-and-topology brick of the modern open-source observability stack (OpenTelemetry, VictoriaMetrics, Grafana, Loki, Tempo).
Why Toise
Modern observability stacks have closed the visibility gap for applications, hosts, containers, and services. The living inventory of the underlying infrastructure — what exists, how it connects, and how it changes over time — remains a blind spot. Toise fills it, designed so an AI assistant can answer an operator's questions about it directly.
Status
Toise is pre-1.0 (alpha), but production-capable as of 0.3.0. It ingests OTLP entity events, maintains a bi-temporal event log and an in-memory graph with change classification, and serves that one read model — scoped per tenant — through three surfaces:
- a GraphQL API (
/graphql, with a playground at/playground), - a native MCP server (
/mcpand stdio) for LLM assistants, and - a minimal debug UI (
/) for operators —
all from a single Go binary with no external runtime dependencies. 0.3.0 adds the
operational surface for real deployments: native bearer-token auth and TLS, a
--production lockdown, /healthz·/readyz·Prometheus /metrics, retention
pruning, projection snapshots, packaged release artifacts, and multi-tenant
isolation.
Pre-1.0, the surfaces can still evolve — but since 0.7.0 the public contracts (the OTLP wire contract, the MCP tools/resources/prompts, and the GraphQL schema) are pinned by a byte-exact conformance fixture and a golden contract test, and governed by a published API stability policy: changes are additive within a release series, and a breaking change ships only with a deprecation notice in the preceding release plus a migration guide. After 1.0 the surfaces follow semantic versioning.
Quickstart
No build needed — a live graph in under a minute. Grab the release tarball for
your platform from the releases page
(it ships toise-server + toise-probe), then run the server and point a probe at
it — toise-probe is a real OTLP/gRPC producer that heartbeats an evolving
topology (process restarts, an interface flap, a container crash, multi-agent
reference counting):
./toise-server --data-dir ./toise-data & # GraphQL + MCP + debug UI on :8080
./toise-probe --producer agent-a # in another terminal
./toise-probe --producer agent-b # a second agent sharing the host/db
# open http://127.0.0.1:8080/
Prefer a container? The server image is on GHCR — then point any OTLP entity-event
producer at :4317:
docker run --rm -p 8080:8080 -p 4317:4317 ghcr.io/toise-dev/toise:latest
From source (for contributors) also builds toise-demo, which seeds a
self-contained "day in the life of web-server-1" scenario — an instant graph with
no producer:
make build # bin/toise-server, toise-demo, toise-probe
./bin/toise-demo --data-dir ./demo-data # seed the demo event log
./bin/toise-server --data-dir ./demo-data # then open http://127.0.0.1:8080/
The demo scenario and a set of example LLM prompts (with the MCP tool calls they
map to) are in docs/demo/.
Security
By default Toise binds to 127.0.0.1 and runs with no authentication — the
trusted-network posture: run it on a private segment or behind a VPN and exposing
it to other hosts is an explicit choice (ADR 0014).
For exposed deployments, 0.3.0 adds opt-in hardening (ADR 0024):
- Bearer-token authentication on the ingest and query surfaces, with tokens
supplied via the environment (
TOISE_AUTH_TOKENS). The operational probes and the metrics scrape stay public. - TLS from a cert/key pair.
--productionto turn off GraphQL introspection, the playground, and the debug UI in one move, plus anallowed_originsWebSocket allowlist.
Multi-tenancy: a single instance serves multiple tenants with fully isolated
graphs, scoped by the X-Scope-OrgID request metadata (or a tenant.id resource
attribute). Authentication is not yet bound to a tenant — a valid token may set any
X-Scope-OrgID — so isolation relies on the upstream OTel Collector authenticating
each client and stamping its tenant. See
Configuration → Multi-tenancy.
Documentation
Design notes, architecture decisions, and roadmap live in the docs/
directory. The public website is at toise.dev.
toise-server is configured by a YAML file, environment variables, or flags —
see Configuring toise-server and the
annotated examples/toise-server.yaml.
The query surfaces are documented in GraphQL API reference (schema, pagination, bi-temporal queries, guardrails) and the MCP tools (ADR 0011).
To deploy, see Deploying toise-server — prebuilt
binaries, the GHCR container image, and the deploy/ examples (systemd,
Docker Compose).
Contributing
See CONTRIBUTING.md and CODE_OF_CONDUCT.md.
License
Apache License 2.0. See LICENSE.
Maintainers
Toise is initiated and primarily maintained by Sensor Factory. Contributions from the broader community are welcome.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
toise-demo
command
Command toise-demo seeds a Toise event log with the phase-1 demonstration fixture — "a day in the life of web-server-1" (see internal/demo and docs/demo/scenario.md).
|
Command toise-demo seeds a Toise event log with the phase-1 demonstration fixture — "a day in the life of web-server-1" (see internal/demo and docs/demo/scenario.md). |
|
toise-probe
command
Command toise-probe is a real OTLP/gRPC producer for demos and end-to-end testing.
|
Command toise-probe is a real OTLP/gRPC producer for demos and end-to-end testing. |
|
toise-server
command
Command toise-server is the main entry point for the Toise server.
|
Command toise-server is the main entry point for the Toise server. |
|
examples
|
|
|
producer-docker
command
Command producer-docker turns the local Docker state into Toise entities: one "container" entity per running container, the host they run on, and a runs_on edge.
|
Command producer-docker turns the local Docker state into Toise entities: one "container" entity per running container, the host they run on, and a runs_on edge. |
|
producer-minimal
command
Command producer-minimal is the smallest useful Toise producer: it emits a host and a service.listener that runs on it, keeps them alive on a heartbeat, and deletes them on Ctrl-C. It uses only the built-in entity vocabulary, so it works against a stock toise-server with no extra flags.
|
Command producer-minimal is the smallest useful Toise producer: it emits a host and a service.listener that runs on it, keeps them alive on a heartbeat, and deletes them on Ctrl-C. It uses only the built-in entity vocabulary, so it works against a stock toise-server with no extra flags. |
|
producer-systemd
command
Command producer-systemd maps systemd service units to Toise entities: one "service" per unit (identity {host.id, service.name}, descriptive active_state and sub_state), the host, and a runs_on edge.
|
Command producer-systemd maps systemd service units to Toise entities: one "service" per unit (identity {host.id, service.name}, descriptive active_state and sub_state), the host, and a runs_on edge. |
|
producer-uptime
command
Command producer-uptime probes a list of URLs on an interval and emits each as a Toise entity whose descriptive state (up, status code, latency) flips as the site goes up or down.
|
Command producer-uptime probes a list of URLs on an interval and emits each as a Toise entity whose descriptive state (up, status code, latency) flips as the site goes up or down. |
|
internal
|
|
|
annotations
Package annotations is the operator-added overlay on entities: free-form key/value notes a human or an assistant attaches to an entity (owner, runbook link, ticket, a remark).
|
Package annotations is the operator-added overlay on entities: free-form key/value notes a human or an assistant attaches to an entity (owner, runbook link, ticket, a remark). |
|
audit
Package audit records security-relevant operations — today the operator writes (annotate_entity) — to an append-only, exportable JSON-line stream, distinct from the producer event log (ADR 0028).
|
Package audit records security-relevant operations — today the operator writes (annotate_entity) — to an append-only, exportable JSON-line stream, distinct from the producer event log (ADR 0028). |
|
auth
Package auth provides optional bearer-token authentication for Toise's data surfaces — the HTTP query surfaces (GraphQL, MCP, debug UI) and the OTLP/gRPC ingest.
|
Package auth provides optional bearer-token authentication for Toise's data surfaces — the HTTP query surfaces (GraphQL, MCP, debug UI) and the OTLP/gRPC ingest. |
|
canonical
Package canonical holds the read-time identity overlay of ADR 0020: the walk over producer-asserted same_as belief edges that says which entities are believed to be the same real thing.
|
Package canonical holds the read-time identity overlay of ADR 0020: the walk over producer-asserted same_as belief edges that says which entities are believed to be the same real thing. |
|
change
Package change is Toise's change-detection engine.
|
Package change is Toise's change-detection engine. |
|
config
Package config resolves the toise-server configuration from layered sources.
|
Package config resolves the toise-server configuration from layered sources. |
|
debugui
Package debugui serves a minimal, server-rendered HTML view over Toise's read model — the same in-memory projection (current state) and event log (history) the GraphQL and MCP surfaces use.
|
Package debugui serves a minimal, server-rendered HTML view over Toise's read model — the same in-memory projection (current state) and event log (history) the GraphQL and MCP surfaces use. |
|
demo
Package demo builds the phase-1 demonstration fixture: "a day in the life of web-server-1", a 24-hour simulated evolution of one host's infrastructure.
|
Package demo builds the phase-1 demonstration fixture: "a day in the life of web-server-1", a 24-hour simulated evolution of one host's infrastructure. |
|
graphql
Package graphql wires the gqlgen executable schema, resolvers, transports, and guardrails into an http.Handler.
|
Package graphql wires the gqlgen executable schema, resolvers, transports, and guardrails into an http.Handler. |
|
graphql/resolvers
Package resolvers implements the gqlgen ResolverRoot, backing the GraphQL API with the in-memory projection (current state) and the event log (history).
|
Package resolvers implements the gqlgen ResolverRoot, backing the GraphQL API with the in-memory projection (current state) and the event log (history). |
|
ingest
Package ingest accepts OpenTelemetry entity events over OTLP/gRPC and routes them to the change-detection engine (see ADR 0009).
|
Package ingest accepts OpenTelemetry entity events over OTLP/gRPC and routes them to the change-detection engine (see ADR 0009). |
|
logship
Package logship ships immutable event-log segments off-node on a cadence — the continuous, finer-RPO complement to the cold checkpoint backup (ADR 0029).
|
Package logship ships immutable event-log segments off-node on a cadence — the continuous, finer-RPO complement to the cold checkpoint backup (ADR 0029). |
|
mcp
Package mcp exposes Toise as a Model Context Protocol server, built on the official Go SDK (github.com/modelcontextprotocol/go-sdk).
|
Package mcp exposes Toise as a Model Context Protocol server, built on the official Go SDK (github.com/modelcontextprotocol/go-sdk). |
|
metrics
Package metrics exposes Toise's internals as Prometheus metrics at /metrics.
|
Package metrics exposes Toise's internals as Prometheus metrics at /metrics. |
|
model
Package model defines Toise's domain types: entities, relations, the typed attribute Value, and the bi-temporal, classified events that flow through the system.
|
Package model defines Toise's domain types: entities, relations, the typed attribute Value, and the bi-temporal, classified events that flow through the system. |
|
oidc
Package oidc verifies OIDC/JWT bearer tokens on Toise's read surfaces and maps their claims to a tenant id and an access role (ADR 0028).
|
Package oidc verifies OIDC/JWT bearer tokens on Toise's read surfaces and maps their claims to a tenant id and an access role (ADR 0028). |
|
ops
Package ops provides the operational HTTP endpoints — liveness and readiness probes — that orchestrators and uptime monitors target directly, so a deployment no longer needs a synthetic httpcheck against a UI page.
|
Package ops provides the operational HTTP endpoints — liveness and readiness probes — that orchestrators and uptime monitors target directly, so a deployment no longer needs a synthetic httpcheck against a UI page. |
|
projection
Package projection maintains Toise's live graph as an in-memory projection of the event log (see ADR 0008).
|
Package projection maintains Toise's live graph as an in-memory projection of the event log (see ADR 0008). |
|
registry
Package registry holds one independent {store, projection, change-engine} stack per tenant, so a single Toise process serves multiple tenants with physically isolated graphs (ADR 0025, #95).
|
Package registry holds one independent {store, projection, change-engine} stack per tenant, so a single Toise process serves multiple tenants with physically isolated graphs (ADR 0025, #95). |
|
store
Package store implements Toise's durable, append-only event log on top of Pebble (see ADR 0007).
|
Package store implements Toise's durable, append-only event log on top of Pebble (see ADR 0007). |
|
tenant
Package tenant resolves and carries a generic, vendor-neutral tenant id so the graph can be scoped per tenant (ADR 0025).
|
Package tenant resolves and carries a generic, vendor-neutral tenant id so the graph can be scoped per tenant (ADR 0025). |
|
version
Package version exposes build-time version information for the Toise server.
|
Package version exposes build-time version information for the Toise server. |
|
pkg
|
|
|
emit
module
|
|
|
proto
|
|