Skip to main content
This guide will get you from zero to querying node liveness in under 5 minutes.

​
Prerequisites

You need one of the following:
  • Docker (recommended for quickest start)
  • Go 1.21+ installed
  • curl or similar HTTP client

​
Running the Server

1

Start the Styx server

docker pull pawan126/styx
docker run -p 8080:8080 pawan126/styx
You should see:
styx oracle listening on :8080
endpoints:
  GET  /health          - health check
  GET  /query?target=ID - query node status
  POST /report          - submit witness report
  POST /witnesses       - register witness
The server creates a new Oracle instance with ID 1 by default (see source/cmd/styx-server/main.go:17).
2

Verify server is healthy

Check that the server is running:
cURL
curl http://localhost:8080/health
Expected response:
{"status":"ok","service":"styx"}
The health endpoint always returns 200 OK if the server is running (see source/api/server.go:136-139).
3

Query a node (with no data)

Let’s query node 42 before we have any witness reports:
curl "http://localhost:8080/query?target=42"
Response:
{
  "target": 42,
  "alive_confidence": 0,
  "dead_confidence": 0,
  "unknown": 1,
  "refused": false,
  "dead": false,
  "witness_count": 0,
  "disagreement": 0,
  "partition_state": "NO_PARTITION",
  "evidence": ["no witness reports available"]
}
With no evidence, Styx returns pure uncertainty (100% unknown). This is the UnknownBelief() from source/types/belief.go:99-105.

​
Submitting Witness Reports

Now let’s add some witness reports so the Oracle has data to work with.
1

Register a witness (optional)

Witnesses are auto-registered when they submit reports, but you can register them explicitly:
curl -X POST http://localhost:8080/witnesses \
  -H "Content-Type: application/json" \
  -d '{"id": 10}'
Response:
{"status":"registered"}
2

Submit a witness report

Let’s have witness 10 report that node 42 is likely alive:
curl -X POST http://localhost:8080/report \
  -H "Content-Type: application/json" \
  -d '{
    "witness": 10,
    "target": 42,
    "alive": 0.8,
    "dead": 0.1,
    "unknown": 0.1
  }'
Response:
{"status":"accepted"}
The three confidence values must sum to exactly 1.0, or you’ll get a validation error from source/types/belief.go:62-66:
sum := alive + dead + unknown
if math.Abs(sum-1.0) > BeliefSumEpsilon {
    return Belief{}, fmt.Errorf("%w: got %f", ErrBeliefInvalidSum, sum)
}
3

Add more witness reports

Let’s add reports from witnesses 11 and 12:
Witness 11 (agrees: node 42 is alive)
curl -X POST http://localhost:8080/report \
  -H "Content-Type: application/json" \
  -d '{"witness":11,"target":42,"alive":0.75,"dead":0.15,"unknown":0.1}'
Witness 12 (neutral: uncertain)
curl -X POST http://localhost:8080/report \
  -H "Content-Type: application/json" \
  -d '{"witness":12,"target":42,"alive":0.4,"dead":0.3,"unknown":0.3}'
4

Query with aggregated data

Now query node 42 again:
curl "http://localhost:8080/query?target=42"
You’ll see aggregated results:
{
  "target": 42,
  "alive_confidence": 0.65,
  "dead_confidence": 0.18,
  "unknown": 0.17,
  "refused": false,
  "dead": false,
  "witness_count": 3,
  "disagreement": 0.12,
  "partition_state": "NO_PARTITION",
  "evidence": ["aggregated 3 witness reports"]
}
The Oracle has aggregated all three witness reports using source/witness/aggregator.go.

​
Using the CLI

Styx includes a command-line client for easier interaction.
1

Install the CLI

go install github.com/Cintu07/styx/cmd/styx@latest
2

Query a node

styx query 42
Output:
node 42:
  alive:   65.0%
  dead:    18.0%
  unknown: 17.0%
  status:  likely alive
The CLI formats the response nicely (see source/cmd/styx/main.go:67-99).
3

Submit a report via CLI

styx report 13 42 0.9 0.05 0.05
This submits a report from witness 13 about target 42 with confidences [alive=0.9, dead=0.05, unknown=0.05].
4

Check server health

styx health
Output:
server: healthy

​
Simulating a Partition

Let’s see Styx refuse to answer during a network partition.
1

Add conflicting witness reports

Submit reports where some witnesses see node 99 as alive, others as dead:
Witnesses 20-22: See node 99 as ALIVE
curl -X POST http://localhost:8080/report \
  -d '{"witness":20,"target":99,"alive":0.9,"dead":0.05,"unknown":0.05}'
curl -X POST http://localhost:8080/report \
  -d '{"witness":21,"target":99,"alive":0.85,"dead":0.1,"unknown":0.05}'
curl -X POST http://localhost:8080/report \
  -d '{"witness":22,"target":99,"alive":0.8,"dead":0.1,"unknown":0.1}'
Witnesses 30-32: See node 99 as DEAD
curl -X POST http://localhost:8080/report \
  -d '{"witness":30,"target":99,"alive":0.05,"dead":0.9,"unknown":0.05}'
curl -X POST http://localhost:8080/report \
  -d '{"witness":31,"target":99,"alive":0.1,"dead":0.85,"unknown":0.05}'
curl -X POST http://localhost:8080/report \
  -d '{"witness":32,"target":99,"alive":0.1,"dead":0.8,"unknown":0.1}'
2

Query during partition

curl "http://localhost:8080/query?target=99"
Response:
{
  "target": 99,
  "alive_confidence": 0,
  "dead_confidence": 0,
  "unknown": 1,
  "refused": true,
  "refusal_reason": "network partition detected - witnesses disagree",
  "witness_count": 6,
  "disagreement": 0.5,
  "partition_state": "CONFIRMED_PARTITION",
  "evidence": ["partition: witnesses split into groups"]
}
Styx refuses to answer! When the disagreement exceeds 40% (see source/partition/detector.go:61), Styx detects a ConfirmedPartition and returns refused: true.This prevents making a wrong decision during split-brain scenarios.

​
Understanding the Response

Let’s break down the query response fields: 
// From source/api/server.go:26-39
type QueryResponse struct {
    Target          uint64   // Node being queried
    AliveConfidence float64  // P(node is alive) [0.0-1.0]
    DeadConfidence  float64  // P(node is dead) [0.0-1.0]
    Unknown         float64  // P(state unknown) [0.0-1.0]
    Refused         bool     // Oracle refuses to answer?
    RefusalReason   string   // Why Oracle refused
    Dead            bool     // Finality: node declared dead?
    WitnessCount    int      // Number of witness reports
    Disagreement    float64  // Witness disagreement level
    PartitionState  string   // NO_PARTITION, SUSPECTED, or CONFIRMED
    Evidence        []string // Reasoning for this result
}

​
Environment Variables

The CLI supports custom server URLs: 
export STYX_SERVER="http://styx.prod.example.com:8080"
styx query 42
See source/cmd/styx/main.go:20-23 for the default server configuration.

​
Next Steps

Installation Options

Learn about Docker, Go install, and building from source

API Reference

Explore all API endpoints and parameters

Concepts

Deep dive into beliefs, witnesses, and finality

Architecture

Understand how Styx components work together

Build docs developers (and LLMs) love

Get started for freeTalk to us