Skip to content
CantelopBeta

Architecture

Cantelop follows the actor model: each Session is an addressable agent runtime with its own identity, process, and mailbox. You define its model, tools, and message behavior; Cantelop manages routing, isolation, and lifecycle.

An App packages your Edge API, session runtime, and environment. It can serve many independent Sessions, each representing a conversation or unit of work.

Releasing the Sandbox clears memory. The Session ID and Workspace survive.
  • Edge API receives HTTP requests, checks access, and dispatches messages.
  • Session handles messages one at a time in acceptance order. The same App-scoped ID reaches the same actor; different Sessions can run concurrently.
  • Sandbox runs one active Session in an isolated Linux environment with its own process and in-memory state.
  • Workspace holds persistent files at /workspace. Sessions can share these files while keeping separate runtime state.

The first message starts a Sandbox if needed. Each Session has one managed activity for long-running work, letting its mailbox handle further commands. Your code decides how queueing, steering, and cancellation work.

After work finishes, the Sandbox stays warm for the requested keep-alive period. Releasing it clears memory and temporary files. The Session ID and Workspace survive; your agent must persist and reload any conversation state it needs.

The CLI runs the App locally, deploys its API and runtime as one release, and manages configuration, Sessions, and logs.

See Sessions and messages, Workspaces, or the SDK architecture guide for more detail.