Technical report

The local control plane: FastAPI, auth, and an unauthenticated stop

How voxyn exposes the neural pipeline over HTTP and WebSocket: bearer tokens for motion, raw intents beside natural language, metrics for operators, and emergency stop without a key.

Project voxyn Year 2025 Scope voxyn/api/server.py

Abstract

The reference server is built with FastAPI. A single NeuralPipeline instance lives on app.state; startup and shutdown hooks call pipeline.start() and stop(). Authenticated routes accept natural language (POST /command/text) or pre-structured JSON (POST /command/raw) that bypasses NLU. POST /emergency-stop is deliberately not behind bearer auth so a physical e-stop or trusted network path can always halt motors. Health, motors, sensors, and Prometheus text metrics expose observability. A /ws WebSocket streams sensor data and accepts typed command messages. Rate limiting and CORS are configured from settings. This note sketches that surface; it does not replace OpenAPI docs at /docs.

Keywords: FastAPI, robotics API, JWT, WebSocket, safety, observability

1. Trust boundaries

Commands that move hardware require a valid bearer token. Issuance is via POST /token using the project’s auth manager. The asymmetry—stop is open, move is not—mirrors physical robotics practice: anyone near the machine should be able to halt it.

Figure 1. Contrasting trust: motion commands vs. unconditional stop.

2. Text versus raw

/command/text runs the full skill → NLU → safety → HAL path. /command/raw forwards a dict to execute_raw for callers that already validated structure (e.g. tele-op or tests). Both are authenticated.

3. Real-time channel

The WebSocket accepts JSON message types for commands, raw intents, stop, and ping; the server can push results, sensor frames, and errors. This complements REST for continuous monitoring and low-latency interaction on the LAN.

Figure 2. Multiple clients can share one pipeline instance; ordering is defined by the async runtime.

References

[1] FastAPI. https://fastapi.tiangolo.com/

[2] voxyn voxyn/api/server.py.