# Cayu

[Find public concepts](https://github.com/cayu-dev/cayu/blob/main/docs/public-concepts.md) ·
[Run the example](https://github.com/cayu-dev/cayu/blob/main/examples/application/README.md)

Cayu is a Python runtime for long-running agents: durable sessions that survive
restarts and redeploys, human approval before side effects, spend caps enforced
before each model call, and multi-agent collaboration.

Start with the installed guides: `cayu guide untrusted-code` to run untrusted
code with controlled filesystem and network access, `cayu guide external-agents`
to run Claude Code or Codex as a step in your app, and `cayu guide long-running`
for approvals, timers, retries and recovery. `cayu guide --help` lists every topic.

| Capability | Cayu parts |
| --- | --- |
| Durable sessions and recovery | `SQLiteSessionStore` or `PostgresSessionStore` (`cayu.storage`) with `ResumeRequest`; `ExecutionProfilePolicy` (`cayu.runtime`) governs resumes on a new build |
| Approval before side effects | `ToolPolicy` returning `ToolPolicyDecision.REQUIRE_APPROVAL` (`cayu.tools`), resolved through `cayu.approvals` |
| Spend caps | `BudgetLimit` per request and `BudgetPolicy` per app (`cayu.budgets`), checked before each model call |
| Timers and background work | `TaskStore` workers and `TaskSchedulePolicy` for scheduled follow-ups (`cayu.tasks`) |
| Multi-agent collaboration | `SubagentTool` (`cayu.tools`), forks, and participants with durable requests (`cayu.collaboration`) |
| Claude Code or Codex runs | `run_external_agent` with `ClaudeAgentAdapter` or `CodexAgentAdapter` (`cayu.external_agents`, extras `cayu[claude-agent-sdk]` and `cayu[codex]`) and a launcher such as `local_agent_launch`, recorded as sessions with usage and deadlines; see `cayu guide external-agents` |

Cayu is Python only and is not a graph DSL: agents, tools and workflows are
ordinary Python. It is not only a hosted service: run it on your own
infrastructure or deploy to the optional Cayu Cloud.

Cayu is open source. Build your agent's harness from Python components and
defaults: model providers, context, tools, integrations, knowledge, memory,
policies, domain logic and verification. Choose the capabilities your job
needs, then evaluate and operate the resulting agent on your infrastructure or
with optional Cayu Cloud.

The integrated runtime carries that work through model and tool calls, durable
sessions, task dispatch, leased workers, resumable workflow steps, approvals and
recovery. Applications can use those execution capabilities directly without a
separate workflow engine.

## Framework, harness, runtime and agent

| Term | Role |
| --- | --- |
| Framework | Cayu's Python APIs, components and defaults for building and running agents |
| Harness | The domain-specific system you assemble: context, tools, memory, policies, domain logic and verification |
| Runtime | The framework's execution machinery for sessions, state, authority, workers, budgets and recovery |
| Agent | The resulting application that performs a defined job |
| Cloud | Optional deployment and shared operation of agents built with the framework |

Applications own their user interface, authentication, business authorization,
domain rules and completion criteria. See the [public concepts and source
map](https://github.com/cayu-dev/cayu/blob/main/docs/public-concepts.md) for the
components to build with.

## Why we built Cayu

We built Cayu while developing domain-specific agents that needed to carry
consequential work through model calls, tools, human decisions and failures.
Those applications needed both a configurable harness and dependable execution.

We began by building agents with SDKs and frameworks including the Claude Agent
SDK, Mastra, and LangGraph. They helped us implement the model-and-tool loop
quickly. Production quality required deeper control of the loop itself: context
assembly, model and tool invocation, output validation, and failure handling.

Production quality also depended on everything around that loop: scheduling,
durable state, credentials, execution environments, human intervention,
recovery, cost attribution, and evaluation. Cayu gives applications control of
that entire agent execution lifecycle.

## Why Cayu

Agent prototypes are easy to start. Production failures happen at the
boundaries:

- a process dies after a side effect but before state is recorded;
- a model requests a valid tool with the wrong authority;
- a run needs human input or approval halfway through;
- context grows until a provider rejects the next request;
- retries, forks, or subagents lose cost and causal attribution;
- operators cannot reconstruct what happened from prompt text alone; or
- evals test final prose while missing the runtime trajectory.

Cayu treats these as runtime contracts. Important actions become structured
events; tool authority and recovery are explicit; configured durable stores let
transcripts and checkpoints survive process boundaries; and the same public
seams support local development, tests, Developer dashboard inspection, and hosted
deployments.

## What Cayu provides

| Need | Framework components |
| --- | --- |
| Models and the agent loop | Provider adapters, reasoning controls, structured output, validation and bounded repair |
| Provider flexibility | OpenAI API, experimental OpenAI subscription login, Anthropic, Bedrock, Vertex, OpenAI-compatible APIs |
| Tools and integrations | Typed Python tools, MCP, capability discovery, application services and workflow composition |
| Web research and browsers | Search/fetch adapters, stateful browser tools and application-selected execution backends |
| Context and memory | Token counting, projection, compaction, overflow recovery and prompt-cache-aware strategies |
| Reviewed knowledge | Durable entries, approval state, keyword/vector retrieval and recall tools |
| Long-term recall | Bounded knowledge/transcript sources, deterministic fusion, exact locators and coverage |
| Multi-agent work | Subagents, delegation, forks, participants and durable peer requests |
| Workspaces and artifacts | Files, execution runners, workspace lifecycle, durable artifacts, vaults and egress |
| Verified completion | Work contracts, proposal evidence, independent acceptance and repair decisions |
| Evals and improvement | Runtime tests, production-session promotion, durable evals, replay, comparison and CI reports |
| Git and GitHub delivery | Governed repository changes, commits, pull requests and delivery receipts |
| Development and deployment | Project scaffolding, application factories, process roles and optional Cloud deployment |
| Operations | FastAPI server API and the packaged Developer dashboard for sessions, workflows, usage and evals |

### The integrated durable runtime

The same framework provides the execution contracts behind those capabilities:

- durable sessions, transcripts, events, checkpoints, resume and interruption;
- controlled tool effects, policies, approvals and idempotency identities;
- human-input checkpoints, approval resolution and manual recovery;
- task dispatch, worker ownership, resumable workflows and child-session lineage;
- usage accounting, run limits, budgets, pricing and causal attribution; and
- execution admission, recovery and reconciliation of uncertain external effects.

Configure the stores, adapters, policies and execution boundaries for your job.
Native Python tools are trusted application code; configured isolation and
external receipts determine the guarantees at the application boundary.

## Verify the runtime

Want executable evidence before adopting Cayu? The [runtime qualification guide](https://github.com/cayu-dev/cayu/blob/main/docs/runtime-qualification.md)
maps tool roundtrips, durable continuation, approval gating, and reviewed-proposal
binding to existing tests. It provides a pinned installed-wheel setup, a small
credential-free acceptance plan, the restartable support integration, and broader
release qualification, with report interpretation and coverage limits.

## Quickstart

Need a non-coding agent that survives restarts and waits for approval? Follow the
[restartable support-agent example](https://github.com/cayu-dev/cayu/blob/main/src/cayu/guides/order-support.md).
It investigates an order, asks for clarification, proposes a replacement, and
waits for verified representative approval before executing it. The guide and
executable ship with Cayu:

```bash
cayu guide order-support
python -m cayu.examples.order_support --help
```

For a model-only agent, start with the generated project below.

### Start a project

The generated project is the recommended path for both humans and coding
agents. Cayu requires Python 3.11 or newer.

You can give a coding agent one request: “Run `pip install cayu` and create a
code review agent.”

```bash
pip install cayu pytest
cayu new myagent
cd myagent

cayu inspect --json
cayu check --fail-on warning --json
pytest
cayu eval run

# After configuring the provider through configuration/settings.py or CAYU_PROVIDER:
python run.py --message "Review this change."
```

When PyPI has a newer Cayu release than the one installed, `cayu new` prints both
versions and the command that scaffolds with the latest release
(`uvx --from 'cayu==X.Y.Z' cayu new ...` with your arguments). In a terminal it
asks before continuing; otherwise it warns on stderr and continues, and `--json`
adds a `newer_release` field. The check waits at most about two seconds, runs at
most once a day, and stays silent when PyPI is unreachable. Set
`CAYU_NO_VERSION_CHECK=1` to turn it off.

For a portable operator snapshot that performs no agent, tool, recovery, repair,
or live-provider work, run `cayu doctor --bundle cayu-support.zip`. The
command reuses maintained-service diagnostics when selected and forces
CayuApp and project control-plane stores backed by the built-in SQLite and
PostgreSQL implementations into diagnostic read-only validation without creating
or migrating them. Session history is excluded unless you
explicitly repeat `--session`. See
[Diagnostic support bundles](https://github.com/cayu-dev/cayu/blob/main/docs/diagnostic-support-bundles.md)
for the contents, redaction boundary, hard limits, and exit codes.

The scaffold is credential-free and includes:

- a composition-only `app.py` with a process-scoped `build_app()` factory;
- one model-only agent with no required tools;
- complete tracked homes for prompts, tools, policies, environments, workflows,
  operations, knowledge, memory, integrations, observability, and domain code;
- explicit provider, storage, runtime, and agent-registration seams;
- a hermetic runtime test and output eval; and
- a source-controlled `[tool.cayu.scaffold]` plan plus `AGENTS.md` and the
  minimal `CLAUDE.md` bridge.

Open the generated project, describe the requested job in the existing agent,
and keep its public test/eval seam intact.

For an explicit, editable repository-coding starter with bounded file and Git
tools, durable knowledge, background review delegation, and human input, opt in
to the maintained composition:

```bash
cayu new mycoder --preset coding
cd mycoder
cayu check --fail-on warning --json
pytest -q tests/test_coding_composition.py
python run.py --agent mycoder --message "Implement the requested change."
```

Add `--execution docker` for the maintained GitHub-independent coding product.
Its `build_coding_product_application()` front door produces durable
`patch_ready_for_delivery` evidence after required checks, source copy-back, Git
inspection, and configured review gates settle. It performs no commit, push,
pull-request, CI, or merge effect. See the
[maintained coding product](https://github.com/cayu-dev/cayu/blob/main/docs/coding-product.md).

Add `--with remote-git-delivery` to generate the optional host-side broker seam.
It prepares the exact patch-ready tree for application approval, then can create
and push one exact commit to a new configured branch without exposing remote or
credential authority to the coding agent. See
[approved remote Git delivery](https://github.com/cayu-dev/cayu/blob/main/docs/remote-git-delivery.md).

Add `--with github-delivery` to include the subsequent host-only PR, exact-head
checks, review, and provenance-labelled follow-up seam. It implies remote Git
delivery and does not authorize merge. See [GitHub delivery](https://github.com/cayu-dev/cayu/blob/main/docs/github-delivery.md).

The generated repository starts from a clean Git commit, and each new product
run requires a clean committed Git source baseline. It also requires `git`,
`rg`, and the POSIX descriptor-relative filesystem primitives used by secure
`LocalWorkspace` path operations. Unsupported hosts fail during generation or
application construction. Its local workspace and runner are trusted-host
development adapters, not a hostile-code sandbox. The default scaffold is the
complete Cayu application convention. Select `--preset agent`, `--preset service`,
`--preset coding`, or `--preset long-running`; optional capabilities share the same
application layout. The long-running preset is a small working example of
approval before a side effect, a waited-for reply, reminder and deadline timers,
a per-session spend cap, and restart tests; `cayu guide long-running` explains
each part on one page.

Discover or review the Rails-style generation plan before writing:

```bash
cayu new --list-presets --json
cayu new --list-capabilities --json
cayu new myagent --preset agent --provider anthropic --dry-run --json
cayu guide applications#planning --json
```

### Deploy with Cayu Cloud

Cloud commands ship in the same `cayu` package; no additional CLI package is
required. Cayu Cloud is currently invite-only. Login-backed commands are pinned to
the production service at `https://cloud.cayu.dev`; users never select an API URL.

```bash
cayu cloud --help
cayu cloud login
cayu cloud whoami
cayu cloud init
cayu cloud deploy
```

Login uses WorkOS device authorization. It opens the browser when possible and always
prints a verification URL and one-time user code for SSH, containers, Cursor, Codex,
and Claude Code. The resulting Organization-scoped session is stored privately and
refreshed automatically; no WorkOS secret is embedded in Cayu. Use `--no-browser` when
a human will open the displayed URL on another device. Login selects the WorkOS session
over any previously persisted private context; a later `cayu cloud context use PATH`
deliberately switches back to that internal automation context. Private contexts and
explicit API credentials remain endpoint-bound operator mechanisms and do not change
the default customer endpoint.

`cayu cloud init` generates the small deployment descriptor from standard
`pyproject.toml` metadata and a configured Cayu server, worker, or console
script. Review the generated process topology before deploying it. Existing
descriptors are never replaced unless `--force` is explicit.

The default command packages the current local working directory and uploads it
directly to the selected Cayu Cloud Organization as an immutable source bundle.
It includes an applied patch and does not require GitHub, a clean worktree, a
commit, or a push. Git-ignored files and common local credential/cache paths are
omitted.

Deploy creates or updates the 8-63 character application slug declared in
`cayu-cloud.toml`. Slugs use lowercase letters, numbers, and interior hyphens.
`--application SLUG` overrides that create-or-update slug; check it carefully because
a valid typo creates a separate application.

Deploy output and local evidence redact runtime environment values. Cayu verifies the
evidence destination before Cloud mutation; if only the final evidence write fails after
a successful rollout, deploy still exits successfully with `evidence_id: null` and an
`evidence.status: unavailable` diagnostic.

To deploy an exact remote GitHub revision instead, pass its canonical URL and
40-character commit. For a private source, make authentication available to the
process that runs Cayu:

```bash
gh auth status --hostname github.com
# For noninteractive CI or an isolated Codex/Claude Code home:
GH_TOKEN="$GITHUB_TOKEN" cayu cloud deploy \
  https://github.com/example/agent --revision COMMIT_SHA
```

GitHub CLI credentials stored in a desktop keychain may not be reachable after
changing `HOME`, even when `GH_CONFIG_DIR` points at an authenticated GitHub CLI
configuration. In that case, pass a short-lived `GH_TOKEN` explicitly. Cayu
does not persist the token in its Cloud context or include GitHub CLI stderr in
its JSON errors. Public GitHub repositories remain deployable without GitHub
authentication.

For CI and other noninteractive automation, the existing
`CAYU_CLOUD_API_KEY`, `CAYU_CLOUD_API_KEY_FILE`, and private Cloud-context
options remain available. Explicit automation credentials take precedence over
the saved interactive login.

### Run an agent

This compact example shows the core API. Real projects should put the same
registrations in the generated `build_app()` factory instead of constructing a
module-global app.

```python
import asyncio

from cayu import AgentSpec, CayuApp, Message, RunRequest, run_to_completion
from cayu.providers import OpenAIProvider


async def main() -> None:
    app = CayuApp()
    app.register_provider(OpenAIProvider(), default=True)  # reads OPENAI_API_KEY
    app.register_agent(AgentSpec(name="assistant", model="gpt-5.6"))

    outcome = await run_to_completion(
        app,
        RunRequest(
            agent_name="assistant",
            messages=[Message.text("user", "Explain durable agent sessions.")],
        ),
    )

    if outcome.ok:
        print(outcome.final_text)
    else:
        print(f"{outcome.status}: {outcome.error}")


asyncio.run(main())
```

`CayuApp()` uses in-memory stores by default, which is appropriate for this
one-shot example and for tests. The generated project configures all local Cayu
stores in `data/cayu.db` so sessions survive process restarts. Multi-process
production deployments should select a conforming shared store such as
PostgreSQL.

`CayuApp.run(...)` is the lower-level event-stream API. Runtime failures arrive
as terminal `session.failed` events instead of exceptions raised from
iteration.
`run_to_completion(...)` consumes that same stream and returns a typed outcome
when an application only needs the result. It retains the complete event stream
in `RunOutcome.events`; use it for bounded runs. Consume `CayuApp.run(...)`
incrementally for long-lived or high-volume runs.

For a product that creates or continues conversations, use `send_turn`:

```python
from cayu import Message, TurnRequest, send_turn

outcome = await send_turn(app, TurnRequest(
    agent_name="assistant",
    session_id=conversation_id,  # None generates an ID; an existing ID resumes.
    messages=[Message.text("user", customer_message)],
))
conversation_id = outcome.session_id
if outcome.ok:
    print(outcome.final_text)
else:
    print(outcome.summary())
```

It returns the same `RunOutcome`, with invocation usage, model identity, ordered
public tool-call summaries, and interruption information. Active sessions raise
`SessionStatusConflict`; approvals, user input and manual recovery keep their
dedicated resolution APIs. See the
[terminal-turn contract](https://github.com/cayu-dev/cayu/blob/main/docs/runtime-contracts.md#terminal-turn-convenience)
and [runnable example](https://github.com/cayu-dev/cayu/blob/main/examples/send_turn.py).

For a credential-free domain-tool tracer bullet, run `cayu guide
references#domain-tool`, then use `cayu generate tool`. To add workspace tools
and command execution, see
[`examples/local_environment_runtime.py`](https://github.com/cayu-dev/cayu/blob/main/examples/local_environment_runtime.py).
For a finite application-owned command surface, use
[`NamedCheck` and `RunCheckTool`](https://github.com/cayu-dev/cayu/blob/main/docs/named-checks.md)
instead of exposing
model-authored shell or argv.

### Build with a coding agent

The generated `AGENTS.md` is the project-local source of truth. Ask the coding
agent to read it first, then use Cayu's package-shipped guides and structured
inspection:

```bash
cayu guide anatomy
cayu guide authoring
cayu inspect --json
cayu check --fail-on warning --json
```

The package-shipped `cayu guide authoring#cayu-map` routes each optional
capability to the smallest version-matched local reference. Its online
[source mirror](https://github.com/cayu-dev/cayu/blob/main/src/cayu/guides/authoring.md#cayu-map)
is secondary. The
[examples index](https://github.com/cayu-dev/cayu/blob/main/examples/README.md)
provides runnable references without making them required project structure.

The supported authoring loop is:

```text
understand -> inspect -> plan -> change -> test -> eval -> exercise -> report evidence
```

Start by editing the existing model-only agent, test, and eval. Add a generated
tool-backed slice only when the requested job needs a capability outside the
model; generated slices remain unfinished until their placeholder behavior,
test, and eval have been replaced.

## Mental model

Cayu separates the agent's identity from the resources and durable state used
for one execution:

```text
AgentSpec
  identity, model, system prompt, defaults, runtime policies

Environment
  workspace, runner, artifacts, vault, proxy, knowledge, MCP

Session
  durable identity, transcript, events, status, checkpoints

ToolContext
  the active environment services and call identity for one tool execution
```

- **Agent** describes who is acting and how model work is configured.
- **Environment** describes what that agent can touch.
- **Session** records one durable execution and its lineage.
- **Tool** is an explicitly registered, application-owned capability that the
  model may request. A native Python `Tool` runs inside the trusted Cayu
  application process; `ToolPolicy` gates its invocation but does not sandbox
  its implementation.
- **Task** is an optional durable unit of background or orchestrated work.
- **Workflow** is deterministic application orchestration around agent steps.

An environment is optional for a conversational agent. It becomes important
when tools need files, commands, artifacts, secrets, network policy, or a
sandbox. Static environments are useful for trusted local work;
`EnvironmentFactory` creates or reattaches session-specific environments in
production. One app can serve every request: `LocalWorkspaceEnvironmentFactory`
attaches each request to its own prepared directory, and
`CayuApp.delete_session` drops finished sessions. See
`cayu guide anatomy#process-scoped-application-graph`.

Choose the execution surface according to where code should run and which
boundary should contain it:

| Surface | Execution location | Boundary |
| --- | --- | --- |
| Native Python `Tool` | Cayu application process | Trusted application code; policy controls invocation, not host-process access |
| Process-isolated host `Tool` | Disposable POSIX child process session | Hard wall-clock liveness and owned process-group cleanup for an explicitly reconstructable trusted adapter; not a security sandbox |
| Runner-backed operation (`ctx.runner`) | Selected runner for that operation; the enclosing `Tool.run()` stays in the Cayu application process | Isolation, environment, network, and filesystem guarantees for the operation come from the admitted runner and environment |
| MCP tool | Configured MCP process or server | Separate integration boundary whose process, transport, credentials, and isolation remain deployment choices |
| Virtual egress | Selected runner plus a trusted broker outside it | A conforming adapter can keep the real credential out of the workload; code isolation still depends on the runner |

## Use the smallest runtime shape

Do not add every Cayu primitive to every application.

| Desired behavior | Start with |
| --- | --- |
| One model-driven interaction | `CayuApp`, `AgentSpec`, provider, `RunRequest` |
| Deterministic model-callable action | `Tool`, `ToolSpec`, explicit `ToolEffect` |
| Authority over an effect | `ToolPolicy`; approval only where a human gate is required |
| Mutable files or commands | Explicit `Environment`, `Workspace`, and `Runner` |
| Durable uploaded or generated files | `ArtifactStore` |
| Long-lived conversation or recovery | Durable `SessionStore` and checkpoint APIs |
| Background durable work | `TaskStore` plus an explicitly started worker |
| Delegated model work | Subagent tools with bounded child-session policy |
| Behavioral regression proof | `EvalSuite` and trajectory assertions |

Start a conversation agent with the model and state it needs. Add workflows,
task queues, environments, memory stores, servers, or multi-agent topology when
the behavior requires them. Give coding agents narrow domain tools before
granting broader shell access.

Artifact writes have a bounded cancellation-settlement contract. After a
dispatched write is interrupted, stores distinguish an exact committed artifact,
positively proved absence, and a typed reconciliation-required orphan candidate;
the candidate is diagnostic evidence, never a readable artifact reference.

## Application UI and Developer dashboard

Your application should own:

- end-user prompts and domain forms;
- product authentication and authorization;
- business-specific workflow and state;
- user-facing streaming, notifications, and presentation; and
- decisions about when a run, task, approval, or interruption is allowed.

Cayu owns runtime execution and the operational state recorded by the
application's configured stores. Its optional Developer dashboard is where
developers inspect sessions,
events, transcripts, tasks, usage, artifacts, pending actions, and recovery
state. Your application remains responsible for the product experience.

Start work through the API that matches the trigger:

- `run` for an immediate new session;
- `resume` for a deliberate continuation;
- `dispatch` for placement through a dispatcher;
- a task worker for durable queued work;
- a subagent for model-selected bounded delegation; or
- an event watcher for durable reactions to already-persisted events.

See [Triggering runs](https://github.com/cayu-dev/cayu/blob/main/docs/triggering-runs.md) for the decision guide and
lifecycle responsibilities.

## Providers and environments

The base package includes the provider contracts and built-in OpenAI, Anthropic,
OpenAI-compatible HTTP, and experimental OpenAI-subscription adapters. Optional
extras add integrations without forcing their dependencies into every
deployment:

| Extra | Adds |
| --- | --- |
| `cayu[server]` | FastAPI server API and the packaged Developer dashboard |
| `cayu[server-settings]` | Server extra plus typed environment and `.env` loading |
| `cayu[oidc]` | Server extra plus OIDC/JWT bearer-token verification (`OidcBearerAuth`) |
| `cayu[postgres]` | PostgreSQL session, task, knowledge, and related stores |
| `cayu[aws]` | Amazon Bedrock and Lambda MicroVM support |
| `cayu[vertex]` | Anthropic models through Google Cloud Vertex AI |
| `cayu[e2b]` | E2B runner and workspace |
| `cayu[microsandbox]` | Local microVM-backed untrusted-code runner |
| `cayu[egress]` | Virtual egress and credential-broker primitives |
| `cayu[files]` | Image and PDF inspection |
| `cayu[console]` | Interactive application console |
| `cayu[otel]` | OpenTelemetry tracing and metrics support |
| `cayu[claude-agent-sdk]` | Claude Code runs as Cayu sessions, with tokens, cost, deadlines and secret scrubbing (`cayu guide external-agents`) |
| `cayu[codex]` | Codex runs as Cayu sessions, with tokens, cost, deadlines and secret scrubbing (`cayu guide external-agents`) |
| `cayu[all]` | Every runtime integration extra above except the two vendor SDKs |

`cayu[all]` intentionally excludes `cayu[claude-agent-sdk]` and `cayu[codex]`,
which install vendor SDKs and their bundled CLI binaries, and `cayu[browser]`,
which is dashboard and browser verification tooling rather than a runtime
integration.

Providers normalize text, thinking, tool calls, usage, completion reasons, and
typed failures behind one runtime contract. Applications register providers
explicitly and may add deterministic model-pattern routing; an arbitrary model
name never selects a provider.

Cayu focuses on OpenAI, Anthropic, OpenRouter, Google, Bedrock, and Vertex.
OpenRouter is a first-class `cayu new --provider openrouter` and
`CAYU_PROVIDER=openrouter` choice backed by the generic Chat Completions adapter;
it requires `OPENROUTER_API_KEY` and an explicit `CAYU_MODEL` slug. Compatible
Chat Completions services such as Fireworks, Baseten Model APIs, and OpenCode Go
use that generic adapter directly. Run `cayu guide providers#openrouter` or use
the [package guide](https://github.com/cayu-dev/cayu/blob/main/src/cayu/guides/providers.md#openrouter)
for exact setup.

For native Choice, Score, and Noul decisions, explicitly register the experimental
[`TypeSafeProvider`](https://github.com/cayu-dev/cayu/blob/main/docs/typesafe.md). It uses TypeSafe's System One API through
Cayu sessions and events; it does not support chat tools or multimodal inputs.

For local development without separate OpenAI API billing, users can sign in
with their own ChatGPT subscription:

```bash
cayu auth openai login
# For SSH or a remote machine:
cayu auth openai login --headless
```

```python
from cayu.providers import OpenAISubscriptionProvider

app.register_provider(OpenAISubscriptionProvider(), default=True)
```

This experimental integration uses the Codex backend. It does not use the
documented OpenAI Platform API. Cayu identifies itself with `originator: cayu`
and preserves upstream rejections. OpenAI has not documented this raw backend
as a general third-party provider API, so support may change or stop.

> **Intended-use boundary:** Use this path only for a subscription holder's own
> local development and evaluation. For production, customer-facing or
> multi-user services, use the OpenAI Platform API or another officially
> supported provider. Do not share or resell credentials or bypass plan limits.

See [OpenAI subscription authentication](https://github.com/cayu-dev/cayu/blob/main/docs/openai-subscription.md) for the
support boundary, credential storage, and fallback options.

The same agent can run in a local workspace, trusted Docker container, E2B,
Microsandbox, Lambda MicroVM, or an application-owned runner without changing
its identity or transcript contract.

## Open and replaceable Developer dashboard

Cayu ships three equally supported Developer dashboard choices: use the bundled compiled dashboard,
eject the exact version-matched React/TypeScript source for application-owned customization, or
provide a completely custom UI over the versioned control-plane API.

```bash
cayu dashboard eject ./control-plane
cd control-plane
npm ci
npm run dev
npm run build
```

Extraction uses package data only—no repository clone, GitHub access, or network request. Serve
the resulting `dist/` with `DashboardConfig(directory=...)`,
`mount_cayu(..., dashboard_dir=...)`, or `mount_dashboard(..., dashboard_dir=...)`. Cayu never
rewrites the extracted application-owned source during upgrades. See [Open and replaceable
Developer dashboard](https://github.com/cayu-dev/cayu/blob/main/docs/control-plane.md) for the complete workflow, compatibility gate, and
redistribution obligations.

## Production boundaries

Cayu makes safety boundaries explicit, but configuration still matters:

- Native Python `Tool` implementations are trusted host-process code and can
  access authority available to the Cayu application. `ToolPolicy` controls
  whether the model may call a tool and with which arguments; it is not an OS
  isolation boundary. Run model-authored or otherwise untrusted code through an
  admitted runner or separately governed external tool boundary. Native tools
  that need credentials should use explicit `SecretRef` values through
  `ctx.proxy` or `ctx.vault` and return only safe results; ambient host
  environment values are not automatically mediated as workload credentials.
- `LocalRunner` executes directly on a trusted local machine and provides no
  sandbox isolation.
- `DockerRunner` is useful for development and CI; ordinary Docker isolation
  is not presented as a secure untrusted-code boundary. To run untrusted code
  locally, use a hardened container with allowlisted egress:
  `DockerEgressAdapter(workload_restrictions=DockerWorkloadRestrictions())` with
  `VirtualEgressEnvironmentFactory` (non-root, read-only root, no capabilities,
  resource limits, only allowlisted hosts). It still shares the host kernel. In
  production, use `SandboxCodingEnvironmentFactory` on Lambda MicroVM. Run
  `cayu guide untrusted-code` ([source](https://github.com/cayu-dev/cayu/blob/main/src/cayu/guides/untrusted-code.md)).
- Environment registration does not imply selection: mark a default explicitly
  or name the environment on the request. Provider defaults and model-pattern
  routing should likewise be configured deliberately and kept unambiguous.
- Tool effects do not authorize themselves. Use policies, approvals, scoped
  credentials, and destination controls where consequences require them.
- SQLite is appropriate for local and single-writer deployments. Use PostgreSQL
  or another conforming shared store for sustained multi-process concurrency.
- The FastAPI server requires an explicit `ServerConfig` access policy.
  Use `AuthenticatedAccess` for a deployed Developer dashboard and API; `OpenAccess` and
  `ServerConfig.local_development()` are deliberate local-only choices.
  Deployment names are descriptive metadata and never relax security policy.
  See [server configuration](https://github.com/cayu-dev/cayu/blob/main/docs/server-configuration.md).
  `AuthContext.tenant` records authenticated operator provenance but does not
  filter or isolate Cayu data. See [Server authentication and tenant
  isolation](https://github.com/cayu-dev/cayu/blob/main/docs/recipes/server-auth-tenancy.md).
  Generated API documentation is a separate exposure decision.
- Public or multi-user product routes need a separate customer authorization
  boundary; Developer dashboard authentication does not make the raw Cayu surface
  tenant-scoped. Start new services with
  `cayu new NAME --preset service`, then require both
  `cayu check --deploy --fail-on warning --json` and the generated
  `tests/test_public_service_security.py`. Cayu reports arbitrary host-owned
  ASGI routes outside that maintained factory as unverified.
- When embedding with `mount_cayu(..., path="/your/path")` or the lower-level
  `mount_dashboard(...)`, use `/your/path/` as the canonical dashboard URL.
  Cayu redirects an exact GET or HEAD of the slashless non-root mount after a
  successful dashboard mount. That public 307 may be returned without
  credentials; dashboard HTML, assets, deep links, and other protected content
  at the canonical target still require configured authentication.
  `mount_cayu(...)` places its control-plane API under `/your/path/api`;
  `mount_dashboard(...)` configures `apiBaseUrl` independently and defaults it
  to `/api`.
- Usage is derived from recorded events and survives restarts when those events
  use a durable store; cost remains an estimate against the price book your
  application selects.
- Recovery never invents the outcome of an ambiguous external side effect.
  Reconcile it through the typed recovery APIs.

Read [Runtime contracts](https://github.com/cayu-dev/cayu/blob/main/docs/runtime-contracts.md) before changing persistence,
replay, approval, interruption, budget, provider, runner, or recovery behavior.

## Documentation

Start with the [documentation index](https://github.com/cayu-dev/cayu/blob/main/docs/README.md)
for maintained guides, operational references, design records, research evidence,
and explicitly archived material.

Start with the document that matches the job:

| Goal | Guide |
| --- | --- |
| Choose Cayu concepts and build an application, by hand or with an AI coding agent | `cayu guide authoring#cayu-map` |
| Configure primary or compatible model services | `cayu guide providers` ([source](https://github.com/cayu-dev/cayu/blob/main/src/cayu/guides/providers.md)) |
| Classify and verify tool mutation and replay behavior | `cayu guide tool-effects` |
| Build a durable propose, authorize, act, verify, and recover lifecycle | `cayu guide durable-operations` ([source](https://github.com/cayu-dev/cayu/blob/main/src/cayu/guides/durable-operations.md)) |
| Run untrusted code in a hardened container with allowlisted egress | `cayu guide untrusted-code` ([source](https://github.com/cayu-dev/cayu/blob/main/src/cayu/guides/untrusted-code.md)) |
| Complete a task only after an independent verifier accepts its evidence | `cayu guide verified-work` ([source](https://github.com/cayu-dev/cayu/blob/main/src/cayu/guides/verified-work.md), [example](https://github.com/cayu-dev/cayu/blob/main/examples/durable_file_workflow/verified.py)) |
| Notify people about durable questions, approvals, and recovery gates | `cayu guide human-attention` ([source](https://github.com/cayu-dev/cayu/blob/main/src/cayu/guides/human-attention.md), [example](https://github.com/cayu-dev/cayu/tree/main/examples/human_attention/)) |
| Reconstruct service-backed tools with stable identities and scoped knowledge | `cayu guide durable-service-tools` ([source](https://github.com/cayu-dev/cayu/blob/main/src/cayu/guides/durable-service-tools.md), [example](https://github.com/cayu-dev/cayu/tree/main/examples/durable_service_tools/)) |
| Understand factories, process roles, and lifecycle | `cayu guide anatomy` ([source](https://github.com/cayu-dev/cayu/blob/main/src/cayu/guides/application-anatomy.md)) |
| Build a browser UI that follows sessions without hot polling | `cayu guide app-ui` ([source](https://github.com/cayu-dev/cayu/blob/main/src/cayu/guides/app-ui.md)) |
| Share one agent between several businesses, with a web interface for their people | `cayu guide b2b` ([source](https://github.com/cayu-dev/cayu/blob/main/src/cayu/guides/b2b.md)) |
| Run Claude Code or Codex as Cayu sessions with tokens, cost, deadlines and secret scrubbing | `cayu guide external-agents` ([source](https://github.com/cayu-dev/cayu/blob/main/src/cayu/guides/external-agents.md)) |
| Choose how work starts | [Triggering runs](https://github.com/cayu-dev/cayu/blob/main/docs/triggering-runs.md) |
| Create per-session workspaces and runners | [Environment factories](https://github.com/cayu-dev/cayu/blob/main/docs/environment-factories.md) |
| Produce a durable checked patch without external delivery | [Maintained coding product](https://github.com/cayu-dev/cayu/blob/main/docs/coding-product.md) |
| Deliver an approved exact patch to a new remote Git branch | [Approved remote Git delivery](https://github.com/cayu-dev/cayu/blob/main/docs/remote-git-delivery.md) |
| Create a bound GitHub PR and observe exact-head checks/reviews | [GitHub delivery](https://github.com/cayu-dev/cayu/blob/main/docs/github-delivery.md) |
| Implement a runner for your platform | [Build a runner](https://github.com/cayu-dev/cayu/blob/main/docs/build-a-runner.md) |
| Contain a non-cooperative trusted host dependency behind a hard deadline | [Process-isolated host tools](https://github.com/cayu-dev/cayu/blob/main/docs/process-isolated-tools.md) |
| Configure network and credential boundaries | [Virtual egress](https://github.com/cayu-dev/cayu/blob/main/docs/virtual-egress.md) |
| Let an agent search and read bounded public web evidence | [Web fetch and hosted search](https://github.com/cayu-dev/cayu/blob/main/docs/web-fetch.md) |
| Run GitHub CLI without giving the runner a real token | [GitHub CLI through virtual egress](https://github.com/cayu-dev/cayu/blob/main/docs/recipes/github-cli-virtual-egress.md) |
| Run a first Developer dashboard evaluation | `cayu guide evals-first` ([source](https://github.com/cayu-dev/cayu/blob/main/src/cayu/guides/evals-first.md)) |
| Add rubric-based AI quality evaluation | `cayu guide evals-ai-quality` ([source](https://github.com/cayu-dev/cayu/blob/main/src/cayu/guides/evals-ai-quality.md)) |
| Evaluate production sessions, scenarios, tools, and memory | `cayu guide evals-production` ([source](https://github.com/cayu-dev/cayu/blob/main/src/cayu/guides/evals-production.md)) |
| Look up complete Evals contracts | [Evals reference](https://github.com/cayu-dev/cayu/blob/main/docs/evals.md) |
| Understand knowledge authorization, retrieval fusion, and memory baselines | [Memory foundation contracts](https://github.com/cayu-dev/cayu/blob/main/docs/memory-foundation.md) |
| Reproduce bounded stateful agent evaluations | [Portable agent snapshots](https://github.com/cayu-dev/cayu/blob/main/docs/runtime-contracts.md#portable-agent-snapshots) |
| Estimate and govern cost | [Cost optimization](https://github.com/cayu-dev/cayu/blob/main/docs/cost-optimization.md) |
| Use the application console | [Console](https://github.com/cayu-dev/cayu/blob/main/docs/console.md) |
| Start a configured server process | [Project server](https://github.com/cayu-dev/cayu/blob/main/docs/project-server.md) |
| Use, customize, or replace the Developer dashboard | [Open and replaceable Developer dashboard](https://github.com/cayu-dev/cayu/blob/main/docs/control-plane.md) |
| Start a named worker process | [Project workers](https://github.com/cayu-dev/cayu/blob/main/docs/project-workers.md) |
| Configure CLI session-store discovery | [Session-store targets](https://github.com/cayu-dev/cayu/blob/main/docs/session-store-targets.md) |
| Prune old sessions, evals, artifacts and workspaces (off by default; persistent session stores keep everything until a policy runs) | [Storage retention](https://github.com/cayu-dev/cayu/blob/main/docs/storage-retention.md) |
| Inspect durable sessions safely | [Session inspection](https://github.com/cayu-dev/cayu/blob/main/docs/session-inspection.md) |
| Configure a server deployment | [Server configuration](https://github.com/cayu-dev/cayu/blob/main/docs/server-configuration.md) |
| Embed Cayu behind tenant-aware product APIs | [Server authentication and tenant isolation](https://github.com/cayu-dev/cayu/blob/main/docs/recipes/server-auth-tenancy.md) |
| Inspect supported model metadata | [Model catalog](https://github.com/cayu-dev/cayu/blob/main/docs/model-catalog.md) |
| Look up exact runtime behavior | [Runtime contracts](https://github.com/cayu-dev/cayu/blob/main/docs/runtime-contracts.md) |
| Track prerelease behavior and migrations | [Release notes](https://github.com/cayu-dev/cayu/blob/main/docs/release-notes.md) |

Maintainer-facing architecture is documented in
[Architecture](https://github.com/cayu-dev/cayu/blob/main/docs/architecture.md),
[Project layout](https://github.com/cayu-dev/cayu/blob/main/docs/project-layout.md),
and the [Glossary](https://github.com/cayu-dev/cayu/blob/main/docs/glossary.md).

## Examples

- [Examples index](https://github.com/cayu-dev/cayu/blob/main/examples/README.md):
  find the smallest reference for a capability.
- `cayu guide references#domain-tool`: credential-free domain-tool authoring
  and generator path.
- [Local environment runtime](https://github.com/cayu-dev/cayu/blob/main/examples/local_environment_runtime.py):
  files and commands.
- [Server example](https://github.com/cayu-dev/cayu/blob/main/examples/server_example.py):
  protected API and Developer dashboard.
- [Cloud PR reviewer](https://github.com/cayu-dev/cayu/blob/main/docs/recipes/pr-reviewer.md):
  durable task, isolated workspace,
  QA, and an explicit external effect.
- [Business approvals](https://github.com/cayu-dev/cayu/blob/main/docs/recipes/business-approvals.md):
  domain approval routing
  over the binary runtime primitive.
- [GitHub CLI through virtual egress](https://github.com/cayu-dev/cayu/blob/main/docs/recipes/github-cli-virtual-egress.md):
  an
  unmodified CLI with a virtual token, exact REST policy, and explicit mutation boundary.
- [Advanced runtime examples](https://github.com/cayu-dev/cayu/blob/main/examples/ADVANCED_RUNTIME_EXAMPLES.md):
  forks,
  compaction, taint isolation, speculative approval, and measured evidence.

Advanced examples are executable runtime specifications. Each example states
its evidence boundary instead of presenting one strategy as suitable for every
workload. Their measured results are described in
[Advanced runtime strategies](https://github.com/cayu-dev/cayu/blob/main/docs/advanced-runtime-examples.md).

## Contributing and security

Cayu contributors should read
[CONTRIBUTING.md](https://github.com/cayu-dev/cayu/blob/main/CONTRIBUTING.md) for
placement policy, setup, validation commands, and pull-request requirements.
New third-party integrations normally live in their own packages against
Cayu's public extension contracts.

Report suspected vulnerabilities privately as described in
[SECURITY.md](https://github.com/cayu-dev/cayu/blob/main/SECURITY.md). Do not open a public issue or pull request for a
suspected security vulnerability.

For questions and project discussion, join
[Discord](https://discord.gg/jWa3kKJ7R8). Use
[GitHub issues](https://github.com/cayu-dev/cayu/issues) for actionable bugs and
concrete feature proposals.

## License

Cayu is licensed under the
[Apache License 2.0](https://github.com/cayu-dev/cayu/blob/main/LICENSE).