Spanda

Getting Started with Spanda

Spanda is an autonomous systems platform with a safety-first .sd language at its core. This guide gets you from install to your first robot program in under 10 minutes.

Release note: Current workspace release is v0.6.3 (evaluation / beta). Default AI and transport paths are mock-backed unless you configure live backends — known-limitations.md · troubleshooting.md.

Pronounced SPUN-duh (/ˈspʌndə/) — Sanskrit for the divine pulse; see philosophy for the body metaphor and etymology.

Platform map: platform-overview.md · All tutorials: Tutorials index

---

Installation

Install prebuilt packages for Linux, macOS, and Windows from GitHub Releases, or build from source below.

See installation.md for shell/MSI/PowerShell installers and platform archives.

Build from source

1. Clone the repository

git clone https://github.com/Davalgi/Spanda.git
cd Spanda

2. Install dependencies

npm install

3. Build the native CLI

npm run build:rust

This produces target/release/spanda. Verify:

./target/release/spanda check examples/hello_world.sd

Optional: add target/release to your PATH so you can run spanda directly.

---

Your first project

Initialize a project

spanda init my_rover
cd my_rover

This creates a spanda.toml manifest and src/main.sd starter file.

Edit src/main.sd

robot MyRover {
  sensor lidar: Lidar on "/scan";
  actuator wheels: DifferentialDrive;

  ai_model planner: LLM { provider: "mock"; model: "patrol"; }

  safety {
    max_speed = 0.5 m/s;
    stop_if lidar.nearest_distance < 0.5 m;
  }

  behavior patrol() {
    loop every 100ms {
      let scan = lidar.read();
      let proposal = planner.reason(prompt: "Plan motion", input: scan);
      let action = safety.validate(proposal);
      wheels.execute(action);
    }
  }
}

---

Learn by example (basics → end-to-end)

Hub: examples/README.md — full ladder, topic map, and CI regression.

New to Spanda? Pick your style (full list: Tutorials index):

• Spanda for Dummies — plain English, ~45 min read, cheat sheet
• Spanda 101 — ten hands-on lessons with exercises (~3 hours)

Progressive code examples live under examples/basics/:

spanda check examples/basics/01_minimal_robot.sd
spanda run examples/basics/02_sensors_and_safety.sd
spanda test examples/basics/07_in_language_tests.sd

Tier	Directory	Topics
Basics	examples/basics/	Robot syntax, safety, control flow, Result/Option, traits, async, contracts
Integration	examples/integration/	Triggers, concurrency, hardware verify
End-to-end	examples/end_to_end/	Full patrol package, record/replay mission
Packages	examples/packages/	Manifests, adapter packages, local deps — README
By feature	examples/features/	One file per capability — README

After the ladder, try examples/showcase/killer_demo.sd and killer-demo.md.

---

Core commands

Type-check

spanda check src/main.sd
spanda check --project          # check entire project
spanda check src/main.sd --json # machine-readable diagnostics

Run simulation

spanda run src/main.sd
spanda sim src/main.sd          # verbose simulation output

Hardware verification

spanda verify src/main.sd
spanda verify src/main.sd --target RoverV1
spanda verify src/main.sd --all-targets --json

Add a deploy target to your program first:

hardware RoverV1 {
  memory: 4 GB;
  sensors [ Lidar ];
  actuators [ DifferentialDrive ];
}

deploy MyRover to RoverV1;

Optional: record certification intent for verify/CI (metadata only — not a runtime safety proof):

certify ISO13849 {
  level PLd;
}

OTA deployment planning

Plan and simulate rollouts from deploy blocks in your program:

spanda deploy plan examples/robotics/ota_deployment.sd
spanda deploy rollout examples/robotics/ota_deployment.sd --strategy canary --canary-percent 25 --dry-run
spanda deploy rollout examples/robotics/ota_deployment.sd --version 1.2.0
spanda deploy rollback examples/robotics/ota_deployment.sd
spanda deploy status

Rollout state is stored in .spanda/deploy-state.json (override with SPANDA_DEPLOY_STATE).

Remote rollout pushes updates to on-device deploy agents:

spanda deploy agent start --target RoverProgram@JetsonOrin --bind 0.0.0.0:8765
spanda deploy agent register RoverProgram@JetsonOrin http://192.168.1.50:8765
spanda deploy rollout examples/robotics/remote_ota_deployment.sd --remote --version 1.3.0

See robotics-platform.md for missions, fleets, safety zones, and Nav2 integration.

Run tests

spanda test

Add test blocks in your .sd files:

test "safety stops near obstacles" {
  // test body
}

Format and lint

spanda fmt src/main.sd
spanda lint src/main.sd

Trace runtime behavior

Debug scheduler, task, and trigger execution with trace flags:

spanda run src/main.sd --trace-scheduler --trace-tasks
spanda run src/main.sd --trace-triggers --trace-events
spanda sim src/main.sd --replay --trace-scheduler

Trace output appears in the runtime log stream with prefixes like trace-scheduler:, trace-task:, and trace-trigger:.

Record and replay mission traces

Record a simulation run, then inspect, verify, or play it back:

spanda sim examples/realtime/deterministic_replay.sd --record
spanda replay mission.trace
spanda replay mission.trace --deterministic   # re-run source and verify frame parity
spanda replay mission.trace --playback --from T+00:30

Real-time telemetry and wall-clock scheduling:

spanda run examples/realtime/deadline_tasks.sd --trace-realtime --metrics-json
spanda sim examples/realtime/latency_budget.sd --wall-clock

See realtime.md, replay.md, and reliability.md.

---

Try the showcase examples

The examples/showcase/ directory contains curated demos for v0.4:

spanda check examples/showcase/rover_navigation.sd
spanda run examples/showcase/rover_navigation.sd
spanda verify examples/showcase/hardware_compatibility.sd --json
spanda check examples/showcase/ai_safety_violation.sd   # expect compile error

Example	Command to try
rover_navigation.sd	spanda run examples/showcase/rover_navigation.sd
warehouse_robot.sd	spanda run examples/showcase/warehouse_robot.sd
hardware_compatibility.sd	spanda verify examples/showcase/hardware_compatibility.sd
communication_demo.sd	spanda run examples/showcase/communication_demo.sd
digital_twin_demo.sd	spanda run examples/showcase/digital_twin_demo.sd
assurance/rover.sd	spanda demo assurance
self_healing/rover.sd	spanda demo self-healing
continuity/warehouse.sd	spanda demo continuity
readiness/rover.sd	spanda readiness examples/showcase/readiness/rover.sd --json
triggers_demo.sd	spanda run examples/triggers_demo.sd --trace-triggers

Triggers and concurrency

Reactive programs use unified triggers — see triggers.md:

spanda run examples/triggers_demo.sd --trace-triggers
spanda run examples/concurrency.sd --trace-scheduler --trace-tasks
spanda fleet run examples/communication/multi_robot_fleet.sd
spanda fleet orchestrate examples/robotics/fleet_management.sd

Real-time, reliability, and regex

Deadline-aware tasks, watchdogs, and degraded modes:

spanda check examples/realtime/deadline_tasks.sd
spanda run examples/realtime/watchdog.sd --trace-realtime
spanda run examples/realtime/degraded_mode.sd

Regex triggers and validation:

spanda check examples/regex/basic_regex.sd
spanda run examples/regex/command_trigger.sd --trace-triggers

Killer demo (5 minutes)

Flagship safety walkthrough — compile-time AI gate, hardware verify, and sim:

spanda check examples/showcase/killer_demo.sd
spanda verify examples/showcase/killer_demo.sd --json
spanda sim examples/showcase/killer_demo.sd

Full script: killer-demo.md

---

Build your first robot (step by step)

Step 1 — Minimal robot

Start with examples/hello_world.sd or examples/rover.sd:

spanda check examples/rover.sd
spanda run examples/rover.sd

Step 2 — Add safety

Study examples/lidar_avoidance.sd for stop_if and emergency stop patterns.

Step 3 — Add AI with safety gate

Study examples/showcase/rover_navigation.sd:

spanda run examples/showcase/rover_navigation.sd

The agent proposes actions; safety.validate() gates them before wheels.execute().

Step 4 — Verify hardware fit

Study examples/showcase/hardware_compatibility.sd:

spanda verify examples/showcase/hardware_compatibility.sd --json

Step 5 — Package your project

spanda init warehouse_bot
cd warehouse_bot
# edit src/main.sd
spanda build
spanda test

---

TypeScript fallback (no Rust build)

If you have not built the native CLI, the npm wrapper falls back to the TypeScript interpreter:

npm run spanda -- check examples/rover.sd
npm run spanda -- run examples/rover.sd

Hardware verification (spanda verify) uses the native Rust CLI when built; otherwise the npm wrapper runs the TypeScript hardware verify fallback (sensors, connectivity, timing, AI models, topic bandwidth, and simulate faults).

---

Web playground

npm run build:wasm
npm run web:dev

Open http://localhost:5173 to type-check and run programs in the browser.

---

GPS, connectivity, and geofencing

Spanda programs can declare wireless requirements, geofence zones, and failover policies at module scope, then react with on gps.lost, on geofence Zone exited, and similar triggers.

spanda check examples/connectivity/gps_navigation.sd
spanda check examples/connectivity/geofence_safety.sd
spanda verify examples/connectivity/connectivity_hardware_verify.sd --target RoverV2

See positioning.md, connectivity.md, and geofencing.md for syntax and verification details. The TypeScript parser, interpreter, and verify fallback mirror the Rust core for these constructs.

---

Language Server (LSP)

Build the LSP for editor integration:

npm run build:rust
npm run build --workspace=@spanda/lsp

Spanda includes a first-party VS Code extension at editor/vscode with bundled LSP, verify diagnostics, deploy-target autocomplete, and DAP debugging. CI Integration packages the VSIX on every main push (vscode-extension job); path-filtered checks also run via .github/workflows/vscode-extension-ci.yml when extension or LSP files change.

Editor support (v0.4)

Capability	Status
Syntax highlighting	Bundled TextMate grammar in VS Code extension
Autocomplete	LSP — symbols, comm keywords, transports, hardware profiles
Diagnostics	LSP — type-check + hardware verify + verification quick-fixes
Go to definition	LSP
Format on save	LSP textDocument/formatting
Debug (DAP)	VS Code extension — behavior, task every, every triggers
VS Code extension package	Experimental — local VSIX or Extension Development Host; Marketplace pending

To configure VS Code manually, add to .vscode/settings.json:

{
  "spanda.languageServerPath": "${workspaceFolder}/packages/lsp/dist/server.js"
}

To build the extension locally:

cd editor/vscode
npm install
npm run build

Then run it in VS Code Extension Development Host, or install a local VSIX:

./scripts/verify_vscode_vsix.sh
code --install-extension editor/vscode/spanda-vscode-0.1.0.vsix

See debugging.md for the DAP workflow.

---

Live AI and IoT (optional)

When API keys or env flags are set, Spanda calls real providers via the Python bridge; otherwise mock backends apply.

export OPENAI_API_KEY=sk-your-key
./scripts/live_ai_golden_path.sh

export SPANDA_LIVE_MODBUS=1
./scripts/live_iot_golden_path.sh

Guides: live-ai-provider.md · iot.md

---

Platform packages and golden paths

For multi-package projects (GPS, MQTT, fleet, ledger):

cd examples/showcase/autonomous_rover
spanda install
spanda verify src/rover.sd
spanda run src/rover.sd --trace-providers

World-model belief workflow:

spanda check examples/showcase/world_model_patrol.sd
spanda run examples/showcase/world_model_patrol.sd

Experimental Tier 3 CI scripts (MQTT, twin cloud, LLVM, cpp-native): tier-3-golden-paths.md

Platform guides: how-packages-work.md · how-providers-work.md · how-runtime-resolution-works.md

---

Project configuration (optional)

Multi-file TOML configuration for fleets, devices, providers, health, readiness, and assurance thresholds. The resolver merges spanda.toml, [extends] layers, and fragment files into ResolvedSystemConfig consumed by verify, run, readiness, and replay.

spanda config validate
spanda config resolve --json
spanda config report --network
spanda device discover --subnet 192.168.1.0/24
spanda device inspect camera-front-001
spanda device-tree graph --json
spanda map verify rover.sd --config spanda.toml
spanda verify rover.sd --config spanda.toml
spanda readiness rover.sd --config spanda.toml

Warehouse example fixture: crates/spanda-config/tests/fixtures/warehouse/

Guides: configuration.md · cascading-config.md · device-tree.md · config-validation.md

---

Verification & health (optional)

Health checks, fleet require clauses, and kill switch wiring:

spanda verify examples/hardware/capability_verification.sd --health
spanda health robot examples/hardware/capability_verification.sd --json
spanda sim rover.sd --inject-health-faults

Guides: health-checks.md · kill-switch.md · capability-traceability.md

---

Mission assurance (optional)

Mission-grade mission assurance: knowledge models, state estimation, anomaly detection, prognostics, mitigation, resilience, and assurance evidence.

spanda demo assurance

Or step through the showcase rover:

spanda check examples/showcase/assurance/rover.sd
spanda assure examples/showcase/assurance/rover.sd --json
spanda anomaly scan examples/showcase/assurance/rover.sd
spanda state estimate examples/showcase/assurance/rover.sd
spanda prognostics examples/showcase/assurance/rover.sd
spanda mission verify examples/mission/mission_assurance.sd
spanda resilience check examples/showcase/assurance/rover.sd
spanda mitigation plan examples/showcase/assurance/rover.sd
spanda readiness examples/showcase/assurance/rover.sd --target RoverV1 --json

Topic examples:

Directory	Guide
examples/assurance/	mission-assurance.md
examples/anomaly/	anomaly-detection.md
examples/diagnostics/	diagnostics.md
examples/prognostics/	prognostics.md
examples/resilience/	resilience.md
examples/mission/	mission-verification.md

Learned anomaly with optional ONNX: SPANDA_ANOMALY_ONNX_MODEL_PATH=/path/to/model.onnx — see anomaly-detection.md.

Operational readiness (composes with assurance): readiness.md

---

Self-healing & recovery (optional)

Safety-first recovery: detect → diagnose → plan → validate → execute → verify → audit. Policies declare conditional actions; the runtime never bypasses safety validation or operator approval.

spanda demo self-healing

Or step through the showcase rover:

spanda check examples/showcase/self_healing/rover.sd --readiness-json
spanda heal examples/showcase/self_healing/rover.sd
spanda recover examples/showcase/self_healing/rover.sd --failure gps
spanda recovery knowledge examples/showcase/self_healing/rover.sd
spanda recovery plan examples/showcase/self_healing/rover.sd --failure gps
spanda recovery simulate examples/showcase/self_healing/rover.sd --failure gps
spanda recovery explain examples/showcase/self_healing/rover.sd --failure gps
spanda recovery graph examples/showcase/self_healing/rover.sd
spanda recovery playbooks
spanda sim examples/showcase/self_healing/rover.sd --inject-failure gps
spanda analyze-failure examples/showcase/self_healing/rover.sd --with-recovery

Recovery Orchestrator (plan/simulate/execute, graph, playbooks, predictive, persisted history): recovery-orchestrator.md · recovery-api.md · recovery-sdk.md · Control Center Recovery tab

Fleet recovery with mesh relay (SPANDA_FLEET_MESH_URL): self-healing.md · fleet-distributed.md · examples/showcase/fleet_recovery/

Multi-process field validation (agents + mesh + recovery/continuity): ./scripts/fleet_field_validation.sh · examples/showcase/fleet_distributed/

---

Mission continuity (optional)

Checkpoint resume, takeover, delegation, and succession when a robot or fleet member fails mid-mission. Pair continuity_policy with fleet programs for takeover mode inference and successor ranking.

spanda demo continuity

Or step through the warehouse showcase:

spanda continuity examples/showcase/continuity/warehouse.sd \
  --failed ScannerAlpha --progress 72 --trigger robot_failed
spanda takeover examples/showcase/takeover/patrol.sd --failed RoverA
spanda delegate examples/showcase/delegation/survey.sd --failed SurveyBot --to RelayBot
spanda succession examples/showcase/fleet_succession/delivery.sd --scope fleet
spanda check examples/showcase/continuity/warehouse.sd --readiness-json

Guide: mission-continuity.md · Package: spanda-mission-continuity (assurance.continuity) · Examples: examples/showcase/continuity/

---

Distributed decisions (optional)

Hierarchical autonomy (brain / spinal cord / reflex): reflex safety, local bounded autonomy, fleet coordination, and control-center governance. Declare per-entity authority, local decision trees, and offline policy bounds.

spanda decision list examples/showcase/distributed_decisions/main.sd
spanda decision inspect examples/showcase/distributed_decisions/main.sd --entity Rover001
spanda decision simulate examples/showcase/distributed_decisions/main.sd --offline
SPANDA_DECISION_TRACE=1 spanda sim examples/showcase/distributed_decisions/main.sd --record
spanda decision trace mission.trace

Guide: distributed-decisions.md · Examples: examples/showcase/distributed_decisions/

---

Cognitive & Resilience Architecture (optional)

Extends distributed decisions with reflex arcs, homeostasis, platform immunity, sensory fusion, attention, operational memory, habituation, damage-risk modeling, adaptive recovery, and maintenance windows — all entity-integrated.

spanda reflex list
spanda reflex simulate emergency
spanda homeostasis check --json
spanda immunity quarantine
spanda fusion analyze
spanda alerts analyze
spanda recovery confidence

Language policies (optional in .sd programs):

homeostasis_policy PlatformStability {
    metric cpu_pct;
    metric memory_pct;
}

attention_policy MissionFocus {
    rule boost_critical_health;
}

Control Center Cognitive & Resilience tab (Health & incidents group) loads live data from /v1/autonomy/* and per-entity /v1/entities/{id}/autonomy.

Guide: cognitive-resilience-architecture.md · Maturity: cognitive-resilience-maturity.md · Smoke: ./scripts/cognitive_resilience_smoke.sh

---

Documentation

Generate API docs from .sd source (JavaDoc-style /// comments are included):

spanda doc src/main.sd
spanda doc --html src/main.sd --out api.html
spanda doc examples/ --out target/api-docs

View CLI manual pages:

spanda man              # list commands
spanda man verify       # man-page style help
spanda man run --roff   # roff for Unix man viewers

Full language reference and topic guides:

• language-reference/ — syntax, types, agents, safety, packages
• spanda-reference.md — generated keywords, stdlib, builtins
• man/ — all CLI man pages

Regenerate reference and man pages after compiler changes:

python3 scripts/generate_spanda_reference.py
cargo doc --workspace --no-deps   # Rust crate API docs

---

Platform maturity (experimental)

Adoption and operations tooling — graph, explain, trust, deployment gates, policy engine:

spanda demo maturity
./scripts/maturity_smoke.sh
spanda readiness examples/showcase/policy/warehouse.sd --policy WarehousePolicy
spanda verify examples/showcase/policy/warehouse.sd --policy WarehousePolicy

See platform-maturity-roadmap.md · policy-engine.md.

---

Control Center (enterprise operations)

Stable E1–E4 control plane for fleet operators. Full reference: control-center.md · enterprise-operations-roadmap.md.

Start the API and embedded UI

# Optional but recommended — generate with: spanda control-center api-key generate --export
export SPANDA_API_KEY="my-local-dev-key"

# Installed spanda
spanda control-center serve --bind 127.0.0.1:8080

# Release build (cargo build -p spanda --release)
./target/release/spanda control-center serve --bind 127.0.0.1:8080

# Active development
cargo run -p spanda -- control-center serve --bind 127.0.0.1:8080

Open http://127.0.0.1:8080 for the embedded Control Center UI, or use the React panel in @davalgi-spanda/web / the Tauri desktop shell (npm run control-center:desktop:dev with the API running). Full two-terminal start and rebuild checklist: control-center.md — Local dev: start & rebuild.

API keys: Run spanda control-center api-key generate --export to create a token, set SPANDA_API_KEY on the server, and use the same value as Authorization: Bearer … for mutations. In the embedded UI you can paste the token and opt in to Remember on this browser (localStorage, per host:port). OIDC SSO and production hardening (hashed keys, session JWTs, optional read-auth): authentication.md. Quick reference: control-center.md — Authentication & API keys. Persistence issues: troubleshooting.md — Control Center. If api-key generate errors, see troubleshooting.md.

Remote API from the CLI (no server required on the client machine):

export SPANDA_CONTROL_CENTER_URL=http://127.0.0.1:8080
export SPANDA_API_KEY=my-local-dev-key
spanda control-center status
spanda control-center status --discover
spanda control-center stop
spanda control-center dashboard
spanda control-center drift --baseline-id <snapshot-id>
spanda control-center drift scan
spanda control-center incidents list
spanda control-center api get /v1/sre/summary

Rate limits, WebSocket streaming, SIEM audit export, scheduled reports, and production policy env vars: control-center.md · control-center-rate-limits.md · stable-hardening-enterprise-ops.md.

Production policy (optional)

export SPANDA_PRODUCTION_POLICY=production   # enables OTA certify + discovery TLS defaults
export SPANDA_OTA_REQUIRE_CERTIFY=1
export SPANDA_DISCOVERY_REQUIRE_TLS=1
export SPANDA_REPORT_SCHEDULE_INTERVAL_SECS=3600
export SPANDA_API_KEY_PEPPER="$(openssl rand -hex 32)"      # hashed file-backed API keys
export SPANDA_SESSION_JWT_SECRET="$(openssl rand -hex 32)"  # OIDC session JWT signing
export SPANDA_API_REQUIRE_AUTH_READS=1                        # when API is network-exposed

See authentication.md for the full production auth checklist.

Smoke test (API + desktop compile check)

./scripts/enterprise_ops_smoke.sh
./scripts/control_center_desktop_smoke.sh
./scripts/security_audit_prep.sh
./scripts/verify_sdk_publish_ready.sh
./scripts/verify_desktop_release_ready.sh

Field soak and stable promotion

Enterprise operations pillars are Stable in feature-status.md. Production SDK 0.4.2 and desktop 0.6.3 (desktop-v0.6.3) are published. Remaining organizational gates (not tier blockers): 30-day field pilot (field-soak-gate.md) and third-party security audit sign-off (security-audit-third-party.md). See enterprise-ops-stable-promotion.md.

Desktop shell

Dev (API must be running separately):

# Terminal 1 — API (see above)
# Terminal 2 — Tauri dev shell (requires npm install + Tauri prerequisites)
npm run control-center:desktop:dev

Point the UI at a different API URL with VITE_CONTROL_CENTER_URL=http://host:port.

Check the running version: sidebar shows vX.Y.Z, or spanda control-center --version / spanda control-center status.

Production install (macOS): download the 0.6.3 installer from the GitHub Release for tag desktop-v0.6.3 (.dmg or workflow artifact if unsigned). Start the API with spanda control-center serve, then launch the desktop app. Maintainer release process: desktop-release-runbook.md · control-center-versioning.md.

Official SDKs

Start Control Center with a program, then use one SDK that matches your app’s language — all three are thin HTTP clients over the same API (no duplicated platform logic). Which to pick: sdk.md — Why three SDKs?. Demo serve examples and --config / --program combinations: control-center.md — Run with --config and --program.

cargo run -p spanda -- control-center serve \
  --bind 127.0.0.1:8080 \
  --program examples/robotics/rover.sd

Rust (crates/spanda-sdk):

use spanda_sdk::SpandaClient;
let client = SpandaClient::local();
let report = client.readiness("rover.sd")?;

Python (pip install spanda-sdk or sdk/python from source):

pip install spanda-sdk
export SPANDA_CONTROL_CENTER_URL=http://127.0.0.1:8080
python -c "from spanda import SpandaClient; print(SpandaClient.local().readiness('rover.sd'))"

TypeScript (npm install @davalgi-spanda/sdk or build from sdk/typescript):

npm install @davalgi-spanda/sdk
# or from monorepo: npm ci --prefix sdk/typescript && npm run build --prefix sdk/typescript

import { SpandaClient } from "@davalgi-spanda/sdk";
const report = await SpandaClient.local().readiness("rover.sd");

Full guides: sdk.md · control-center-api.md · sdk-publishing.md (maintainers: PyPI/npm release)

Legacy Python client (enterprise ops)

pip install -e 'packages/sdk-python[stream]'
export SPANDA_CONTROL_CENTER_URL=http://127.0.0.1:8080

See packages/sdk-python/README.md for drift, OTA, and SRE helpers (ControlCenterClient).

---

Next steps

• language-reference/ — structured language topics
• spanda-language.md — full language reference
• mission-assurance.md — knowledge, state, anomaly, resilience CLI
• readiness.md — operational go/no-go scoring
• killer-demo.md — 5-minute safety + verify walkthrough
• control-center.md — enterprise Control Center API and UI
• realtime.md — deadline-aware tasks and wall-clock mode
• replay.md — mission trace record and playback
• regex.md — regex literals and filters
• triggers.md — trigger-driven execution
• concurrency.md — tasks, spawn, channels, fleet CLI
• hardware-compatibility.md — deploy profiles
• architecture.md — how the compiler works
• health-checks.md — health checks and fleet requirements
• live-ai-provider.md — OpenAI, Anthropic, ONNX live paths
• health-checks.md — health checks and fleet require clauses
• testing.md — expect_compile_error and test CLI
• verification-diagnostics.md — structured verification output
• typed-handler-io.md — handler return types
• registry.md — hosted registry and publish mirror
• feature-status.md — what is stable vs experimental
• known-limitations.md — mock backends, live env flags, organizational gates
• troubleshooting.md — live AI/IoT/ROS2 setup and symptom fixes

---

Troubleshooting

Problem	Solution
spanda: command not found	Run npm run build:rust or use ./target/release/spanda
verify not available	Run npm run build:rust for the native CLI, or use the npm wrapper — TS verify fallback covers most checks when the CLI is missing
pip install spanda-sdk / externally-managed-environment	Use a venv — troubleshooting.md — Python SDK
cargo add spanda-sdk could not determine package	Pass --package <crate> from the monorepo root — troubleshooting.md — Rust SDK
Compile error on wheels.execute(proposal)	Expected — use safety.validate(proposal) first
Tests fail after clone	Run npm install then npm run build:rust before npm test
Mock AI / in-memory transport warnings	Expected by default — set live env flags or SPANDA_QUIET=1 — known-limitations.md

Full symptom index: troubleshooting.md.

This site is open source. Improve this page.