> ## Documentation Index
> Fetch the complete documentation index at: https://actelos.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# How Does cyrnel Work?

> A high-level description of the inner workings of cyrnel

Cyrnel is a single HTTP server that sits between AI applications (clients) and
the services those applications want to act on. Clients submit code, cyrnel runs
it inside a sandboxed environment, and tool invocations made from that code
are translated by adapter modules into calls to the real services.

```mermaid theme={null}
graph LR
    subgraph Clients [AI Applications]
        C1[Mobile App Chat Clients]
        C2[Desktop/CLI Agent]
        C3[Web Chat Clients]
    end

    Cyrnel[Cyrnel Server Instance]

    subgraph End_Servers [Service Layer]
        REST[REST APIs]
        DB[Databases]
        CLI[CLI Applications]
        Other[...]
    end

    C1 --- Cyrnel
    C2 --- Cyrnel
    C3 --- Cyrnel

    Cyrnel --- REST
    Cyrnel --- DB
    Cyrnel --- CLI
    Cyrnel --- Other
```

## Core Components

The cyrnel server is composed of three cooperating services.

### `Processes`

Owns process lifecycle, responsible for creating processes, scheduling and
terminating their execution, tracking state, and capturing outputs.

See [Processes](/cyrnel/docs/processes) for the full process model.

### `Services`

Owns the **service registry**, responsible for installing, updating, and
deleting services, retrieving service and tool data, and managing
configuration and encrypted secrets.

See [Services](/cyrnel/docs/services) and [Tools](/cyrnel/docs/tools) for the full
services model.

### `Modules`

Owns the **module registry**, responsible for installing, updating, and
deleting modules, Loading built-in and any custom modules and dispatching
commands to the different module types.

See [Modules](/cyrnel/docs/modules) for the full modules model.

The different types of modules play different roles in cyrnel;

* **Adapter modules**: Generate services and translate tool invocations into
  the right call to the right end service (HTTP, RPC, whatever the service
  speaks), and hold the per-service config and secret snapshots needed to do so.
* **Environment modules** execute submitted code and expose generated
  bindings so that code can discover services, fetch tool metadata, and invoke
  tools.

See [Adapter Modules](/cyrnel/docs/adapters-modules) and
[Environment Modules](/cyrnel/docs/environments-modules) for the full models.

This model keeps the running surface small and deterministic: a single source
of truth for "which environment runs new code", plus a known set of adapters
for outbound calls.

## Process Lifecycle

From the client's perspective, process execution is asynchronous. The client
creates a process and either gets a `pid` back immediately, or, with
`block: true`, waits until the process reaches `idle`. Outputs are retrieved
by `pid` from the `/processes/:pid/{output,stdout,stderr}` routes once the
process is idle.

```mermaid theme={null}
sequenceDiagram
    autonumber

    participant Client

    box Cyrnel Server
        participant API as HTTP API
        participant PS as ProcessService
        participant MS as ModuleService
        participant SS as ServicesService
        participant Env as Environment Module
        participant Adapter as Adapter Module
    end

    participant Service as End Service

    Note over API,Adapter: Process Execution
    Client->>API: POST /processes (code, options)
    API->>PS: create({ code, options })
    PS-->>API: pid
    API-->>Client: { pid }

    PS->>MS: execute({ eid: pid, code, options })
    MS->>Env: execute(input)
    Env-->>PS: emit stdout / stderr / output / state

    Env->>MS: invokeTool({ serviceId, toolId, parameters })
    MS->>SS: lookup service & tool (enabled?)
    SS-->>MS: adapter id
    MS->>Adapter: invoke({ serviceId, toolId, parameters })
    Adapter->>Service: native protocol call
    Service-->>Adapter: response
    Adapter-->>MS: result
    MS-->>Env: result

    Env-->>MS: ExecutionExitState (success / failed / timeout / canceled)
    MS-->>PS: exitState
    PS->>PS: state = idle, exitState = <value>

    Client->>API: GET /processes/:pid
    API-->>Client: process record
    Client->>API: GET /processes/:pid/output
    API-->>Client: structured output
```