embodied-ai

embodied-ai is a local-first embodied agent runtime. The active architecture is the HFSM/config DSL described in docs/spec/.

Source of Truth

Read these first:

• docs/spec/embodied-ai-hfsm-dsl-spec.md

Active Layout

configs/              runtime v2, state, health, and plugin config
schemas/              JSON schema contracts for runtime v2 and v1 subcontracts
services/body/        Body runtime plus subsystems: Spine, Health, Trust, Audit, Communication, MCP, Documentation, Module Registry, Evolution, Identity, Self-Improvement
services/brain/       intelligence service: harness, chat/session execution, self-review/dreaming, backend routing
crates/embodied-memory-core/  Rust memory sidecar
containers/           checksum-pinned shared native media build payloads
security/             container vulnerability triage and provenance policy
modules/              manifest-backed plugin modules; self-contained containers
modules/hud/          HUD module service and assets
apps/hud/             HUD package boundary notes
tests/                pytest suite

Validation

.venv/bin/python -m pytest tests -q

Older v01/v02 tests are intentionally not the source of truth for new work.

Containers and deployment

Checked-in Compose and environment files are development templates. Production Compose authority, credentials, identities, memory, and artifacts belong under ~/apps/embodied-ai, never this source checkout. Production deploys only a complete immutable commit release with --no-build.

Container publication requires hardened startup/functional smokes, archive-based Trivy scanning, per-image CycloneDX SBOM and SLSA provenance, strict digest-bound OpenVEX policy, and independent registry manifest verification. See docs/container-release-policy.md and security/README.md.

HTTP Security

All non-health Body service endpoints are protected. Brain and other non-module service callers still use service-scoped bearer tokens plus replay headers:

• Authorization: Bearer <service-specific token>
• X-Embodied-Service: <service-id>
• X-Embodied-Timestamp and X-Embodied-Nonce on every authenticated request, including GET, HEAD, and WebSocket upgrade handshakes

Non-module principals use distinct tokens and route scopes: Brain uses BODY_BRAIN_TOKEN, Body MCP uses BODY_MCP_TOKEN, and direct operator tooling uses BODY_OPERATOR_TOKEN. Tokens are not interchangeable; valid credentials receive HTTP 403 when their principal lacks the requested method/path scope.

Modules do not use bearer tokens. Module manifests declare transport.auth.type: body_mtls; modules enroll with Body, persist their own private key locally, and reconnect with a Body-issued client certificate. The private key is never sent to Body. The enrollment bootstrap key or one-time token is valid only for claiming an allowed module slot, and enrollment requires HTTPS or a trusted TLS proxy.

When a TLS proxy terminates enrollment traffic, set BODY_TRUSTED_PROXY_CIDRS to the comma-separated CIDRs of the proxies that connect directly to Body. Forwarded TLS headers from all other peers are ignored. The trusted proxy must overwrite client-supplied forwarding headers; when a proxy chain appends values, Body treats the rightmost value as the immediate proxy's assertion. Never add private networks merely because they are private. Leave the setting empty when Body handles TLS directly. BODY_ALLOW_INSECURE_ENROLLMENT=true is only an explicit local-development escape hatch and defaults to false.

Runtime module calls prove possession of the module private key by signing the request method, path, timestamp, nonce, and body hash with the enrolled key. When Body runs behind an mTLS terminator, the terminator may instead verify the client certificate and forward it with a signed assertion using BODY_CLIENT_CERT_PROXY_HMAC_SECRET, or expose a verified TLS client-cert environment. Do not trust raw client-certificate headers from the public network. The default replay window is intentionally loose for Docker networking: 30 seconds timestamp skew and 60 seconds nonce TTL.

modules/ is the active package path for manifest-backed plugins. A plugin should be one self-contained container that owns its manifest, health, senses, events, appendages, and hardware/API integration. Do not split a plugin into a same-purpose proxy plus relay; grant the plugin only the specific host resources it needs.

/healthz remains unauthenticated for liveness checks. Host port mappings are preserved, so exposed services rely on these endpoint checks plus TLS for non-local or cross-machine traffic.

Operational notes:

• Body MCP is a privileged control surface. Bind it to a Tailnet IP or localhost with BODY_MCP_BIND_IP, require both its client-facing BODY_MCP_BEARER_TOKEN and Body-facing BODY_MCP_TOKEN, and leave BODY_MCP_DEV_MODE=false outside explicit local debugging.
• Body Trust stores replay nonces in SQLite. Set BODY_NONCE_DB_PATH to a shared local file for multi-worker deployments; otherwise it uses /tmp/embodied-ai/body-nonces.sqlite3.
• Body Trust stores module enrollment claims in SQLite. Set BODY_ENROLLMENT_DB_PATH to override /tmp/embodied-ai/body-enrollment.sqlite3.
• Body Trust stores its local CA in BODY_CA_DIR; set BODY_CA_KEY_PASSPHRASE to encrypt the CA private key at rest.
• Modules persist private keys and client certs in DAISY_IDENTITY_DIR, mounted from DAISY_IDENTITY_HOST_DIR in Compose.
• Local Compose enrollment uses the same secret under boundary-specific names: Body reads only BODY_MODULE_BOOTSTRAP_KEY from its server env file, while capability modules read only DAISY_BODY_BOOTSTRAP_KEY from module-enrollment.env. Claimed slots cannot be replaced with that key; use a one-time enrollment token for reenrollment.
• GET /body/security/preflight reports nonce-store configuration and module auth mode using the same protected API auth.
• Security audit events are emitted as JSON service logs with schema embodied.security_audit/v1, and recent entries remain available at GET /body/security/audit.