toise

module

v0.10.0 Latest Latest Go to latest Published: Jul 30, 2026 License: Apache-2.0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/toise-dev/toise

Links

Open Source Insights

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 (/mcp and 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.
--production to turn off GraphQL introspection, the playground, and the debug UI in one move, plus an allowed_origins WebSocket 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 ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

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.
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/generated
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
toise/v1