DEFONEOS Knowledge Base

Complete architecture documentation, API reference, and developer guides for the UK's sovereign defence AI OS.

1. System Architecture — 7 Layers

DEFONEOS is built as a 7-layer sovereign substrate. Each layer is independently deployable, independently auditable, and communicates only through cryptographically signed MCP messages.

2. MCP API Reference — 30 Servers

Core Compliance & Governance MCPs

Sensor & ISR MCPs

Security & Threat Detection MCPs

3. SIGIL Chain Specification

The SIGIL chain is DEFONEOS's append-only, hash-chained, Ed25519-signed audit ledger. Every action by every agent is recorded.

Entry Format

<OP>|<actor>|<target>|<message>|<timestamp>|<prev_hash>|<signature>

Operations (OP codes)

Chain Integrity

hash(n) = SHA-256(entry_n || hash(n-1))
signature = Ed25519.sign(private_key, hash(n))

Each entry's hash includes the previous entry's hash, making the chain tamper-evident. Any modification to a historical entry invalidates all subsequent hashes. Signatures are verifiable by anyone with the agent's public key (L1 identity registration).

Verification

4. BFT Governance Protocol

Council Composition

• 33 agents — each with unique Ed25519 keypair (L1 registered)
• Quorum: 22 of 33 (67%) — required for any binding decision
• Fault tolerance: f < n/3 — tolerates up to 11 Byzantine (malicious) agents
• Consensus: HotStuff — 3-chain BFT, leader rotation, O(n) message complexity

Vote Types

Agent Roster (12 Domains)

Compliance · Security · ISR · Swarm · Cyber · Logistics · Medical · Space · Maritime · Land · Air · Civil Resilience — each domain has 2-3 council agents, ensuring no single domain dominates.

5. Knowledge Graph (SPARQL)

DEFONEOS includes a defence-grade semantic knowledge graph. RDF/OWL-compatible. SPARQL-queryable. Entities, relationships, actions, and rules.

Graph Structure

Entities (Objects):

Relationships (Links):

SPARQL Query: Dark Vessel Detection

SPARQL Query: Multi-Sensor Fusion Track

Business Rules Engine

• IF confidence > 0.85 AND BFT_quorum = true THEN escalate
• IF vessel.hasAIS = false AND RF_detected = true THEN classify(threat)
• IF drone.distance < 500m AND restricted_airspace = true THEN alert(security)
• IF cyber.threat_level = critical THEN activate(incident_response) + notify(BFT_council)
• IF red_line.violated = true THEN veto(agent) + log(SIGIL) + halt(operation)

6. Deployment Guide

Quick Start (5 Minutes)

# 1. Clone
git clone https://github.com/CSOAI-ORG/defoneos.git
cd defoneos

# 2. Install
pip install -r requirements.txt

# 3. Generate Ed25519 keypair (L1 Identity)
python -c "from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey; k=Ed25519PrivateKey.generate(); print(k.private_bytes_raw().hex(), k.public_key().public_bytes_raw().hex())"

# 4. Start SOV3 hub
python -m sov3.hub --port 3101 --host 0.0.0.0

# 5. Verify
curl -X POST localhost:3101/mcp -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Deployment Modes

Environment Variables

SOV3_HOST=0.0.0.0
SOV3_PORT=3101
BFT_COUNCIL_PORT=3200
SIGIL_CHAIN_PATH=/var/defoneos/sigil.jsonl
ED25519_PRIVATE_KEY=<hex>
ED25519_PUBLIC_KEY=<hex>
BFT_QUORUM=22
OLLAMA_HOST=http://localhost:11434
VERCEL_TOKEN=<optional>
DATABASE_URL=postgresql://...

7. SDK & Client Libraries

Python

from defoneos import DEFONEOSClient

client = DEFONEOSClient(host="localhost", port=3101)

# List all tools
tools = client.list_tools()
print(f"{len(tools)} tools available")

# Call a tool
result = client.call("sigil_emit", {
    "line": "C|operator|sov3|begin ISR scan sector alpha-7"
})

# Query the knowledge graph
tracks = client.call("sparql_query", {
    "query": "SELECT ?v WHERE { ?v rdf:type def:Vessel . ?v def:hasAIS false }"
})

# BFT vote
vote = client.call("bft_vote", {
    "proposal": "deploy-counter-drone-jammer-sector-7",
    "choice": "for"
})

JavaScript

import { DEFONEOSClient } from '@defoneos/sdk';

const client = new DEFONEOSClient('http://localhost:3101');

// List tools
const tools = await client.listTools();

// Call a tool
const result = await client.call('sigil_emit', {
  line: 'C|operator|sov3|begin ISR scan sector alpha-7'
});

// Subscribe to SIGIL stream
client.subscribe('sigil', (entry) => {
  console.log('New SIGIL:', entry);
});

curl

# List tools
curl -X POST localhost:3101/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

# Call a tool
curl -X POST localhost:3101/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"threat_detect","arguments":{"text":"suspicious payload"}}}'

8. Data Sources & OGL Licensing

DEFONEOS uses exclusively Open Government Licence (OGL) data. No proprietary data, no foreign-sourced classified data, no data without provenance.

Total data moat: 49 GB on GCP VM. All OGL/CC-BY. No lock-in.

9. Event Types & Schema

10. FAQ & Troubleshooting

Q: How is DEFONEOS different from Palantir Gotham?

A: DEFONEOS is open-source (Apache 2.0), costs £0-£9,999/mo vs Palantir's $50M/year, runs air-gapped, has BFT governance built-in, and every action is cryptographically signed. Palantir is a black box; DEFONEOS is a glass box.

Q: Can DEFONEOS run without internet?

A: Yes. The air-gapped deployment mode runs entirely offline — local Ollama models, local PostgreSQL, local MCPs. Data is transferred via USB with Ed25519 signature verification and quarantine VM processing.

Q: What happens if the BFT council can't reach quorum?

A: The action is deferred. The system enters a safe state — defensive posture, no new actions, existing operations continue with cached parameters. Quorum can be re-established by waking dormant agents or through human override (logged as a SIGIL entry with supermajority requirement).

Q: Is the SIGIL chain quantum-safe?

A: The chain itself uses SHA-256 + Ed25519. DORADO PQC module provides ML-DSA-65 (Dilithium) and ML-KEM-768 (Kyber) for quantum-resistant signatures. The 90-day key rotation ensures forward secrecy even against future quantum adversaries.

Q: Can I contribute an MCP server?

A: Yes. Fork the repo, build your MCP following the integration guide, submit a PR. Every contribution is SIGIL-signed and goes through BFT review.

Q: What's the maximum scale?

A: Tested with 33 agents, 30 MCPs, 188+ tools, 49 GB data. The architecture is horizontally scalable — more agents = more fault tolerance, more MCPs = more sensor coverage, more VMs = more compute. Coalition mode supports cross-organization federation.