---
title: The operator model
description: How your agent is provisioned, configured, kept in sync and observed.
---

# The operator model

You provision one NOLGIA Agent per account with `POST /agent`, which requires an active Studio, Team or Enterprise subscription. Starter and Pro plans cannot provision an agent. Configure its environment, read its desired state and inspect the work it creates.

![The NOLGIA Agent and the work it creates](../assets/art/agent.jpg)

## Provision and deprovision

`GET /agent` reads your agent; `POST /agent` provisions it asynchronously. `DELETE /agent` deprovisions it and revokes its access token.

<!-- gen:endpoints paths=/agent,/agent/config,/agent/manifest,/agent/heartbeat,/agent/usage,/agent/dashboard/ticket -->
| Method | Path | What it does |
| --- | --- | --- |
| [GET](../api/#tag/agent/get/agent) | `/agent` | Get the current user's NOLGIA Agent, if provisioned. |
| [POST](../api/#tag/agent/post/agent) | `/agent` | Provision the current user's NOLGIA Agent (one per account; requires an active subscription). |
| [DELETE](../api/#tag/agent/delete/agent) | `/agent` | Deprovision the current user's NOLGIA Agent and revoke its access token. |
| [GET](../api/#tag/agent/get/agent/usage) | `/agent/usage` | Credits spent and jobs created by the current user's agent. |
| [GET](../api/#tag/agent/get/agent/manifest) | `/agent/manifest` | Return the complete desired state for the current user's agent as a single, server-computed source of truth: its installed abilities (with pinned versions), its available presets, and the pinned CLI + runtime versions. This is the one list a pod-side reconciler materializes. Increment 1 enumerates what already exists in the DB (abilities + presets + version pins); the CLI-embedded skills and the base-image skill library are a separate increment pending an object-store decision. |
| [GET](../api/#tag/agent/get/agent/config) | `/agent/config` | List the agent's custom configuration entries. Secret values are redacted (empty string) in the response. |
| [PUT](../api/#tag/agent/put/agent/config) | `/agent/config` | Upsert custom configuration entries (e.g. TELEGRAM_BOT_TOKEN) injected into the agent pod's environment. A running agent is flipped back to `pending_deploy` so the deploy pipeline applies the change (typically within ~5 minutes). |
| [POST](../api/#tag/agent/post/agent/dashboard/ticket) | `/agent/dashboard/ticket` | Mint a short-lived ticket URL for embedding the agent's live dashboard. |
| [POST](../api/#tag/agent/post/agent/heartbeat) | `/agent/heartbeat` | Report the agent pod's materialized state (installed ability versions) upstream. |
<!-- /gen -->

## Configure

> [!NOTE]
> `GET /agent/config` reads custom entries with secrets redacted. `PUT /agent/config` writes entries injected into the pod environment; a change flips a running agent to `pending_deploy` and is typically applied within about five minutes.

## Desired state

| Endpoint | What it tells you |
| --- | --- |
| `GET /agent/manifest` | Desired abilities with pinned versions, available presets, and pinned CLI and runtime versions. |
| `POST /agent/heartbeat` | The pod reports installed ability versions; compare `installed_version` with `latest_version` on `GET /agent/abilities` to observe drift. |

## Observe

`GET /agent/usage` reports credits spent and jobs created. `POST /agent/dashboard/ticket` creates a 120-second ticket for the embedded dashboard and accepts browser sessions only.

<!-- gen:fields schema=AgentUsage -->
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `credits_spent` | integer | Yes | Total credits consumed by generations the agent's token created. |
| `jobs_total` | integer | Yes | Number of jobs created with the agent's token. |
| `recent_jobs` | array of `Job` | Yes |  |
<!-- /gen -->

:::cards
- [Agent Sessions API](./agent-api.html) icon=spot-agent: Send messages, stream replies and collect assets.
- [Abilities](./abilities.html) icon=spot-library: Browse, install and sync marketplace packages.
:::