Stellar Jay

Agent setup

Give an agent safe write access with the MCP server. Every change is kept and
attributed to the agent that made it, and any change can be undone.

{
  "mcpServers": {
    "aviansuite": {
      "command": "stellarjay-mcp",
      "env": {"STELLARJAY_URL": "https://store.example.com", "STELLARJAY_TOKEN": "writer-token"}
    }
  }
}

Install it with go install github.com/kyle-visner/stellarjay/cmd/stellarjay-mcp@latest.
Hosted on AvianSuite, use the remote server https://mcp.aviansuite.com/mcp
instead. Tools and details: docs/mcp.md.

TL;DR

Stellar Jay is an append-only fact store for AI agents trusted with critical
business data. Agents can add flexible JSON facts, but the hosted API cannot
rewrite or delete history. Every write is attributed, encrypted, safe to retry,
checked for stale state, and available for replay.

Requires Go 1.22 or later:

git clone https://github.com/kyle-visner/stellarjay.git
cd stellarjay
go install ./cmd/stellarjay-server
stellarjay-server init ./secrets

The initializer prints reader, writer, and admin tokens once. Save them in a
password manager, then continue to Run Stellar Jay.

Who Stellar Jay is for

Stellar Jay is for developers and small teams moving from read-only copilots to
agents that are allowed to operate. It fits accounting, operations, compliance,
approvals, and other work where agents write critical data, mistakes must stay
visible and correctable, and fact shapes evolve with the job.

Stellar Jay is designed for single-tenant systems: one organization, one trust
boundary, and one writer process per store. Many agents and applications can
share that store, including dashboards, internal tools, APIs, and automated
workflows. Stellar Jay is not meant to be the globally distributed, multi-tenant
backend for a web application.

Why Stellar Jay exists

Traditional databases assume deterministic application code owns every read and
write. Agents make judgment calls, retry uncertain work, and sometimes behave in
unexpected ways—at machine speed. A mutable database can turn one bad decision,
runaway loop, or malicious instruction into lost source data before anyone
notices.

You can build these protections around a general-purpose database. Stellar Jay makes
them part of every write instead of leaving them to each application.

Stellar Jay does not decide whether a fact is true. An authorized agent can still
write a bad fact; Stellar Jay keeps that action visible and correctable.

How it works

Stellar Jay stores a linear chain of events. Each event records what happened, who
did it, an encrypted JSON payload, and the event before it. Payloads stay
flexible; the history rules do not.

The normal write flow is:

1. Read the current root.
2. Submit a fact with that expected_root and a stable Idempotency-Key.
3. Stellar Jay derives the actor, encrypts and hashes the event, writes it, and
   advances the root.
4. Identical retries return the original event. Stale roots and reused keys with
   different content return 409 conflict.

Each event address depends on the event before it. Changing old content changes
the hashes that follow, so an off-host copy of the root can detect rewritten or
replaced history.

Corrections, retractions, and approvals are new events, never edits. The hosted
API has no update or delete path for history, and callers cannot choose their own
identity. One writer process serializes writes for each data volume; many agents
can use that process, but Stellar Jay is not a distributed consensus system.

Run Stellar Jay

Deploy the hosted service

Prerequisites: a Linux host with Docker Compose, ports 80 and 443 reachable, and
an A/AAAA record pointing a domain at the host.

cp .env.example .env
# Edit .env and set STELLARJAY_DOMAIN.

stellarjay-server init ./secrets

docker compose up -d --build
docker compose ps
curl https://stellarjay.example.com/health/ready
curl https://stellarjay.example.com/llm.txt

The origin is the website. / links to /llm.txt, which is the agent setup contract (CLI + STELLARJAY_URL / STELLARJAY_TOKEN, not per-app MCP).

The initializer will not replace existing secrets. The server requires an
external data key and hashed credential file.

Append a fact

Fetch the current root first:

export STELLARJAY_URL=https://stellarjay.example.com
export STELLARJAY_TOKEN='the-writer-token'

curl -fsS \
  -H "Authorization: Bearer $STELLARJAY_TOKEN" \
  "$STELLARJAY_URL/v1/root"

Use the returned root as expected_root and choose one stable idempotency key
for the logical operation. Use an empty string only for the first event in a new
database.

curl -fsS -X POST "$STELLARJAY_URL/v1/events" \
  -H "Authorization: Bearer $STELLARJAY_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: fact-primary-contact-v1-7f3d2a" \
  --data '{
    "type": "business.fact",
    "entity_id": "01JOPAQUE8F3K2M7Q9R4T6V1WX",
    "command": "fact assert",
    "payload": {"primary_contact": "Ada Lovelace"},
    "expected_root": "sha256:root-from-the-previous-response"
  }'

See the API guide for metadata-first replay, selective bounded
payload reads, stable-root pagination, refs, snapshots, and administrative
endpoints.

Use the embedded Go library

store, err := stellarjay.OpenStore(".stellarjay")
if err != nil { /* handle error */ }
defer store.Close()
root, err := store.Append(stellarjay.Context{Actor: "agent"}, stellarjay.AppendOptions{
    Type: "business.fact", Command: "fact assert", Payload: fact,
})

OpenStore is a local-development convenience that co-locates the key and data.
Production processes must use OpenStoreWithDataKey; the server enforces this.

Production boundaries

• One process owns each writable data volume.
• Caddy handles HTTPS; bearer credentials provide reader, writer, or admin
  access. An optional operator role manages the catalog and cannot append.
• Omitted token scopes and an unconfigured catalog preserve open writes. A
  scoped token, or an enforced catalog, rejects appends outside that boundary.
• Payloads are encrypted at rest, with the data key stored outside the volume
  and snapshots.
• Snapshots should be copied off-host.
• Containers run as non-root with a read-only root filesystem.

Read the architecture, security,
API, and operations guides before running
Stellar Jay with sensitive data. Point an agent at $STELLARJAY_URL/llm.txt to set
up. llm.md is the full write/replay contract.

Verify

GOCACHE=/tmp/stellarjay-gocache go test -race ./...
GOCACHE=/tmp/stellarjay-gocache go vet ./...
docker compose config
docker build -t stellarjay:test .

License

AGPL-3.0-or-later. See LICENSE.