Architecture

Pokee Enterprise is a per-tenant runtime for long-running AI agents, not an LLM wrapper with a sandbox bolted on. Each tenant gets a private HTTPS endpoint, a fleet of persistent sessions, and the auth scheme that fits its security posture — bearer token by default, with mTLS, SSO, IP allowlists, and PrivateLink available on request. Inside, every session is an OS-isolated workspace where the agent runs your messages, accumulates state, and streams events back.

The structural choices behind this — and the four highlighted components in the diagram below — are explained on Why Pokee. For the full list of supported auth and network controls, see Authentication & access.

Session anatomy

Inside a tenant endpoint, every session is its own mount namespace with its own workspace. At creation time you can pin the session to an explicit file_access scope — paths outside it return ENOENT from both the agent and the file API (scoped file access). Two well-known paths matter beyond user files: .memory/ persists across sessions and pod restarts, and .pokee/ extends the agent's system prompt with tenant-specific context.

The agent never holds or sees integration credentials. Outbound calls leave the session through an egress proxy that lives outside the agent's reach; the proxy pulls the right credential from an encrypted vault and attaches it before the call exits the tenant boundary. The agent observes only its own request inputs and the API's response — never the bearer tokens, OAuth access tokens, or API keys that authorized them.

flowchart LR
  C["Your client"]

  subgraph Tenant["tenant.enterprise.pokee.ai · auth: bearer / mTLS / SSO"]
    direction TB
    subgraph Sess["Session · persistent sandbox · OS-isolated"]
      direction TB
      A["Agent
multi-step · streams events"]:::diff
      WS["Workspace
per-session read / write scope
OS-enforced (mount namespace)"]:::diff
      MEM[".memory/MEMORY.md
survives across sessions"]:::diff
      POKEE[".pokee/*.md
tenant agent context"]:::diff
      A --- WS
      WS --- MEM
      WS --- POKEE
    end
    Egress["Egress proxy
attaches credentials at the boundary"]
    Vault[("Secrets vault
encrypted credentials")]
    A -- "request (no creds)" --> Egress
    Vault -. credential .-> Egress
  end

  C == HTTPS ==> Tenant
  Egress -- "authenticated call" --> ExtAPI(["External API"])

  classDef diff fill:#eff6ff,stroke:#2563eb,color:#1e3a8a,stroke-width:2px;

Trust boundaries

Five concentric boundaries sit between a caller and the data inside a session. Each layer is enforced independently — a failure of one does not collapse the others.

flowchart TB
  Client(["Your client"])

  subgraph Region["Pokee region · pinned at provisioning"]
    direction TB
    subgraph Tenant["Tenant · isolated subdomain · scoped auth"]
      direction TB
      Vault[("Secrets vault")]
      subgraph Session["Session · OS mount namespace · sandboxed runtime"]
        direction TB
        Scope["Workspace within file_access scope
(read / write paths declared at session start)"]
      end
    end
  end

  Client == TLS 1.2+ ==> Region

Transport — TLS 1.2+ on every public connection. mTLS, IP allowlists, and PrivateLink are available on request (see Authentication & access).
Region — compute, storage, and inference are pinned to the region selected at provisioning. Data does not leave the region without an explicit contractual exception.
Tenant — each tenant gets its own subdomain, its own auth scope, and its own session pool. There is no cross-tenant API surface and no shared compute.
Session — every session runs in its own OS mount namespace and resource-limited runtime. Sessions cannot see each other's filesystems or processes.
File scope — a session's file_access declaration is enforced by the kernel; paths outside it return ENOENT to both the agent and the file API.

Request lifecycle

Sessions are created on demand and persist until you delete them. Messages stream as Server-Sent Events, but once a turn starts the agent runs to completion even if the client disconnects — reconnect or poll the session to retrieve the result.

sequenceDiagram
  autonumber
  participant C as Client
  participant API as tenant endpoint
  participant S as Session

  C->>API: POST /v1/sessions { file_access }
  API->>S: provision (mount ns scoped to file_access
.memory mounted)
  API-->>C: { session_id }

  loop one or more turns
    C->>API: POST /v1/sessions/{id}/messages
    API->>S: deliver
    Note over S: Agent runs to completion
even if the client drops
    S-->>API: agent events
    API-->>C: SSE stream
  end

  C->>API: GET /v1/sessions/{id}/files/{path}
  API-->>C: file contents

  C->>API: DELETE /v1/sessions/{id}
  API-->>C: 204  ·  .memory/ preserved for next session

See the quickstart for runnable examples, the API reference for endpoint details, and Why Pokee for the design rationale.