DOCS

A Reference For
Connecting And Operating.

An honest reference for connecting to and operating Verity One — discovery, authentication, the hosted API, releases, and running a local node.

PROTOCOL & DISCOVERY

How agents discover and connect

Verity One is discoverable from a single root. An agent fetches GET / to learn the available surfaces, reads the ontology to understand the graph it is talking to, and follows the descriptor and connect routes to wire itself up.

  • GET / — the discovery root: the entry point that enumerates the live surfaces.
  • /schema — the ontology: the node and edge types that structure the graph.
  • /.well-known/agent — the agent descriptor, advertised at the well-known path.
  • /connect — the connect route: how a client attaches to a node.
  • /toc — a table of contents over the available routes.

Machine readers should start at the /agents page, and can read the plain-text descriptors at /agents.md and /llms.txt.

AUTHENTICATION · OAUTH

The OAuth model

Web agents reach Verity One through an OAuth-bearer flow. verityone.app (the hosted service) is the authorization server, and the protected resource is the connector at verityone.app/mcp. Two scopes are issued: vo.read for reads against the synced mirror, and vo.write.intent for writes — which are queued as intents, not applied live.

The flow is described by the two live well-known documents:

HOSTED REST API

A REST surface, not a transport

The /hosted-mcp/* routes are a hosted REST API, authenticated with a vop_ bearer token. Despite the path name, this is plain request/response REST — it is not an MCP transport. Use it when you want HTTP access to the hosted mirror without speaking the MCP protocol.

The authoritative MCP transport is the local stdio server wired by vo-mcp install; the hosted REST API and the OAuth-bearer connector at verityone.app/mcp both speak to the synced mirror, not to local authority.

RELEASES & CHANNELS

Source-only, in beta

Verity One installs from source and is in beta. There is no packaged or signed binary, and no Homebrew or npm release — the installer clones the repo at a pinned commit and builds a local node on your machine.

STABLE
PINNED · RECOMMENDED
NIGHTLY
AUTO FROM PUBLIC HEAD

The stable channel is canonical and recommended: pinned to an exact commit. The nightly channel auto-publishes the latest public repo HEAD after a private-main run passes its gates — so the pinned install.source_ref is always a commit the source installer can actually check out — and is served from download.verityone.app. The current version is read from the stable manifest — 0.1.2.

  • /download — install from source, with the current release state.
  • /start — the step-by-step onboarding ladder: install, connect, first recall.
RUNNING A NODE · OPERATORS

A local node on your machine

Once built, Verity One runs as a local PostgreSQL-backed node at localhost:3100 — the source of truth, kept close and private on your machine. On-machine agents read and write to it live over the stdio MCP server.

Operators get a local dashboard at 127.0.0.1:3100/dashboard to inspect and operate the node (the dashboard's saved auth is origin-scoped to 127.0.0.1, so use that host — not localhost).

LEGAL