> ## Documentation Index
> Fetch the complete documentation index at: https://docs.starfort.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Guardian

> The Guardian is the engine that inspects content against your Guard Policies and returns a PASS, MASK, or BLOCK decision.

A **Guardian** is the analysis engine that sits in the path of an AI request. It receives content, evaluates it against the **Guard Policies** assigned to it, and returns an [action](/en/v1.2/concepts/actions-pass-mask-block) — `PASS`, `MASK`, or `BLOCK` — along with the detected items that justify the decision.

## System Guardian vs. Project Guardian

<CardGroup cols={2}>
  <Card title="System Guardian" icon="server">
    The master definition registered on the platform (e.g. the `VLM-OCR` preset). It declares the capabilities a Guardian supports — Input Types, Policy Types, process types, operating limits, and model configuration.
  </Card>

  <Card title="Project Guardian" icon="cube">
    A copy you create inside a **Project**. It owns the operational settings: which Guard Policies are assigned, model-config overrides, active categories, and its own lifecycle. This is what your API keys and Desktop Agents call.
  </Card>
</CardGroup>

When an Account Admin [registers a Guardian](/en/v1.2/admin/register-guardian) in a project, they pick a System Guardian preset; the project then gets its own Project Guardian to configure. A single Project can run **several Project Guardians** — for example one per service, or one per policy bundle — and each is an independent [Kill Switch](/en/v1.2/concepts/organization-hierarchy) toggle unit.

### Specs are frozen; settings are yours

Two rules explain most "why didn't my change apply?" confusion:

* **A System Guardian's spec is immutable after registration.** Once registered, only its name, description, Endpoint URL, and visibility (scope + Enabled) can change. The capability spec — supported Input Types, Policy Types, process types, limits, and model-config keys — is frozen.
* **A Project Guardian copies that spec at creation and owns it independently.** Later edits to the System Guardian do **not** propagate retroactively; only the live Endpoint URL keeps being referenced. The compatible Policy Type set (what it *can* inspect) stays fixed by the System Guardian, while the operating values inside that range (assigned Guard Policies, text/file limits, active categories, model configuration) are yours to tune.

## Input Types

A Guardian declares which kinds of content it can inspect. You enable a subset per Guardian:

| Input Type | Examples                           |
| ---------- | ---------------------------------- |
| Text       | prompts, messages                  |
| Image      | PNG, JPG, WebP, GIF, …             |
| Audio      | WAV, MP3                           |
| Video      | MP4                                |
| Document   | PDF, DOCX, XLSX, PPTX, TXT, CSV, … |
| Archive    | ZIP                                |

Category support follows a three-stage lifecycle: the System Guardian **declares** the categories it can handle, the Project Guardian **activates** a subset, and at runtime the Bastion **verifies** the incoming content against the active set. (On Desktop Agent projects the content type is determined by the parsing rule; on API projects it is taken from the declared content-part type.) Content whose type is not enabled is rejected (or, for files, passed unchecked — see Unsupported File Handling). See [Multimodal inputs](/en/v1.2/api/multimodal) for how these map to API requests.

## Process types: input and output

A Guardian evaluates content per **process type** — a free-form label the Guardian defines (commonly `input` and `output`):

* **`input`** — content going *to* the model (the user's prompt).
* **`output`** — content coming *back* from the model (the reply).

Each process type declares the **Policy Types it is compatible with**. Guard Policies are assigned per process type, so you can mask PII on the way in and, for example, block disallowed topics on the way out. A process type whose compatible set is empty is **Policy-not-required** — no policy slot is shown for it and no `policies` are sent on the call (it runs on its additional input alone).

## The Guardian contract

Any Guardian implementation must satisfy a small baseline contract so the platform can drive it:

* **Stateless** — every request is handled independently; user management, auth, and trace logging are the Bastion's job, not the Guardian's.
* **Normalized format** — it accepts the Guardian Input Format and replies in the Guardian Output Format.
* **Three baseline endpoints** — `/guardian` (analysis), `/info` (self-description), and `/health` (liveness only), plus optional per-model diagnostics.

`/info` is a **seed, not the source of truth**: at registration its response pre-fills the form, and the System Admin's saved result becomes the system's source of truth.

### Guardian Fail-Closed

A Guardian returns a success response **only for requests it fully analyzed**. If it cannot complete analysis — a model is down, a file can't be extracted, or even one of several model calls fails (partial failure) — it returns an **HTTP error**, never an empty-detection "success." This guarantees that "no detections" always means *analyzed and found nothing*, so an outage can never silently become a PASS.

## Model configuration

Each Guardian has an effective model configuration — engine defaults merged with any project-level overrides (for example `confidence_threshold`). Admins view and override these on the Guardian's detail page.

<Note>
  A Guardian only acts when it has policies assigned **and** those policy versions are applied to it. See [Version & apply a policy update](/en/v1.2/admin/how-to/version-and-apply-policy).
</Note>