How Ren works

Ren runs AI agents that do real work (writing code, calling APIs, managing data) inside isolated, managed compute. This page shows how the core pieces fit together and what happens when you run a session.

The stack

Ren is built from five primitives, layered from infrastructure up to the conversation:

┌─────────────────────────────────────────────┐
│  Session   │  A conversation between humans and agents
├─────────────────────────────────────────────┤
│  Project   │  What runs: agents, stores, permissions
├─────────────────────────────────────────────┤
│  Agent     │  A versioned template: prompt, model, skills, MCPs
├─────────────────────────────────────────────┤
│  Pod       │  A compute environment: server + sandbox
├─────────────────────────────────────────────┤
│  Sandbox   │  Isolated code execution
└─────────────────────────────────────────────┘

• A pod is the compute environment: a persistent server paired with an isolated sandbox where code runs. Every user gets a private pod; every organization gets a shared general pod.
• A project runs on a pod and binds what an agent can use: a primary agent and optional sub-agents, file stores, memory stores, permissions, and an optional git repo.
• An agent is a versioned template: a system prompt, a model, skills, MCPs, and a permissions policy. New sessions use the latest version; running sessions keep the version they started on.

Pods isolate compute and access

A pod is the ownership and isolation boundary. Each member is an owner (can change the pod) or a member (can use it). One pod’s sandbox cannot see another pod’s files or processes, so a shared org pod serves a whole team without leaking state between workloads.

Vaults attach to pods, so credentials are scoped by pod membership.

Sessions stay in sync

A session is a conversation scoped to a project on a pod. It moves through four states: idle (waiting for input), busy (the agent is working), waiting (the agent needs your approval or input), and error.

When you change something on a pod (update an agent, attach a vault, add a file store), the sandbox picks up the new configuration within seconds. Changes never interrupt a turn mid-execution: a running turn finishes on the old configuration, and the next turn uses the new one.

Credentials resolve at runtime

Agents often need credentials (API keys, OAuth tokens, database passwords) to call external services. Ren never puts secrets in prompts or configuration. Instead they live in vaults, encrypted at rest, and are injected into the sandbox only at execution time.

When a session starts, Ren collects every credential the project’s agents, skills, and MCPs declare they need, then checks the pod’s vaults for matching values. Anything missing is flagged before the agent runs, so you find out up front instead of mid-conversation.

A session, end to end

1. Start. You send a message. Ren resolves the project, its agents, and the pod.
2. Credential check. Ren collects required credentials and checks the vaults. Missing ones are surfaced before the agent starts.
3. Run. The agent’s prompt, model, skills, and MCPs load. The model reasons, calls tools, and produces output. Credentials are available in the sandbox but never appear in the conversation.
4. States. The session moves through idle → busy → waiting → idle as the agent works and pauses for input.
5. Finish. When the task is done, the session returns to idle, ready for the next message. On failure it enters error, and you can retry or inspect the logs.