Stellar Jay logo

Stellar Jay

Safe write access for AI agents. Stellar Jay is where your agents keep business data. Every change is kept, attributed to the agent that made it, and can be undone. Think of it as Git for your business data.

• Hosted: AvianSuite runs Stellar Jay for you. $20/month per store, with a 14-day free trial.
• Self-hosted: free and open source under the AGPL. The quick start below gets a store running on your machine in a few minutes.

Agent setup

Connect an agent with the MCP server. On AvianSuite, add the remote server:

# Claude Code
claude mcp add --transport http aviansuite https://mcp.aviansuite.com/mcp

// Cursor: .cursor/mcp.json
{"mcpServers": {"aviansuite": {"url": "https://mcp.aviansuite.com/mcp"}}}

In Claude and ChatGPT, add a custom connector with the same URL.

For a self-hosted store, run the local server instead:

{
  "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. Tools and details: docs/mcp.md.

Why

Clients want agents that do the work, not just read about it. But when an agent writes straight into a CRM or ticketing system, one bad decision or runaway loop can overwrite or delete records, and there is often no way back.

Stellar Jay is built so that can't happen:

• Nothing is overwritten or deleted. A correction or retraction is a new entry, and the original stays in history.
• Every change has a name on it. Each agent gets its own token, so you can see exactly which agent changed what, and when.
• Any change can be undone. Roll back everything one agent did in a time window, with a preview first.
• History is tamper-evident. If anyone rewrites or removes past entries, it shows.
• Retries are safe. An agent that retries after a timeout doesn't create duplicates, and a write based on stale information is refused.
• Your data stays flexible. Facts are JSON, so new fields and new kinds of records need no migrations.

Stellar Jay records what agents say happened. It doesn't decide whether a fact is true; it makes sure a wrong one stays visible and correctable.

Who it's for

Developers, consultants, and small teams moving from read-only copilots to agents that are allowed to act: operations, accounting, approvals, support, and other work where the data matters. Each store serves one organization. Many agents and apps can share it.

Quick start (self-hosted)

Requires Go 1.22 or later.

1. Install and create secrets.

go install github.com/kyle-visner/stellarjay/cmd/stellarjay-server@latest
stellarjay-server init ./secrets

init creates a data encryption key and prints an admin, writer, and reader token once. Save them in a password manager.

2. Start the server.

export STELLARJAY_DATA_DIR=./data
export STELLARJAY_DATA_KEY_FILE=./secrets/data_key
export STELLARJAY_AUTH_FILE=./secrets/auth.json
stellarjay-server serve

It listens on 127.0.0.1:8080.

3. Record a fact. In another terminal:

export STELLARJAY_URL=http://127.0.0.1:8080
export STELLARJAY_TOKEN='the-writer-token'

curl -fsS -X POST "$STELLARJAY_URL/v1/events" \
  -H "Authorization: Bearer $STELLARJAY_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: first-fact" \
  --data '{
    "type": "business.fact",
    "entity_id": "customer-42",
    "command": "fact assert",
    "payload": {"predicate": "primary_contact", "value": "Ada Lovelace"},
    "expected_root": ""
  }'

expected_root is empty only for the first entry in a new store. After that, read the current value from GET /v1/root and send it with each write, so a write based on stale information is refused. The API guide covers reading history, pagination, named checkpoints, and snapshots.

4. Connect an agent. Point the MCP server at your store:

go install github.com/kyle-visner/stellarjay/cmd/stellarjay-mcp@latest

Then use the self-hosted config from Agent setup with STELLARJAY_URL=http://127.0.0.1:8080 and your writer token. Agents that don't use MCP can read $STELLARJAY_URL/llm.txt, which explains how to work with the store.

Deploy to a server

For a production store with HTTPS, you need a Linux host with Docker Compose, ports 80 and 443 open, and a DNS record pointing a domain at the host.

git clone https://github.com/kyle-visner/stellarjay.git
cd stellarjay
cp .env.example .env
# Edit .env and set STELLARJAY_DOMAIN.

go run ./cmd/stellarjay-server init ./secrets

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

init will not replace existing secrets. Read the operations runbook for backups, token rotation, and upgrades, and the security model before storing sensitive data. Or skip all of this and use AvianSuite.

Documentation

• llm.md: the guide agents follow to read and write safely
• docs/mcp.md: MCP server setup and tools
• docs/how-it-works.md: storage model, design limits, and the embedded Go library
• docs/api.md: HTTP API reference (OpenAPI)
• docs/architecture.md, docs/security.md, docs/operations.md: running it in production

Development

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. Hosted Stellar Jay is available from AvianSuite.