Skip to main content
Ara has four major layers:
  1. Client product (app.ara.so, web/desktop)
  2. Cloud control plane (Ara-backend FastAPI service)
  3. Sandbox execution plane (Blaxel sandboxes)
  4. Agent runtime (inside each sandbox)

​
High-level flow

Client (web, desktop, channel users)
  -> Ara Cloud API (auth/session/files/ws/mcp/usage)
    -> Blaxel sandbox (per user)
      -> Agent runtime (tools, skills, memory, channels)

​
Layer 1: product surface (app.ara.so)

  • Desktop-like UI, apps, chats, and file interactions
  • Calls cloud API for session and runtime operations
  • Uses realtime paths for chat and terminal
  • Displays and manages skills discovered from runtime storage

​
Layer 2: cloud control plane (Ara-backend/api)

The cloud API is the orchestration and policy layer:
  • Auth, billing, credentials, usage, and analytics
  • Session lifecycle (/session/start, /session/status, /session/stop)
  • WebSocket proxying (/ws/{session_id}, /session/terminal/{session_id})
  • File proxying (/session/files/*)
  • Skills management (/session/skills*)
  • Integration and MCP routing

​
Layer 3: sandbox execution plane

Each active user session maps to a dedicated sandbox:
  • Isolated filesystem and process space
  • Long-running runtime workers
  • Persistent workspace
  • Per-session runtime configuration injection

Sandbox deep dive

Runtime image, persistence model, and operational lifecycle.

​
Layer 4: agent runtime

The runtime handles autonomous behavior:
  • Agent loop and model/tool orchestration
  • Channel adapters (WhatsApp, Telegram, Linq, and more)
  • Skills loader + registry + manager tools
  • Memory files and context assembly
  • Subagent spawning and delegated execution

Runtime deep dive

Tool loop, skills precedence, and runtime contracts.

​
Message path (realtime)

1

Client connects

Client opens websocket to cloud API with JWT or gateway token.
2

Cloud API authenticates and routes

Session is resolved from cloud_sessions, then proxied into sandbox websocket.
3

Runtime processes request

Runtime decides model/tool actions, emits assistant frames, and writes outputs.
4

Cloud jobs persist telemetry

Message writer and observability jobs process frames for analytics and history.

​
Files and artifacts path

  1. Client requests file read/write through /session/files/*
  2. Cloud API validates user/session and path scope
  3. Request is executed inside sandbox filesystem
  4. Results stream back to client and can be referenced by later prompts

​
Why this architecture works

  • Clear separation between control plane and execution plane
  • Strong per-user isolation in sandbox layer
  • Runtime can evolve (skills, recursion, channels) without changing client contracts
  • Same core agent across app UI, APIs, and channel communications