Getting started

This content is for v1.0. Switch to the latest version for up-to-date documentation.

In about 15 minutes you will have a running Starfly fabric unit and your first scoped WIMSE JWT — proof that exchange, policy, and signing work on your laptop before you wire agents or tools.

What you’ll prove

Starfly boots in dev mode and answers health checks
A platform credential exchanges for a WIMSE JWT with aud, td, and exp
Metrics and live events stream from the PEP
Sandbox scripts replay exchange, revocation, and MCP scenarios

No Kubernetes required for this path.

Prerequisites

Go 1.25+ (go version)
curl and jq
Make

1. Clone and build

git clone https://github.com/raygj/project-starfly-fabrics.git
cd project-starfly-fabrics
make build-dev

Produces bin/starfly — single binary, dev-tagged build.

2. Start dev mode

STARFLY_STORAGE_PATH=/tmp/starfly-dev \
STARFLY_POLICY_BUNDLE_PATH=policies/dev \
./bin/starfly --dev

Boot banner highlights:

using DEV lock — data at rest is not encrypted (dev only)
policy loaded — policies/dev/exchange.rego
HTTP server listening on :8693

3. Health check

curl -s http://localhost:8693/v1/sys/health | jq

{
  "initialized": true,
  "locked": false,
  "version": "dev",
  "unit_id": "…"
}

4. JWKS

curl -s http://localhost:8693/v1/identity/jwks | jq

Downstream services verify WIMSE JWTs against this endpoint (kid: starfly-dev-1 in dev).

5. First exchange

curl -s -X POST http://localhost:8693/v1/exchange/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "urn:ietf:params:oauth:grant-type:token-exchange",
    "subject_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJteS1hcHAiLCJpc3MiOiJkZXYiLCJleHAiOjk5OTk5OTk5OTl9.stub",
    "subject_token_type": "urn:ietf:params:oauth:token-type:jwt",
    "audience": "https://api.target.example.com",
    "scope": "read:data"
  }' | jq

In dev mode, any parseable JWT is accepted against the synthetic dev.local trust domain.

6. Read the WIMSE JWT

Pipe .access_token through base64 decode on the payload segment, or use the sandbox:

./sandbox/init.sh
./sandbox/run.sh exchange

Key claims: sub, aud, td (trust domain), exp. Deeper dive: exchange concepts.

7. Metrics and live events

curl -s http://localhost:8693/metrics | grep starfly_exchange
curl -N http://localhost:8693/v1/events

These same streams power the operations dashboard when deployed.

8. Run the proof scripts

Five scenarios — no Go rebuild required against a running PEP:

./sandbox/run.sh all

Narrated demos:

./demos/01-token-exchange.sh
./demos/02-real-time-revocation.sh
./demos/03-confused-deputy.sh

Manifest and agent bootstrap: sandbox/ · AGENTS.md

What’s next

Goal	Go here
Vocabulary	Glossary
Wire an agent	Token exchange
MCP tool security	MCP security
Multi-protocol tools	UTC
Playground UI	starfly.dev/play
API contract	OpenAPI

Documentation voice