Skip to main content
Every active Ara session runs in an isolated sandbox environment.

​
Runtime layout

Key paths used by runtime and cloud APIs: 
/root/.ara/workspace/            # User workspace, channel state, runtime artifacts
/root/.ara/workspace/self-skills # Agent-created skills (SKILL.md per skill)
/root/.ara/runtime-config.json   # Runtime + channels + tool config
/tmp/runtime.log                 # Runtime process log

​
Session lifecycle

1

Start

Cloud API creates a session record and provisions a sandbox.
2

Inject config

Runtime config is updated with BYOK, channel settings, and MCP servers.
3

Boot runtime

Runtime gateway starts and websocket endpoints become available.
4

Operate

Messages, tools, files, and skills execute inside sandbox boundaries.
5

Stop

Session is torn down and marked stopped; runtime resources are released.

​
Why this sandbox model

  • Isolation: each user runtime is separated at process and filesystem level
  • Persistence: workspace survives restarts and reconnects
  • Low coupling: cloud plane can restart independently from sandbox runtime
  • Capability density: channels, tools, and browser execution share one local context

​
Filesystem guarantees

Cloud file routes enforce path constraints and avoid cross-user access. Agent operations are scoped to user runtime storage.

​
Networking and access

  • Client never connects directly to runtime internals
  • Cloud API authenticates and proxies websocket traffic
  • Runtime can reach external model providers and authorized MCP services

​
Operational notes

  • Runtime processes are health-checked before proxy routing
  • Session metadata tracks websocket connectivity and heartbeats
  • Background jobs handle telemetry, usage, and automation scheduling

Message and file flow

Follow the end-to-end path of requests, artifacts, and memory.