# Managed Agents

Provision a private, always-on AI agent that Cohesivity hosts for you: its own isolated compute box, a model source, and the network surface, with zero setup. You say "I want an agent"; Cohesivity launches it, wires it to a model, and gives you one OpenAI-compatible endpoint to talk to it with your existing app key. First agent type: **Hermes** (Nous Research's stateful, long-running CLI agent).

**Claimed accounts only.** The agent is account-level: one box per Cohesivity user, reachable by every project you own.

## Setup Sequence

Provisioning runs in this order; every step happens on Cohesivity's or OpenAI's own pages:

1. **Tenant setup:** a `.cohesivity` file marks an existing tenant; without one, the quickstart creates it (see Quick start).
2. **Claim requirement:** managed agents need a claimed tenant. On an `ephemeral` tenant, provisioning fails until the claim flow (`POST https://cohesivity.ai/api/claim/url`) completes, which needs the user's approval.
3. **Provisioning** happens via the endpoint below.
4. **Optional:** connecting the user's Codex subscription makes inference $0 against the wallet.
5. **Usage** happens via `/edge/managed-agents` (below).

## Plans (flat monthly, from fluid credits)

- **Starter: $12/mo:** 4 GB RAM box.
- **Pro: $20/mo:** 8 GB RAM box.

Compute is a flat monthly fee billed from your fluid credits (scale-to-zero between requests). **A claimed account gets its first month free.** Model inference is billed separately by source (below).

## Provision

`POST https://cohesivity.ai/api/agents` with `Authorization: Bearer <coh_management_key>` and body `{ "agent_type": "hermes", "plan": "starter" | "pro" }` → `{ status: "active", address, monthly_fee_cents, next_charge_at, trial }`.

- `GET https://cohesivity.ai/api/agents` → current status (provisioned, plan, status, next charge).
- `DELETE https://cohesivity.ai/api/agents` → unprovision (pauses the box; data is kept for a 15-day retention window, then the box terminates; re-provisioning before that window keeps it).
- `GET https://cohesivity.ai/api/managed-agents` → catalog, your eligibility, and your current `model_source`.

## Model source

Your agent runs on one of two model sources (toggleable):

1. **Your connected Codex subscription** (default when present): the agent runs on your own ChatGPT/Codex plan; LLM cost lands on that subscription, **$0 against your Cohesivity wallet**. Connect it once (see below).
2. **Cohesivity AI Gateway**: allowlisted OpenAI/Anthropic/Google/xAI models, billed from your fluid credits. Used when you have no connected subscription, or by choice.

On rate-limit, Cohesivity suggests the other source rather than silently spilling. There is **no standalone "use Codex directly" product**: a connected Codex subscription exists to power *your managed agent*.

**Switch anytime, no reset.** The Codex subscription can be connected or disconnected anytime; the agent moves to the new source automatically (within ~30s), on the **same box**, with **no re-provision and no lost state** (`~/.hermes` memory/sessions are preserved). Order does not matter: provision first and connect later, or connect first then provision; either way the agent ends up on your sub when connected and on the AI Gateway when not.

### Codex Subscription Connection (to power the agent)

Uses OpenAI's official device-code flow: no Cohesivity UI, no key to paste. It's an account-level *connection*, not a per-tenant resource, so `/api/resources/codex` does not apply here.

1. `POST https://cohesivity.ai/api/codex/connect` with `Authorization: Bearer <coh_management_key>` (claimed tenant) → `{ user_code, verification_uri, security_settings_url, wait }`.
2. The human enables **Allow device code login** in ChatGPT → Settings → Security (`security_settings_url`), opens `verification_uri`, enters `user_code`, and approves.
3. `GET https://cohesivity.ai/api/wait` with the returned `wait` blob polls until `{ "status": "completed" }`.
- `GET https://cohesivity.ai/api/codex` → connection status · `POST https://cohesivity.ai/api/codex/disconnect` → revoke.

## Using the Agent

The agent responds to your **existing app key**, with no separate key needed. OpenAI-compatible:

`POST https://cohesivity.ai/edge/managed-agents/v1/chat/completions?key=<coh_application_key>` with body `{ messages, ... }` (OpenAI-compatible). Forwarded to your private agent box and streamed back; the app key never reaches the box (Cohesivity resolves a narrow per-agent key server-side).

**The `model` field is not a per-call selector.** The agent runs on ONE model fixed by your source: `gpt-5.5` on a connected Codex sub, `openai/gpt-5.4` on the AI Gateway. The field accepts omission or exactly that fixed model value; any other value (e.g. `gpt-4o`) returns `400 model_not_selectable` naming what the agent actually runs on. Every response carries `x-cohesivity-model` and `x-cohesivity-model-source` headers, identifying what served it. Changing models means switching the source (above), not the field.

**Cold start is normal.** The box scales to zero when idle (~20 min), so the **first call after idle wakes it and can take ~30–90s**. A generous client timeout (**≥90s**) on that call avoids premature failures; a `503 agent_starting` is transient (the box is booting, at no cost), and retrying resolves it, after which the agent stays warm for follow-ups.

## Isolation

One VM per user (never bin-packed with other tenants). The box holds only a narrow, tenant-scoped agent key: never the wallet-spending app key, never the raw subscription token. It is reachable only through Cohesivity's in-network control path, never publicly.