Skip to main content
Ara treats messages and files as a unified execution substrate.
Messages and files data flow visual
Single data plane: conversation frames and artifacts move through the same runtime path.

​
Message flow

Primary realtime path:
  1. Client opens websocket to cloud API
  2. API authenticates with JWT or gateway token
  3. API proxies to sandbox websocket endpoint
  4. Runtime emits assistant frames
  5. Background writers persist message events and telemetry
This keeps runtime isolated while preserving low-latency interaction.

​
File flow

Primary file path:
  1. Client calls /session/files endpoints
  2. API validates path and session ownership
  3. Operation executes inside sandbox filesystem
  4. Response returns content or structured directory listing

​
Why co-locating messages and files matters

  • Agent can read/write artifacts referenced in conversations
  • File outputs can become future prompt context
  • Long-running tasks can checkpoint progress as files
  • Skills can encode file conventions and reusable structures

​
Path boundaries

File operations are constrained to allowed runtime paths and active user sessions, preventing cross-tenant leakage.

​
Observability

Message and file paths are instrumented through cloud jobs and logging so teams can debug:
  • dropped websocket sessions
  • malformed tool calls
  • file operation failures
  • skill execution regressions

Cloud API reference

Endpoints for sessions, websockets, files, skills, and usage.