Welcome

Cognitum Seed is a portable edge intelligence appliance. It provides an on-device vector store in RVF binary format, real-time sensor processing with drift detection, thermal-aware DVFS management, cryptographic custody with Ed25519 signing, and a cognitive container for spectral graph analysis — all accessible through 90 HTTPS API endpoints with per-client bearer token authentication.

Quick Start (First 5 Minutes)

Get up and running with your Cognitum Seed in five steps.

1. Plug in via USB data port (not the power port). Three interfaces appear: a COGNITUM USB drive, a USB Ethernet adapter, and mDNS at cognitum.local.
2. Install the trust certificate (optional but recommended). Open the COGNITUM USB drive and run the installer in the trust/ folder for your OS:
   • Windows: double-click trust/install-trust.bat
   • macOS: double-click trust/install-trust.command
   • Linux: run bash trust/install-trust.sh
   This adds the Seed's certificate to your system trust store so browsers and tools connect without warnings. You can skip this and accept the certificate manually instead.
3. Open the API Explorer at https://169.254.42.1:8443/. If you installed the trust certificate, it loads directly. Otherwise, accept the certificate warning when prompted. You'll see the live dashboard with vector count, epoch, and uptime.
4. Pair your client to unlock write endpoints. Go to the Pairing section and click "Pair". This opens a pairing window, issues a bearer token, and saves it to your browser automatically.
5. Ingest sample data to test the store. Click POST /api/v1/demo/ingest-sample — this adds 100 random 8-dim vectors. Then try a k-NN query with POST /api/v1/store/query.
6. Explore endpoints — 100 endpoints cover vectors, sensors, thermal governor, temporal coherence, cognitive container, custody, and more. Read endpoints work without authentication; write endpoints require a bearer token.

curl -sk -X POST https://169.254.42.1:8443/api/v1/demo/ingest-sample

Connect to Your Seed

The Seed provides three connection methods. USB is primary (no network config required); WiFi is secondary for wireless access.

USB Connection (recommended)

Plug the Seed into your computer via the USB data port (not the power-only port). Three interfaces appear:

curl -sk https://169.254.42.1:8443/api/v1/status

SSH Access

# Via USB
ssh genesis@169.254.42.1

# Via mDNS
ssh genesis@cognitum.local

# Via WiFi (if configured)
ssh genesis@192.168.1.x

Cross-Platform Compatibility

Pairing & Authentication (ADR-048)

Pairing authorizes your client to use write endpoints (ingest, delete, config updates, OTA, actuator fire). Read-only endpoints work without pairing. Each client receives a unique bearer token during pairing that must be included in all write requests.

How It Works

1. Open pairing window — POST /api/v1/pair/window opens a 30-second window. This endpoint only accepts requests from the USB interface (localhost / 169.254.42.1).
2. Pair — POST /api/v1/pair with {"client_name":"my-laptop"}. The server generates a 256-bit random token and returns it. The server stores only the SHA-256 hash of the token.
3. Save the token — This guide saves it to localStorage automatically. CLI users must save the token manually; it is shown only once.
4. Authenticate — Include Authorization: Bearer <token> on every write request. The guide does this automatically.

# Step 1: Open pairing window (USB IP only)
curl -sk -X POST https://169.254.42.1:8443/api/v1/pair/window

# Step 2: Pair and receive token
curl -sk -X POST https://169.254.42.1:8443/api/v1/pair \
  -H 'Content-Type: application/json' \
  -d '{"client_name":"my-laptop"}'

# Step 3: Use token in subsequent requests
curl -sk -X POST https://169.254.42.1:8443/api/v1/store/ingest \
  -H 'Authorization: Bearer <your-token>' \
  -H 'Content-Type: application/json' \
  -d '{"vectors":[[0,[0.1,0.2,0.3,0.4,0.5,0.6,0.7,0.8]]]}'

Paired Clients

View all clients currently paired with this Seed.

curl -sk https://169.254.42.1:8443/api/v1/pair/clients

RVF Binary Format

The Seed stores all vectors in RVF (RuVector Format), a compact append-only binary format designed for embedded devices. RVF files are binary-compatible with the parent ruvector workspace — you can generate .rvf files on your workstation and import them into the Seed, or export the Seed's store for analysis on your computer.

File Structure

An RVF file is a sequential log of entries. Each entry has a fixed-size header followed by variable-length data:

Key Properties

• Append-only — deletions are tombstones, not erasures. The file grows monotonically until compaction.
• Content-addressed IDs — vector IDs are derived from SHA-256 of the vector data (truncated to u64). Duplicate vectors get the same ID automatically.
• Witness entries — every write appends a witness entry with a SHA-256 hash linking to the previous entry, forming a tamper-evident chain.
• Compaction — POST /api/v1/store/compact rewrites the file excluding deleted vectors, reclaiming disk space.
• Pre-computed norms — L2 norms are cached per vector to accelerate cosine similarity queries (dot product + 1 division instead of 2 square roots per candidate).

Storage Budget

The Seed has 512 MB RAM. Keep total vectors * dimension * 4 bytes under ~100 MB to leave room for the sensor pipeline, kNN graph, and cognitive container.

Vector Store

The store holds vectors in RVF format with content-addressed IDs. It supports k-nearest-neighbor queries using cosine similarity, batch ingest with deduplication, soft-delete with compaction, and a kNN graph for structural analysis.

k-NN Query

Query returns the k most similar vectors by cosine similarity. Uses a BinaryHeap with O(n log k) complexity and early distance pruning. Supports multiple distance metrics via the metric field: cosine (default), l2, or dot.

curl -sk -X POST https://169.254.42.1:8443/api/v1/store/query \
  -H 'Content-Type: application/json' \
  -d '{"vector":[0.1,0.2,0.3,0.4,0.5,0.6,0.7,0.8],"k":5}'

# With metadata filter and metric
curl -sk -X POST https://169.254.42.1:8443/api/v1/store/query \
  -d '{"vector":[0.1,0.2,0.3,0.4,0.5,0.6,0.7,0.8],"k":5,"metric":"l2","filter":{"field_id":0,"op":"eq","value":"sensor"}}'

kNN Graph

The optimizer loop rebuilds a k=16 nearest-neighbor graph every 10 seconds (when changes are detected). The graph drives boundary analysis (Stoer-Wagner min-cut) which produces a fragility score from 0.0 (solid) to 1.0 (fragile). Fragility directly controls the thermal governor's demand level.

Witness Chain

Every write operation (ingest, delete, compact) appends a tamper-evident entry to the witness chain. Each entry contains a SHA-256 hash that links to the previous entry, forming a cryptographic audit trail. If any historical entry is modified, the chain verification fails at the tampered link.

What Gets Witnessed

curl -sk -X POST https://169.254.42.1:8443/api/v1/witness/verify

Custody & Ed25519 Signing

Each Seed has a unique Ed25519 keypair derived from its device ID. The private key never leaves the device. You can sign arbitrary data and verify signatures, enabling cryptographic proof that data originated from a specific Seed.

Signing Workflow

1. Sign data with POST /api/v1/custody/sign — returns hex-encoded Ed25519 signature + public key.
2. Verify with POST /api/v1/custody/verify — pass the data, signature, and optionally a public key. Uses the device's own key if omitted.
3. Attestation with GET /api/v1/custody/attestation — returns a signed attestation proving the device booted with its identity, including epoch, vector count, and witness head.

curl -sk -X POST https://169.254.42.1:8443/api/v1/custody/sign \
  -H 'Content-Type: application/json' -d '{"data":"hello world"}'

MCP Proxy (ADR-047)

The Model Context Protocol proxy exposes the Seed's capabilities to AI assistants (Claude, GPT, etc.) via JSON-RPC 2.0 over Streamable HTTP at /mcp. 12 tools across 6 groups, 4 resources, 3 guided prompts, and a default-deny policy engine.

Architecture

Tool Scopes

Set via capabilities.experimental.cognitum.toolScope in the initialize request.

Auth Classes

Tool Groups (21)

Connection Flow

# 1. Initialize the MCP session (default scope = 24 tools)
curl -s -X POST http://169.254.42.1/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"initialize","id":1,"params":{"protocolVersion":"2025-11-25","clientInfo":{"name":"my-client","version":"1.0"},"capabilities":{"experimental":{"cognitum":{"toolScope":"default"}}}}}'

# 2. Send initialized notification
curl -s -X POST http://169.254.42.1/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"notifications/initialized"}'

# 3. List available tools
curl -s -X POST http://169.254.42.1/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":2,"params":{}}'

# 4. Call a tool
curl -s -X POST http://169.254.42.1/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/call","id":3,"params":{"name":"seed.device.status","arguments":{}}}'

Try It — MCP Initialize + Status

Try It — MCP Tools List

Try It — MCP Query Vectors

Resources & Prompts

Resources (read via resources/read):

Prompts (expand via prompts/get):

Batch Requests

Send multiple JSON-RPC calls in a single HTTP POST as a JSON array. Notifications (no id) return HTTP 202.

# Batch: initialize + list tools in one request
curl -s -X POST http://169.254.42.1/mcp \
  -H "Content-Type: application/json" \
  -d '[
  {"jsonrpc":"2.0","method":"initialize","id":1,"params":{"protocolVersion":"2025-11-25","clientInfo":{"name":"test"}}},
  {"jsonrpc":"2.0","method":"notifications/initialized"},
  {"jsonrpc":"2.0","method":"tools/list","id":2,"params":{}}
]'

{
  "mcpServers": {
    "cognitum-seed": {
      "url": "http://169.254.42.1/mcp",
      "transport": "streamable-http"
    }
  }
}

# Step 1: Initialize (get server capabilities)
POST /mcp  {"jsonrpc":"2.0","method":"initialize","id":1,
  "params":{"protocolVersion":"2025-11-25",
    "clientInfo":{"name":"my-app","version":"1.0"}}}

# Step 2: Confirm initialization
POST /mcp  {"jsonrpc":"2.0","method":"notifications/initialized"}

# Step 3: Use tools, resources, or prompts
POST /mcp  {"jsonrpc":"2.0","method":"tools/call","id":2,
  "params":{"name":"seed.status.get","arguments":{}}}

# User: "Search the seed for vectors similar to [0.1, 0.2, ...]"
# Claude calls: seed.memory.query with {"query":[0.1,0.2,...], "k":10}
# User: "What's the device status?"
# Claude calls: seed.status.get
# User: "Diagnose this seed"
# Claude uses prompt: seed_diagnose

ssh -L 8444:127.0.0.1:8444 genesis@cognitum.local

Sensor Subsystem (ADR-041)

The sensor loop samples 6 channels at 10 Hz, producing 45-dimensional embeddings. The pipeline flows: raw samples → sliding window → feature extraction (5 stats per channel + pairwise cross-correlations) → HD gate (1024-bit hyperdimensional hash for anomaly screening) → drift detection (Page-Hinkley + ADWIN + Reservoir ESN) → reflex arc (sensor-to-actuator rules).

Embedding Dimensions

For C channels, the embedding has 5C + C*(C-1)/2 dimensions:

Drift Detection

Three independent detectors run simultaneously. An alarm fires when any detector triggers:

Available Drivers

Thermal Governor (ADR-043)

A 1 Hz DVFS governor manages CPU frequency across 4 steps based on SoC temperature, workload demand, and per-chip silicon characterization. The governor runs a 5-step decision pipeline every tick:

1. Firmware veto — check for hardware throttle flags
2. Thermal ceiling — cap frequency based on temperature zone
3. Predictive preemption — if temperature derivative is rising fast, step down early
4. Demand target — set frequency based on workload (fragility score, query rate)
5. Turbo management — burst scheduler with cooldown

Thermal Zones

Zones use 3°C hysteresis to prevent oscillation at boundaries.

Frequency Steps

Temporal Coherence (ADR-042)

Temporal coherence tracks the structural stability of the vector store over time. Every 10 seconds, the optimizer collects a time slice — a snapshot of the kNN graph's similarity structure. Coherence is computed by comparing adjacent slices: a score of 1.0 means the structure is perfectly stable; 0.0 means complete restructuring between slices.

Phase Boundaries

A phase boundary marks a structural regime change — the point where the vector store's topology shifted significantly (e.g., a burst of new data changed cluster structure). Boundaries must persist across N consecutive recomputes to be reported, preventing false positives from transient noise.

Interpreting Scores

Cognitive Container

The cognitive container runs spectral graph analysis on the kNN graph every 30 seconds. Each tick computes a Spectral Coherence Score (SCS) — a measure of graph connectivity via eigenvalue analysis. It accumulates evidence over time and appends tamper-evident receipts to a secondary witness chain independent of the RVF store's chain.

Dual Witness Chains

Memory Budget

The container uses a 512 KB memory slab (reduced from the default 4 MB for the Seed's 512 MB RAM). Max retained receipts: 1000. Both are configurable via PUT /api/v1/cognitive/config.

Import / Export

Import .rvf files from the filesystem (placed via SCP or USB) or export the current store. Import validates dimension match (rejects with 409 on mismatch) and deduplicates by content hash. The Seed's 64 KB HTTP body limit means large files must be placed on the filesystem first, then imported by path.

How-To: Ingest Vectors

Ingest vectors via the JSON API or by importing .rvf files.

API Ingest (small batches)

Send vectors as [id, [f32...]] pairs. The array length must match the store dimension (default 8). IDs are u64; use 0 for auto-generated content-hash IDs.

# Single vector
curl -sk -X POST https://169.254.42.1:8443/api/v1/store/ingest \
  -H 'Content-Type: application/json' \
  -d '{"vectors":[[1,[0.1,0.2,0.3,0.4,0.5,0.6,0.7,0.8]]]}'

# Batch of 3 vectors with content-hash dedup
curl -sk -X POST https://169.254.42.1:8443/api/v1/store/ingest \
  -d '{"vectors":[[0,[0.1,0.2,0.3,0.4,0.5,0.6,0.7,0.8]],[0,[0.9,0.8,0.7,0.6,0.5,0.4,0.3,0.2]],[0,[0.5,0.5,0.5,0.5,0.5,0.5,0.5,0.5]]],"dedup":true}'

File Import (large datasets)

# 1. Copy .rvf file to the Seed
scp my-data.rvf genesis@169.254.42.1:~/

# 2. Import via API (reads from filesystem)
curl -sk -X POST https://169.254.42.1:8443/api/v1/store/import \
  -d '{"path":"/home/genesis/my-data.rvf"}'

# 3. Check result
curl -sk https://169.254.42.1:8443/api/v1/store/status

Python Client Example

import requests, json, urllib3
urllib3.disable_warnings()  # skip if trust cert installed

BASE = "https://169.254.42.1:8443/api/v1"
TOKEN = "<your-bearer-token-from-pairing>"
HEADERS = {"Authorization": f"Bearer {TOKEN}"}

# Ingest vectors (requires auth)
vectors = [[i, [float(j)/8 for j in range(8)]] for i in range(100)]
r = requests.post(f"{BASE}/store/ingest",
    json={"vectors": vectors}, headers=HEADERS, verify=False)
print(r.json())  # {"ingested": 100, "epoch": ...}

# Query (read-only, no auth required)
r = requests.post(f"{BASE}/store/query",
    json={"vector": [0.1]*8, "k": 5}, verify=False)
for hit in r.json()["results"]:
    print(f"ID {hit['id']}: distance={hit['distance']:.4f}")

How-To: Change Vector Dimension

The store dimension is set by the first ingested vector and cannot be changed without resetting the store. All subsequent vectors must match this dimension.

Setting the Dimension

1. Fresh store — the first ingest sets the dimension. If you ingest an 8-dim vector, the store is 8-dim forever (until reset).
2. Dimension mismatch — if you ingest a vector with the wrong dimension, you get a 400 error: "dimension mismatch: expected 8, got 16".
3. Import mismatch — importing an .rvf file with a different dimension returns 409 Conflict.

Resetting to a New Dimension

# 1. SSH into the Seed
ssh genesis@169.254.42.1

# 2. Stop the agent
sudo systemctl stop cognitum-agent

# 3. Remove the store file (WARNING: deletes all vectors)
sudo rm /var/lib/cognitum/rvf-store/*.rvf

# 4. Restart
sudo systemctl start cognitum-agent

# 5. Ingest with your new dimension (e.g., 128-dim)
curl -sk -X POST https://169.254.42.1:8443/api/v1/store/ingest \
  -d '{"vectors":[[1,[0.1,0.2,...128 values...]]]}'

How-To: Add Real Sensors

The default configuration uses 6 synthetic (software) channels. To add real hardware sensors, wire them to the Seed's GPIO header and update the sensor configuration.

Example: BME280 (Temperature + Humidity + Pressure)

1. Wire the sensor to the I2C bus: VCC → 3.3V (pin 1), GND → GND (pin 6), SDA → GPIO 2 (pin 3), SCL → GPIO 3 (pin 5).
2. Enable I2C on the Pi: sudo raspi-config → Interface Options → I2C → Enable.
3. Verify detection: i2cdetect -y 1 should show the BME280 at address 0x76 or 0x77.
4. Update sensor config via the API (requires pairing):

   curl -sk -X PUT https://169.254.42.1:8443/api/v1/sensor/embedding/config \
     -H 'Content-Type: application/json' \
     -d '{"drivers":[{"type":"bme280","bus":1,"address":"0x76"}]}'

5. Verify readings: GET /api/v1/sensor/stream should show real temperature, humidity, and pressure values instead of synthetic sine waves.

Example: GPIO Digital (Reed Switch / PIR)

1. Wire: connect the switch between a GPIO pin (e.g., GPIO 17, pin 11) and GND. The internal pull-up provides the high state.
2. Configure: add a gpio_digital driver entry with the pin number.
3. Read: GET /api/v1/sensor/gpio/pins shows pin states.

How-To: Configure Reflex Rules

Reflex rules define automatic sensor-to-actuator responses. When a trigger condition is met, the reflex arc fires the specified actuator action. Rules have priorities and cooldown periods to prevent rapid-fire toggling.

Rule Structure

{
  "name": "high-temp-alert",
  "trigger": {
    "type": "threshold",        // threshold | drift | fragility
    "channel": "temperature",
    "op": "gt",                  // gt | lt | eq
    "value": 60.0
  },
  "action": {
    "type": "fire",             // fire | release | pwm
    "actuator": 0
  },
  "cooldown_ms": 5000,
  "priority": 1                  // lower = higher priority
}

Trigger Types

Update rules via PUT /api/v1/sensor/reflex/rules (requires pairing). Safety-first: fragility checks run before boundary analysis to prevent cascading failures.

How-To: Silicon Characterization

Each Pi chip is slightly different. Silicon characterization tests your specific chip to find its maximum stable overclock frequency.

1. Trigger characterization: POST /api/v1/thermal/characterize (requires pairing). This takes ~30 seconds.
2. The test runs boundary analysis 10 times at each frequency step [600, 1000, 1200, 1300 MHz] and compares SHA-256 hashes of the partition results.
3. If all 10 runs produce identical hashes at a frequency, that step is marked stable.
4. The governor's max frequency is automatically capped at the highest stable step.
5. View results: GET /api/v1/thermal/silicon-profile shows pass/fail per step.

How-To: Export & Backup

Export via API

# Export store to a file on the Seed
curl -sk -X POST https://169.254.42.1:8443/api/v1/store/export \
  -d '{"path":"/tmp/backup.rvf"}'

# Download it to your computer
scp genesis@169.254.42.1:/tmp/backup.rvf ./backup.rvf

Full Sync (all live vectors)

# Pull all vectors as JSON
curl -sk https://169.254.42.1:8443/api/v1/store/sync > vectors.json

SD Card Image

# On the Pi: zero free space for better compression
sudo dd if=/dev/zero of=/tmp/zero bs=4M 2>/dev/null; sudo rm /tmp/zero

# On your computer: image the SD card
# (replace sdX with your SD card device)
sudo dd if=/dev/sdX bs=4M status=progress | gzip > cognitum-backup.img.gz

File Transfer

Upload RVF vector files or download the current store. The Seed accepts uploads up to 64 KB via HTTP; for larger files, use the SCP workflow below.

# 1. Copy file to Seed
scp my-data.rvf genesis@169.254.42.1:/home/genesis/

# 2. Import via API
curl -sk -X POST https://169.254.42.1:8443/api/v1/store/import \
  -H 'Content-Type: application/json' \
  -d '{"path":"/home/genesis/my-data.rvf"}'

# 3. Verify
curl -sk https://169.254.42.1:8443/api/v1/store/status

Store Operations

Query, inspect, and manage the vector store directly from this page.

Configuration

View and update device configuration. Write operations require pairing.

Device Management

Monitor and control device operations. Destructive actions require pairing and confirmation.

Quick Actions

Optimization

Thermal & Characterization

Witness & Custody

Core API Endpoints (30)

Store v2 API Endpoints (9)

Sensor API Endpoints (17)

Thermal API Endpoints (13)

Coherence API Endpoints (5)

Cognitive API Endpoints (7)

Import / Export Endpoints (3)

Security & Firmware Endpoints (8)

Sync & Swarm Endpoints (10)

Delta Sync Example

# Pull only changes since epoch 50
curl -sk "https://169.254.42.1:8443/api/v1/store/sync?since_epoch=50"
# Response: {"is_delta":true, "vectors":[...], "deletions":[12,45], "current_epoch":73}

# Push changes to peer
curl -sk -X POST https://169.254.42.1:8443/api/v1/store/sync \
  -H "Content-Type: application/json" \
  -d '{"vectors":[[1,[0.1,0.2,0.3,0.4,0.5,0.6,0.7,0.8]]],"deletions":[99],"source_device_id":"peer-uuid","source_epoch":30}'

MCP Tools — 114 Tools, 21 Groups (ADR-058)

All MCP communication uses JSON-RPC 2.0 via POST /mcp. Session must be initialized before calling tools. Scope controls how many tools are advertised.

Wire Format

# Request (using canonical tool name):
{"jsonrpc":"2.0","method":"tools/call","id":3,"params":{"name":"seed.device.status","arguments":{}}}

# Response (with annotations):
{"jsonrpc":"2.0","result":{"content":[{"type":"text","text":"{\"deviceId\":\"...\",\"uptimeSecs\":120,...}"}]},"id":3}

# Auth denied (wrong auth class):
{"jsonrpc":"2.0","error":{"code":-32001,"message":"Auth class 'dangerous' required","data":{"tool":"seed.firmware.update","requiredAuthClass":"dangerous"}},"id":4}

Headers

Upgrade & Other Endpoints (2)

Hardware

GPIO Pin Assignments

Performance Benchmarks (20k vectors, dim=8)

Security

Witness Chain Verification

Every store mutation (ingest, delete, compact, metadata update) appends a SHA-256 witness hash: SHA-256(prev_hash || entry_data). The chain is tamper-evident — flipping any byte in any entry breaks all subsequent hashes.

# Verify the full witness chain
curl -sk -X POST https://169.254.42.1:8443/api/v1/witness/verify
# {"valid":true, "algorithm":"sha256", "head":"a1b2c3...", "entries_verified":20000}

OTA Firmware Verification

When a build key is configured, firmware updates require a valid Ed25519 signature. Two modes are supported:

# Mode 1: Detached signature (X-Signature header, hex-encoded)
curl -sk -X POST https://169.254.42.1:8443/api/v1/firmware/update \
  -H "X-Signature: a1b2c3d4..." \
  --data-binary @cognitum-agent

# Mode 2: Inline signature (last 64 bytes of body)
cat cognitum-agent signature.bin | \
curl -sk -X POST https://169.254.42.1:8443/api/v1/firmware/update \
  -H "X-Signed: true" \
  --data-binary @-

mTLS Auto-Enable

If a client CA certificate exists at the well-known path, mTLS is automatically enabled in optional mode. No flag needed.

# Production: /var/lib/cognitum/tls/client-ca.pem
# Virtual:    ./client-ca.pem

# Check mTLS status
curl -sk https://169.254.42.1:8443/api/v1/security/status | jq .mtls_active

Getting Files Onto the Seed

The USB drive (COGNITUM) is read-only. Use these methods to transfer files:

SCP (Secure Copy)

# Over USB
scp myfile.rvf genesis@169.254.42.1:~/

# Over WiFi
scp myfile.rvf genesis@cognitum.local:~/

Typical Import Workflow

# 1. Copy .rvf file to the Seed
scp data.rvf genesis@169.254.42.1:~/

# 2. Import via API
curl -sk -X POST https://169.254.42.1:8443/api/v1/store/import \
  -H "Content-Type: application/json" \
  -d '{"path": "/home/genesis/data.rvf"}'

# 3. Verify
curl -sk https://169.254.42.1:8443/api/v1/store/status

WiFi Setup

Configure WiFi to access the Seed wirelessly from any device on your network.

Browser Setup (when connected via USB)

SSH Setup

# Connect to WiFi
sudo nmcli device wifi connect "YourNetwork" password "YourPassword"

# Verify and note IP
ip -4 addr show wlan0 | grep inet

# Add multiple networks (auto-connects to whichever is available)
sudo nmcli device wifi connect "Office-WiFi" password "officepass"

# List / remove saved networks
nmcli connection show
sudo nmcli connection delete "Office-WiFi"

Manage Saved Networks

WiFi credentials persist across firmware updates (stored on the data partition). The Seed does not bridge USB and WiFi traffic (network isolation).

Firmware Updates

The Seed uses A/B slot partitioning. Updates write to the inactive slot. If the API doesn't respond within 30 seconds after reboot, the boot guard rolls back automatically after 3 failed attempts.

Quick Deploy (binary only)

# Stop, copy, restart
ssh genesis@cognitum.local "sudo systemctl stop cognitum-agent"
scp cognitum-agent genesis@cognitum.local:~/
ssh genesis@cognitum.local \
  "sudo cp ~/cognitum-agent /opt/cognitum/cognitum-agent && \
   sudo chmod 755 /opt/cognitum/cognitum-agent && \
   sudo systemctl start cognitum-agent"

Partition Layout

Troubleshooting

Device not detected via USB

Use the USB data port (not power-only). Check for the COGNITUM drive. If USB Ethernet doesn't appear, SSH via WiFi and check: cat /sys/kernel/config/usb_gadget/cognitum/UDC (should show 3f980000.usb).

401 Unauthorized / 403 Forbidden on write endpoints

401: Missing or invalid bearer token. Go to Pairing and pair your client. The guide saves the token to localStorage automatically. For CLI, include -H 'Authorization: Bearer <token>'.

403: The pairing window is not open, or the request did not come from the USB interface. Open the window first with POST /api/v1/pair/window.

TLS certificate warning

The Seed uses a device-specific certificate. You have two options:

1. Install the trust certificate (recommended) — open the COGNITUM USB drive and run the installer in the trust/ folder:
   • Windows: trust/install-trust.bat
   • macOS: trust/install-trust.command
   • Linux: bash trust/install-trust.sh
   After installing, browsers and tools will connect without warnings.
2. Skip the installer — use -k with curl, verify=False in Python, or click "Advanced → Proceed" in your browser.

409 on import

The .rvf file has a different vector dimension than the store. Check with GET /api/v1/store/import/formats. To change dimension, see How-To: Change Dimension.

Sensor endpoints return 404

Sensor endpoints require the optimizer loop to be running. In --virtual mode (localhost dev), only core + thermal endpoints are available. Deploy to Pi or run without --virtual.

Device goes to sleep

Check that g_ether is not loaded: lsmod | grep g_ether. If loaded, blacklist it and reboot.

Recovery

Hold the factory reset button (GPIO 27) for 10+ seconds to wipe data and regenerate identity. Or use Raspberry Pi Connect for remote access.