# Aethis documentation > Complete, build-generated documentation for Aethis agents and developers. This file combines all 28 published documentation articles in the same order as the Aethis documentation navigation. Documentation home: https://aethis.io/docs ## Table of contents - [Getting started](#getting-started) - [Aethis Docs](#aethis-docs) - [What is Aethis?](#what-is-aethis) - [Quickstart](#quickstart) - [Tour the dashboard](#tour-the-dashboard) - [Agents](#agents) - [Agents and Connections](#agents-and-connections) - [Register an Agent](#register-an-agent) - [Observe Mode](#observe-mode) - [Manage spend and usage](#manage-spend-and-usage) - [Connections](#connections) - [Connect an MCP server](#connect-an-mcp-server) - [Tool discovery and review](#tool-discovery-and-review) - [Review tool changes](#review-tool-changes) - [Policies](#policies) - [Policies and decisions](#policies-and-decisions) - [Create and publish a Policy](#create-and-publish-a-policy) - [Policy rule model](#policy-rule-model) - [Verify a governance boundary](#verify-a-governance-boundary) - [Approvals](#approvals) - [Approvals bound to an exact action](#approvals-bound-to-an-exact-action) - [Review the Approval Queue](#review-the-approval-queue) - [Activity & evidence](#activity-evidence) - [Governed actions](#governed-actions) - [Action Records](#action-records) - [Investigate in Activity](#investigate-in-activity) - [Read the Control Map](#read-the-control-map) - [Respond to Alerts](#respond-to-alerts) - [Administration](#administration) - [Organizations and workspaces](#organizations-and-workspaces) - [Manage your organization and workspaces](#manage-your-organization-and-workspaces) - [Plans and governed actions](#plans-and-governed-actions) - [Security and data](#security-and-data) - [Reference](#reference) - [Terminology](#terminology) - [Statuses](#statuses) ## Getting started ### Aethis Docs Canonical source: [https://aethis.io/docs](https://aethis.io/docs) > Learn how to connect agents, set policies, review approvals, and understand every governed action in Aethis. Connect your agents. Define their boundaries. Understand what happened. ### What is Aethis? Canonical source: [https://aethis.io/docs/concepts/what-is-aethis](https://aethis.io/docs/concepts/what-is-aethis) > Understand how Agents, Connections, Policies, approvals, and Action Records work together to govern a call. Aethis is a governance and control layer for AI agents. It sits between an agent and the systems it can affect, evaluates each action against policy, and records the decision and outcome together. Your agent keeps running in your own application. Aethis governs the calls you route through it; it does not host your agent or govern calls that bypass it. #### The governance loop 1. **Your agent** Makes a tool call 1. **Aethis endpoint** Identifies the Agent 1. **Policy check** Evaluates the exact action 1. **Your MCP server** Receives permitted calls in Enforce mode 1. **Identify the caller.** Your MCP client calls the Agent’s Aethis endpoint and sends its access key. The key identifies the Agent; it is not a credential for the upstream server. 2. **Resolve the destination.** Aethis checks the Agent’s assigned Connections and the discovered tool. Attaching a Connection establishes a path; policy determines what may happen on it. 3. **Evaluate the action.** The applicable Policies evaluate the tool, target, and arguments. The policy decision is **Allow**, **Require Approval**, or **Block**. 4. **Apply the mode.** In **Enforce**, permitted calls reach the upstream server, blocked calls stop, and calls requiring approval are held. In **Observe**, Aethis records the decision while execution continues unchanged. 5. **Keep the evidence.** The Action Record connects the request, policy version, any review, and execution outcome. A policy decision and an execution outcome answer different questions. **Allow** says the action was permitted. **Execution succeeded** says it ran successfully. Read both before concluding what happened. #### The objects you work with | Object | What it answers | Where to start | | -------------------- | ---------------------------------------------------- | ------------------------------------------------------------ | | **Agent** | Who is making the call, and who owns it? | [Register an Agent](https://aethis.io/docs/guides/register-an-agent) | | **Connection** | Which upstream system may this Agent reach? | [Connect an MCP server](https://aethis.io/docs/guides/connect-an-mcp-server) | | **Policy** | Which actions may run, need review, or must stop? | [Create a Policy](https://aethis.io/docs/guides/create-a-policy) | | **Approval request** | May this exact action proceed once? | [Review an approval](https://aethis.io/docs/guides/review-approvals) | | **Action Record** | What was requested, decided, approved, and executed? | [Investigate in Activity](https://aethis.io/docs/guides/investigate-activity) | Agents and Connections belong to a workspace. Use separate workspaces when environments need separate credentials, access, or ownership. Organization settings govern the wider team. See [Organizations and workspaces](https://aethis.io/docs/concepts/organizations-and-workspaces). #### Follow a refund example Suppose a Billing Agent uses a published refund policy with these boundaries: - Up to SGD 500: **Allow**. - Above SGD 500 and up to SGD 1,000: **Require Approval**. - Above SGD 1,000: **Block**. For a SGD 750 refund, the policy returns **Require Approval**. In Enforce mode, the call is held for review. A reviewer checks the account, amount, target, and arguments, then chooses **Approve Once** or **Deny**, with a reason. Approval does not itself execute the refund. It authorizes one exact action. Changing the amount or target requires another evaluation. Follow the request into its Action Record to see whether execution actually happened. In Observe mode, the same rule can return **Require Approval** without holding execution. An observed decision is evidence of what the policy said, not proof that the action was stopped. Use [Verify a governance boundary](https://aethis.io/docs/guides/verify-governance) to check a policy with safe example inputs before relying on it. #### Integration paths **MCP tool calls.** Your MCP-compatible client uses one Aethis endpoint per Agent, regardless of how many Connections are attached: ```text URL: https://mcp.aethis.io/v1/agents/{agent_id}/mcp Header: Authorization: Bearer ``` Copy the values from the dashboard and keep the access key in a secret manager. No SDK is required. Your remote MCP servers stay where they are. **Model calls.** Direct model routing supports OpenAI chat completions through a **Model Route**. A Model Route and an MCP Connection are different destinations; choose the path that matches your client’s request. See [Connect an MCP server and Model Routes](https://aethis.io/docs/guides/connect-an-mcp-server#model-routes-openai). #### Who is Aethis for? Teams that give agents access to consequential tools: payments, customer records, deployments, or internal systems. Builders configure the boundary; reviewers decide exceptional actions; operators inspect evidence and resolve problems. #### How is Aethis different from an AI gateway or observability product? A gateway routes requests. Observability helps you inspect what happened. Aethis adds an action-level policy decision, an approval when required, and evidence connecting the decision to the outcome. These categories can overlap; Aethis’s focus is governing the action in the request path. #### Next steps - [Quickstart](https://aethis.io/docs/quickstart): connect an Agent and inspect its first recorded decision. - [Tour the dashboard](https://aethis.io/docs/tour): find each surface and its purpose. - [Plans and governed actions](https://aethis.io/docs/reference/plans): understand action allowances and retention. ### Quickstart Canonical source: [https://aethis.io/docs/quickstart](https://aethis.io/docs/quickstart) > Protect your first Agent with Aethis. Choose an Agent, connect it, set one boundary, try it, and inspect the Action Record. This quickstart follows the **Protect your first Agent** guide built into the dashboard. It takes one Agent from nothing to a recorded, governed decision in five steps: 1. Choose your Agent 2. Connect the Agent 3. Set one clear boundary 4. Try the boundary 5. Inspect the Action Record Open **Get started** in the sidebar. The guide starts automatically on your first visit and highlights the control to use at each step. You can pause it at any time with **Pause tour** and pick it up again from **Get started**. > **Want to see it work first?** > On step 1, select **Use a sample Agent**. Aethis creates a **Sample Billing Agent** with a sandbox billing Connection already attached, and jumps you to step 3. It is the quickest way to see a decision end to end before you connect your own agent. #### 1. Choose your Agent An Agent in Aethis is the identity your client uses when it calls tools. Open an existing Agent, or register the one your client will use. [Screenshot: The guided tour on the Agents page, step 1 of 5: Choose your Agent, with a Use a sample Agent button next to Register Agent.](https://aethis.io/docs/quickstart) 1. On **Agents**, select **Register Agent**. 2. Under **Choose how this Agent works**, select **MCP-only**, then **Continue**. [Screenshot: Register Agent, step 1 Setup type, with MCP-only selected.](https://aethis.io/docs/quickstart) 3. On the **Client** step, under **Choose how your agent connects**, select **MCP-compatible agent**, then **Continue**. No SDK is required. [Screenshot: Register Agent, step 2 Client: MCP-compatible agent selected; Custom HTTP is the other option.](https://aethis.io/docs/quickstart) 4. Enter an **Agent Name**, check the **Owner** and **Workspace**, and optionally choose **MCP Connections**. Select **Register Agent**. 5. The **Agent created** dialog shows the two values your client needs: the **Aethis MCP server URL** and the **Aethis access key**. Copy both, store the key in your secret manager, then select **Done**. [Screenshot: The Agent created dialog showing the Aethis MCP server URL on mcp.aethis.io and the Aethis access key, each with a copy button.](https://aethis.io/docs/quickstart) > **Treat the access key like a password** > Keep the access key out of source control, screenshots and support messages. If it leaks, rotate it from the Agent's **Overview** with **Rotate Key**. ##### Point your agent at Aethis In your MCP-capable agent or client, replace the upstream MCP server address with the **Aethis MCP server URL** you copied, and send the **Aethis access key** as a bearer token: ```text URL: https://mcp.aethis.io/v1/agents/{agent_id}/mcp Header: Authorization: Bearer ``` Each Agent has one Aethis MCP endpoint, whatever the number of Connections it uses. The URL identifies the Agent and isn't a secret; the access key is the Agent's scoped credential and is. Copy the URL from the dashboard rather than typing it by hand. From then on, your agent's tool calls go to Aethis first. Aethis resolves each call through the Agent's assigned Connections, governs it, and forwards allowed calls to your existing upstream MCP server. When you attach more Connections later, you don't change anything in your client. #### 2. Connect the Agent A [Connection](https://aethis.io/docs/concepts/agents-and-connections) is the upstream MCP server the Agent is allowed to reach through Aethis. 1. Open the Agent and select **Connections**. 2. Select **Attach connection**, choose an MCP Connection from this workspace, and select **Attach MCP Connection**. 3. If the server isn't in Aethis yet, select **Manage accounts** in the guide (or open **Connections**) and [add the MCP server](https://aethis.io/docs/guides/connect-an-mcp-server) first. Then connect its account, select **Refresh tools**, and review any changes. #### 3. Set one clear boundary Attach a published [Policy](https://aethis.io/docs/concepts/policies) to the Agent. A Policy holds the rules that decide whether each action is allowed, needs approval, or is blocked. [Screenshot: The Agent's Policies section with the guide on step 3 of 5, Set one clear boundary, offering Apply refund limits.](https://aethis.io/docs/quickstart) - **With the sample Agent**, select **Apply refund limits**. Refunds up to SGD 500 pass, refunds up to SGD 1,000 need approval, and anything above is blocked. - **With your own Agent**, select **Create or review policy**, build the rule for your Connection, publish the version, then return to the Agent and select **Attach Policy**. See [Create and publish a Policy](https://aethis.io/docs/guides/create-a-policy). #### 4. Try the boundary You can check a boundary without running anything. 1. Open the Agent's **Tools** section. Tools that a policy can evaluate show **Conditional** access and an **Evaluate policy** button. [Screenshot: The Agent's Tools section. Issue a refund has Conditional access and an Evaluate policy button.](https://aethis.io/docs/quickstart) 2. Select **Evaluate policy**. Enter a safe test **Amount**, **Currency** and **Target**. The decision updates as you type. Evaluation does not execute the action. [Screenshot: The Evaluate policy panel for Issue a refund. An amount of 750 SGD shows Approval required.](https://aethis.io/docs/quickstart) 3. Select **Record result** (or **Request approval**, when the decision is Require Approval). Aethis records the evaluated action. [Screenshot: After recording, the panel shows Action recorded, with links to Open Approval Queue and Open Action Record.](https://aethis.io/docs/quickstart) To try it for real, make the same call from your agent. Aethis applies the same Policy to the live call. New Agents default to [Observe Mode](https://aethis.io/docs/concepts/observe-mode): the decision is recorded, but the call isn't blocked or held. Check the Agent's mode before interpreting the outcome; **Enforce** applies the policy decision. #### 5. Inspect the Action Record Select **Open Action Record**. The record opens in **Activity** and shows what Aethis decided and why. [Screenshot: An Action Record for Issue a refund: Sample Billing Agent, Sample Internal Billing, policy decision Require Approval, outcome Approval pending.](https://aethis.io/docs/quickstart) Check three things: - **Summary:** the Agent, Connection, **Policy decision** and **Outcome** match what you expected. A recorded evaluation that needs approval shows **Approval pending**; a live allowed call moves through **Allowed, awaiting execution** and **Execution in progress** to **Execution succeeded**. **Outcome unknown** means the result was lost after the call may have run; it is never reported as failed. See [Action outcomes](https://aethis.io/docs/reference/statuses#action-outcomes). - **Governance:** the Policy version and matched rule are the ones you meant to apply. - **Integrity:** the record's link status. See [Action Records](https://aethis.io/docs/concepts/action-record). If the decision was **Require Approval**, open the request from **Open Approval** and [review it in the Approval Queue](https://aethis.io/docs/guides/review-approvals). #### Next steps - [Verify a governance boundary](https://aethis.io/docs/guides/verify-governance): check the policy, mode, and execution outcome together. - [Tour the dashboard](https://aethis.io/docs/tour) - [Observe Mode](https://aethis.io/docs/concepts/observe-mode): see what a policy would block before you enforce it. - [Review the Approval Queue](https://aethis.io/docs/guides/review-approvals) - [Invite an approval reviewer](https://aethis.io/docs/guides/manage-organizations-and-workspaces#invite-a-member) ### Tour the dashboard Canonical source: [https://aethis.io/docs/tour](https://aethis.io/docs/tour) > Find your way around the Aethis dashboard. The sidebar groups surfaces into Control, Govern, Observe, Operate and Admin. The Aethis dashboard is organized around one loop: register Agents, connect them to tools, govern what they may do, and observe what they did. The sidebar follows that order. [Screenshot: The Aethis sidebar with five groups: Control, Govern, Observe, Operate and Admin.](https://aethis.io/docs/tour) #### The top bar - **Organization switcher** (top left): switch between organizations you belong to, or select **Manage organizations**. - **Workspace switcher**: switch between workspaces in the current organization, such as Production and Staging, or select **Manage workspaces**. Almost everything in the dashboard is scoped to the current workspace. - **Search Aethis** (`Ctrl` `K`): search across the dashboard. - **Notifications**: the bell shows new items that need you. #### Control | Surface | What it's for | | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Get started** | Guided journeys. **Protect your first Agent** walks you through the [Quickstart](https://aethis.io/docs/quickstart). Others cover connecting an app, bringing in a reviewer, the Control Map and alerts. | | **Overview** | The state of the workspace at a glance: requests today, active Agents, healthy connections, gateway overhead, what needs attention, and connection health. | | **Control Map** | A graph of what each Agent can reach and which policies apply. See [Read the Control Map](https://aethis.io/docs/guides/read-the-control-map). | [Screenshot: The Overview page: summary figures, a gateway overhead chart, and a Needs attention panel listing pending approvals, unresolved alerts and connections to check.](https://aethis.io/docs/tour) **Needs attention** is the fastest route to work: it counts pending approvals, unresolved alerts, and connections that are degraded or unavailable. #### Govern | Surface | What it's for | | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- | | **Agents** | Register Agents and manage each one's **Overview**, **Connections**, **Policies** and **Tools**. See [Register an Agent](https://aethis.io/docs/guides/register-an-agent). | | **Connections** | Add MCP servers (and OpenAI Model Routes), connect accounts, refresh and review tools. See [Connect an MCP server](https://aethis.io/docs/guides/connect-an-mcp-server). | | **Approval Queue** | Actions held for a person. The sidebar badge counts active requests. See [Review the Approval Queue](https://aethis.io/docs/guides/review-approvals). | | **Policies** | Create, publish and assign the rules Aethis applies. See [Create and publish a Policy](https://aethis.io/docs/guides/create-a-policy). | #### Observe | Surface | What it's for | | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | **Activity** | Every governed action, as a **Timeline** or a list of **Action Records**. See [Investigate in Activity](https://aethis.io/docs/guides/investigate-activity). | | **Alerts** | Operational problems that need an owner, such as a changed tool or a policy conflict. See [Respond to Alerts](https://aethis.io/docs/guides/respond-to-alerts). | #### Operate **Support** lists your support tickets with Aethis and lets you open a new one with **Create Ticket**. #### Admin **Settings** has three scopes: - **Personal**: your account and sign-in security. Open it from your name at the bottom of the sidebar. - **Workspace**: the current workspace's details, members and access, and defaults. - **Organization**: members, roles, workspaces, SSO and organization-wide governance defaults. See [Manage your organization and workspaces](https://aethis.io/docs/guides/manage-organizations-and-workspaces). #### Guided journeys **Get started** lists every guided journey. Each one opens on the real page and highlights the control to use, with a short card that explains the step. - Select **Pause tour** on the card, or press `Esc` while the card has focus, to pause. - Press `F6` to move focus between the card and the highlighted control. - Return to **Get started** and select **Resume** to continue where you left off. The journeys never submit a form, publish a policy or approve an action for you. You make every change yourself. ## Agents ### Agents and Connections Canonical source: [https://aethis.io/docs/concepts/agents-and-connections](https://aethis.io/docs/concepts/agents-and-connections) > An Agent is the identity a client uses to reach Aethis. A Connection is an upstream MCP server (or OpenAI Model Route) that Agent may use. Two objects describe what an AI agent can reach: the **Agent**, which says who is calling, and the **Connection**, which says where the call may go. #### Agents An **Agent** is the identity Aethis associates with a governed call. Each Agent belongs to one workspace and has: - a name and an **Owner** (the team accountable for it) - an **Agent identity** such as `agent_billing_prod` - one **Aethis MCP server URL**, `https://mcp.aethis.io/v1/agents/{agent_id}/mcp` - an **Aethis access key**, the Agent's scoped credential, which your client sends as `Authorization: Bearer `; the dashboard shows only its **Agent key fingerprint** after creation - a setup type: **MCP-only**, **Model-only** or **Combined** - assigned Connections, Policies and basic controls A connection or a key does not grant permission on its own. Having a Connection makes a tool reachable; the Agent's [Policies](https://aethis.io/docs/concepts/policies) decide whether a particular call may run. ##### Agent sections Every Agent has four sections: | Section | Shows | | --------------- | ------------------------------------------------------------------------------------------------------------------- | | **Overview** | **Usage & limits** (including the spend budget), Agent details, the access key fingerprint, and **Basic controls**. | | **Connections** | The Connections assigned to this Agent and their status. | | **Policies** | The Policies that apply to this Agent, whether assigned directly or required by the organization. | | **Tools** | Every tool the Agent can reach, the policies that apply to it, and its current access. | ##### Basic controls Basic controls on the Agent's **Overview** apply to every call the Agent makes: - **Data protection**: **PII redaction**, **Payment data redaction** and **Secrets redaction** mask sensitive values before they leave for a provider or tool. Redaction is an Agent control, not a policy decision. - **Approvals & evidence**: **Unknown tool approval** holds untrusted tools for review, and **Tamper-evident evidence** records a hash-chained decision and policy snapshot. ##### Spend budgets Spend is visible at both Agent and workspace level: - **Agent** (**Usage & limits** on the Agent's **Overview**): **Monthly spend cap**, **Spend this month** and an **Alert at** percentage. The Agent figures track the workload against its budget; **Alert at** is a warning threshold and does not stop execution. - **Workspace** (**Workspace spend controls** in workspace settings): an aggregate **Monthly spend cap** and **Current spend**. This is the enforced monetary ceiling for supported cost-bearing execution in the workspace. Do not assume the Agent's **Monthly spend cap** independently stops a call. Use it to track and alert on the Agent's contribution, and use the workspace cap as the documented execution boundary. A spend budget is separate from your plan's allowance of [governed actions](https://aethis.io/docs/concepts/governed-actions). See [Manage spend and usage](https://aethis.io/docs/guides/manage-spend-budgets) or [Set a spend budget](https://aethis.io/docs/guides/register-an-agent#set-a-spend-budget). ##### Agent status An Agent is **Active**, **Degraded**, **Paused**, **Suspended** or **Disabled**. **Paused** is a temporary stop you start with **Pause Route**: governed routes stop, the configuration remains, and **Resume Route** restores it. **Suspended** is a protective stop enforced by Aethis, which lasts until the triggering condition is resolved. **Disabled** means turned off administratively until someone re-enables it. See [Statuses](https://aethis.io/docs/reference/statuses#agents). #### Connections A **Connection** is an upstream destination an Agent may use through Aethis. - **MCP Connections** point at a remote MCP server by its HTTPS URL, with **Bearer**, **OAuth**, **mTLS** or **None** authentication. This is the main path in the beta. - **Model Routes** send model requests to a model provider through the Aethis Model Gateway. Direct model routing supports **OpenAI** (chat completions) only. A Connection belongs to one workspace, and you can assign it to any Agent in that workspace. Everything Aethis knows about the server's tools comes from [tool discovery](https://aethis.io/docs/concepts/tool-discovery). ##### The execution boundary Each MCP Connection has an **execution boundary** that all assigned Agents share: - **Governed**: calls can be evaluated and forwarded. - **Frozen**: execution is paused, usually because the server's tools changed and the change hasn't been reviewed. Calls through the Connection don't run until someone accepts or rejects the change. #### One endpoint per Agent Your client configures one Aethis MCP endpoint and one credential per Agent, however many Connections the Agent has: ```text URL: https://mcp.aethis.io/v1/agents/{agent_id}/mcp Header: Authorization: Bearer ``` The URL isn't a secret; the access key is. Behind that one endpoint, Aethis resolves each call in order: ```text Agent ──► assigned Connections ──► discovered capabilities ──► effective policy ──► upstream MCP server ``` Attaching or detaching a Connection changes what the Agent can reach through the same endpoint. You don't reconfigure the client. #### How the pieces fit ```text Workspace └─ Agent (identity + one MCP endpoint + access key + basic controls) ├─ Connections (which MCP servers or OpenAI routes it can reach) ├─ Policies (what it may do there: Allow, Require Approval, Block) └─ Tools (the discovered tools, with the access that results) ``` The [Control Map](https://aethis.io/docs/guides/read-the-control-map) draws this picture for any Agent. ### Register an Agent Canonical source: [https://aethis.io/docs/guides/register-an-agent](https://aethis.io/docs/guides/register-an-agent) > Register an Agent, connect your MCP client with the Aethis MCP server URL and access key, and set its Connections, Policies, basic controls and spend budget. An Agent is the identity your client uses to call tools through Aethis. Register one Agent per workload so each has its own key, policies and records. #### Before you begin Decide the Agent's name, the team that owns it, and the workspace it belongs in. Use a name that describes the job, such as **Billing Agent**, rather than an implementation detail. You also need: - permission to register Agents in the target workspace - any MCP Connections you want to attach already created in that workspace - a secret manager ready for the one-time access key - a published Policy, or a named owner who will add one before governed traffic is trusted #### Register the Agent 1. Open **Agents** and select **Register Agent**. 2. **Setup type.** Choose how the Agent works, then select **Continue**: - **MCP-only**: the Agent uses MCP tools through Aethis. Choose this for the beta's MCP-first path. - **Model-only**: the Agent sends model requests through a Model Route. - **Combined**: both a Model Route and MCP Connections. Model-only and Combined need a model provider. Direct model routing supports **OpenAI** only. 3. **Client.** Under **Choose how your agent connects**, select **MCP-compatible agent**, then **Continue**. No SDK is required. Choose **Custom HTTP** only for a Model-only Agent that sends OpenAI chat completions through the Aethis model gateway. [Screenshot: Register Agent, step 2 Client: MCP-compatible agent or Custom HTTP.](https://aethis.io/docs/guides/register-an-agent) 4. **Configure.** Enter the **Agent Name**, choose the **Owner** and **Workspace**, and optionally choose **MCP Connections** from the same workspace. You can assign Connections later. [Screenshot: Register Agent, step 3 Configure: Agent Name, Owner, Workspace and an optional MCP Connections picker.](https://aethis.io/docs/guides/register-an-agent) For a Model-only or Combined Agent, also choose the **Model Route** (a dedicated route is recommended). 5. Select **Register Agent**. 6. In **Agent created**, copy the **Aethis MCP server URL** and the **Aethis access key**, store the key in your secret manager, and select **Done**. [Screenshot: The Agent created dialog with the Aethis MCP server URL and Aethis access key.](https://aethis.io/docs/guides/register-an-agent) > **Caution** > The access key is shown in full only once. After you close the dialog, the Agent shows only its **Agent key fingerprint**. If you lose the key, rotate it. **Expected result:** the Agent appears in the workspace inventory with its owner and status. Its **Overview** shows the Agent identity and key fingerprint, while the full key remains only in your secret manager. #### Connect your client Configure your MCP-capable agent with the Agent's **Aethis MCP server URL**, and send the **Aethis access key** as a bearer token: ```text URL: https://mcp.aethis.io/v1/agents/{agent_id}/mcp Header: Authorization: Bearer ``` Copy the URL from the dashboard rather than building it by hand. The URL isn't a secret; the access key is. Each Agent has one endpoint and one credential, however many Connections it uses. Aethis identifies the Agent from the key, resolves the call through the Agent's assigned Connections, discovered tools and effective policy, and forwards allowed calls to the right upstream MCP server. Attaching another Connection later doesn't change your client configuration. If the client cannot connect, first confirm that it uses the URL copied from this Agent, sends the current access key as a bearer token, and that the Agent is **Active**. A **Paused**, **Suspended** or **Disabled** Agent is unavailable for a different reason; use the [Agent status definitions](https://aethis.io/docs/reference/statuses#agents) before rotating a working credential. #### Assign Connections 1. Open the Agent and select **Connections**. 2. Select **Attach connection**, choose an **MCP Connection** from the same workspace, and select **Attach MCP Connection**. [Screenshot: The Agent's Assigned connections table with a Model Route and two MCP servers, each with its status.](https://aethis.io/docs/guides/register-an-agent) The **Status** column shows each Connection's execution boundary. **Frozen** means tool changes are waiting for review; see [Review tool changes](https://aethis.io/docs/guides/review-tool-changes). Select **Detach** to remove a Connection from this Agent. #### Attach Policies 1. Open the Agent and select **Policies**. 2. Select **Attach Policy**, choose a published **Policy**, and select **Attach Policy**. [Screenshot: The Attach Policy dialog: apply a published policy directly to Billing Agent.](https://aethis.io/docs/guides/register-an-agent) The Policies list shows every book that applies and how it got there: **Direct** books you can detach; **Required** books come from the organization and can't be detached here. [Screenshot: The Agent's Policies list: Payments Policy, Data Handling, Model Access and Emergency Controls.](https://aethis.io/docs/guides/register-an-agent) #### Check tool access The **Tools** section lists every tool the Agent can reach, the Policies that apply to it, and its **Access**: - **Conditional**: policy evaluates each call. Select **Evaluate policy** to check an exact action without running it. - **Blocked**: policy blocks the tool. - **Unresolved**: Aethis can't evaluate the tool yet, for example because the Connection is paused or the tool's meaning needs review. The reason is shown underneath. #### Set basic controls On the Agent's **Overview**, **Basic controls** apply to every call the Agent makes. Turn a control on or off, then select **Save Changes** at the top of the page. [Screenshot: Data protection controls: PII redaction, Payment data redaction and Secrets redaction.](https://aethis.io/docs/guides/register-an-agent) - **PII redaction**, **Payment data redaction** and **Secrets redaction** mask sensitive values before they leave for a provider or tool. - **Unknown tool approval** holds untrusted tools for review. - **Tamper-evident evidence** records a hash-chained decision and policy snapshot. [Screenshot: Approvals & evidence controls: Unknown tool approval and Tamper-evident evidence.](https://aethis.io/docs/guides/register-an-agent) #### Choose Observe or Enforce Each Agent has an **Enforcement mode**. New Agents default to Observe Mode. - **Observe** (the default for new Agents): Aethis evaluates policy and writes an Action Record for each call, but doesn't block, hold or modify it. - **Enforce**: Aethis applies each decision. **Block** stops the call and **Require Approval** holds it for a reviewer. Before relying on Enforce, run representative traffic in Observe and check **Activity** for would-have-blocked or would-have-required-approval decisions. Confirm that: - expected writes are allowed or intentionally held - blocked actions really should stop - a reviewer covers the Approval Queue during the Agent's operating hours - the workload handles a held or blocked call without unsafe automatic retries - the Agent is in Enforce before you depend on **Block** or **Require Approval** to prevent execution See [Observe Mode](https://aethis.io/docs/concepts/observe-mode). #### Set a spend budget A spend budget tracks an Agent's spend and limits supported cost-bearing execution at the workspace level. It is separate from your plan's allowance of [governed actions](https://aethis.io/docs/concepts/governed-actions). 1. Open the Agent's **Overview** and find **Usage & limits**. 2. Set the Agent's **Monthly spend cap** and **Alert at** percentage, then select **Save Changes**. These values track the Agent and provide a warning threshold; do not rely on the Agent cap alone to stop execution. 3. Open **Settings** > **Workspace**, then find **Workspace spend controls**. 4. Set the workspace **Monthly spend cap** and save the change. **Expected result:** the Agent shows its cap, spend and warning threshold, and the workspace shows its saved cap and current spend. When spend reaches the workspace's enforced ceiling, Aethis stops the next supported cost-bearing execution before it runs. For selection guidance and diagnostics, see [Manage spend and usage](https://aethis.io/docs/guides/manage-spend-budgets). #### Rotate the key, pause or delete - **Rotate Key** replaces the Agent's access key. Update your client with the new key. - **Pause Route** makes the Agent's model and MCP paths unavailable until you select **Resume Route**. - **Delete Agent** removes it from the workspace and clears its Connection assignments. Its Action Records are kept. Each of these asks you to type a confirmation phrase, such as `ROTATE agent_billing_prod`. ### Observe Mode Canonical source: [https://aethis.io/docs/concepts/observe-mode](https://aethis.io/docs/concepts/observe-mode) > Each Agent has an Enforcement mode, Observe or Enforce. In Observe, Aethis evaluates policy and records the decision without blocking, holding or changing execution. New Agents start in Observe. Every Agent has an **Enforcement mode**: **Observe** or **Enforce**. New Agents default to Observe Mode. | Mode | What Aethis does | | ----------- | ----------------------------------------------------------------------------------------------------------------------------- | | **Observe** | Evaluates policy, records the decision and creates an Action Record. It does not block, hold or modify execution. | | **Enforce** | Evaluates policy, then enforces the decision: **Allow** forwards the call, **Require Approval** holds it, **Block** stops it. | New Agents default to **Observe**. Observe Mode lets you see what your agents actually do, and what your policy would do about it, before the policy has any consequences. #### What Observe Mode does - Evaluates each governed action against the Agent's Policies. - Records the decision the policy returned and writes a full Action Record. - Lets the call continue to the upstream server unchanged, whatever the decision. #### What it doesn't do - It doesn't block, hold or modify any call. An observed **Block** decision is not evidence that the call was stopped; the record's outcome shows what actually happened. - It doesn't observe calls that bypass Aethis. Only calls that go through the Agent's Aethis MCP endpoint are evaluated. #### The adoption path 1. **Observe.** Route a new Agent through Aethis. It starts in Observe. 2. **Understand what would be blocked.** In **Activity**, look at the actions the policy would have blocked or held, and the risky actions it missed. 3. **Fix your policies.** Tighten or loosen rules until the would-have-blocked list stops surprising you. Use **Evaluate policy** to check specific cases. 4. **Confirm readiness for Enforce.** In Enforce mode, Block and Require Approval take effect. Confirm the mode before relying on either decision to prevent execution. #### Prepare for Enforce Treat an Observe-to-Enforce change as an operational change: calls that policy blocks will stop, and calls that require approval will wait for a reviewer. Check the would-have-blocked traffic, reviewer coverage, upstream retry behavior and rollback owner first. See [Choose Observe or Enforce](https://aethis.io/docs/guides/register-an-agent#choose-observe-or-enforce). #### Counting An observed action is a governed action. Aethis evaluated it and wrote its record, so it counts as one, the same as an enforced action. See [Governed actions](https://aethis.io/docs/concepts/governed-actions). ### Manage spend and usage Canonical source: [https://aethis.io/docs/guides/manage-spend-budgets](https://aethis.io/docs/guides/manage-spend-budgets) > Set the enforced workspace spend cap, use Agent usage to find contributors, and respond safely when spend approaches the limit. Aethis separates Agent budget tracking from the workspace's enforced monetary control: - The workspace **Monthly spend cap** is the enforced ceiling for supported cost-bearing execution. - An Agent's **Usage & limits** shows its **Monthly spend cap**, **Spend this month** and **Alert at** warning threshold so you can understand which workloads contribute to workspace spend. - Your plan's governed-action allowance is a separate count. A blocked or held action can still count because Aethis evaluated and recorded it. #### Before you begin You need permission to change workspace settings and a monthly amount approved by the workspace owner. Agree on who responds to a **Budget Enforcement** alert and what work may be paused when the cap is reached. Choose a workspace cap that reflects the total supported cost-bearing traffic in the workspace. For example, a Production workspace with a USD 2,000 operating limit should use that workspace total. Agent caps can divide the monitoring target among workloads, but the workspace cap remains the documented execution boundary. #### Set Agent tracking and alerts 1. Open the Agent and find **Usage & limits** on **Overview**. 2. Set the **Monthly spend cap** used to track this workload. 3. Set **Alert at** to the percentage where its owner should investigate, then save the change. 4. Confirm that **Spend this month** appears against the saved cap. **Expected result:** the Agent shows current spend against its cap and can warn at the selected percentage. **Alert at** does not stop execution, and the Agent cap should not be treated as an independently enforced boundary. #### Set the workspace cap 1. Select the workspace you want to control. 2. Open **Settings** > **Workspace**. 3. Find **Workspace spend controls**. 4. Enter the **Monthly spend cap** and save the change. 5. Confirm that the saved cap and **Current spend** appear for the same workspace. **Expected result:** the workspace cap becomes the hard monetary boundary. When current spend reaches it, Aethis stops the next supported cost-bearing execution before it runs. > **Choose the workspace first** > Workspace settings apply to the selected workspace. Confirm the workspace switcher before changing a Production cap. #### Find what is driving spend Open **Agents** and start with the workspace totals. Then open an Agent's **Overview** and compare: | Measure | Use it for | | --------------------------- | ----------------------------------------------------------------------------------------- | | **Monthly spend cap** | The Agent's tracking target. Do not treat it as the documented execution stop. | | **Spend this month** | Compare the Agent's attributed spend with its cap and with other Agents in the workspace. | | **Alert at** | Decide when the Agent owner should investigate. This threshold does not stop execution. | | Workspace **Current spend** | Compare aggregate spend with the workspace's enforced **Monthly spend cap**. | Use **View Activity** from the Agent to inspect the time window around a spend increase. Filter to the Agent and relevant Connection, then compare the Action Records with the workload's expected traffic. #### Respond near or at the cap 1. Open the **Budget Enforcement** alert and select **Assign to me**. 2. Check the affected workspace, current spend, cap and related Agents. 3. Use Agent usage and Activity to distinguish expected volume from a retry loop, an unexpected model route or another anomaly. 4. If traffic is unsafe, pause the affected Agent route. If traffic is expected, have the workspace owner decide whether to change the cap or defer work. 5. Resolve the alert only after the underlying spend condition or traffic cause is addressed. Do not retry a cost-bearing action solely because it was stopped at a budget boundary. Confirm the action's outcome and the upstream state first, especially when an Action Record says **Outcome unknown**. #### Diagnose discrepancies **The Agent has spend, but the workspace total looks wrong.** Confirm that both views use the same workspace and monthly period. Then clear Activity filters and compare the relevant Agents and Connections for that period. **The Agent spend appears stale or empty.** Confirm the selected workspace and monthly period, then check that the Agent's governed traffic appears in Activity. If records are present but spend is still unavailable, preserve the Agent and Record IDs for support. **Calls stop before the cap appears reached.** Check the Agent's status and Connection state. **Paused**, **Suspended**, **Disabled**, **Frozen** and **Unavailable** describe different controls and failures; see [Statuses](https://aethis.io/docs/reference/statuses). **Spend reached the cap, but you need to know what ran.** The cap affects the next supported cost-bearing execution. Use [Investigate in Activity](https://aethis.io/docs/guides/investigate-activity) to distinguish completed, blocked, failed and unknown outcomes. #### Related controls - [Plans and governed actions](https://aethis.io/docs/reference/plans) explains the separate monthly action allowance. - [Respond to Alerts](https://aethis.io/docs/guides/respond-to-alerts) covers ownership and resolution states. - [Agents and Connections](https://aethis.io/docs/concepts/agents-and-connections#spend-budgets) explains where Agent tracking fits. ## Connections ### Connect an MCP server Canonical source: [https://aethis.io/docs/guides/connect-an-mcp-server](https://aethis.io/docs/guides/connect-an-mcp-server) > Add your existing remote MCP server as a Connection, connect its account, refresh its tools, and assign it to Agents. A Connection tells Aethis where to forward an Agent's allowed tool calls. You keep your existing MCP server; Aethis sits in front of it. ```text your agent ──► the Agent's Aethis MCP endpoint (mcp.aethis.io) ──► Aethis governance ──► your MCP server (the Connection) ``` Your agent doesn't connect to each Connection separately. It uses one endpoint per Agent, `https://mcp.aethis.io/v1/agents/{agent_id}/mcp`, and Aethis resolves every Connection assigned to that Agent behind it: Agent, assigned Connections, discovered capabilities, effective policy, then the upstream MCP server. #### Before you begin - The MCP server's **HTTPS URL**, and how it authenticates: **Bearer**, **OAuth**, **mTLS** or **None**. - Permission to add Connections in the workspace. Your organization may allow only approved servers. - A non-production server or account for the first discovery and policy test, when the upstream service can cause side effects. - The server owner's confirmation of the tool names, parameter schema, amount units and environment you expect to discover. #### Add the Connection 1. Open **Connections** and select **Add connection**. 2. Choose **MCP** (Connect agents to tools on an MCP server), then select **Next**. [Screenshot: Add connection, step 1 of 3: choose Model or MCP.](https://aethis.io/docs/guides/connect-an-mcp-server) 3. Choose the server. Pick one your organization has already set up, or select **Custom server** to connect an MCP server by its URL. [Screenshot: Add connection, step 2 of 3: Choose an MCP server, with Internal Billing and Custom server options.](https://aethis.io/docs/guides/connect-an-mcp-server) 4. For a custom server, enter a **Connection name**, the **MCP server URL** (use the HTTPS address provided by your server), and the **Authentication** method. 5. Select **Add Connection**. In **Connection added**, select **Open connection**. > **Note** > If you see "Only organization-approved servers can be connected", ask an organization admin to approve the server, or use **request access** on that page. #### Connect the account and refresh tools A new Connection shows what it needs next at the top of its **Overview**. [Screenshot: The Finance MCP Connection overview: Tool changes need review, with account connection Healthy, 12 tools, Bearer authentication.](https://aethis.io/docs/guides/connect-an-mcp-server) 1. If it shows **Connect account**, select it and follow the authorization prompts for the server. 2. Select **Refresh tools**. Aethis discovers the server's tools and fingerprints each definition. Discovery doesn't count as a governed action. 3. Review anything flagged. See [Review tool changes](https://aethis.io/docs/guides/review-tool-changes). 4. When the Connection shows **Ready**, its tool catalogue is current and available for policy checks. Select **Check connection** at any time to test that the server is reachable. **Expected result:** the Connection is **Ready**, its health is **Healthy**, and the **Tools** section shows the catalogue you expected. **Ready** means the catalogue can participate in policy checks; an Agent still needs the Connection assigned and an applicable Policy before you rely on the path. #### Assign it to Agents Open an Agent, select **Connections**, then **Attach connection**. You can only attach Connections from the Agent's own workspace. The Connection's **Assigned agents** section lists every Agent using it. You don't need to change the Agent's client configuration. The new Connection's tools become reachable through the Agent's existing Aethis MCP endpoint, subject to its Policies. After assignment, open the Agent's **Tools** section. A tool should be **Conditional**, **Blocked** or **Unresolved** with a reason. Use **Evaluate policy** for a harmless example such as a read against a non-production resource; policy evaluation does not execute the action. #### Diagnose connection states | State | What to check | | ----------------------- | ---------------------------------------------------------------------------------------------------------- | | **Connect account** | Complete the server's authentication flow. Do not paste credentials into a support ticket. | | **Refresh tools** | Run discovery, then compare the returned catalogue with the server owner's expected schema. | | **Review changes** | Review every pending definition change. Calls remain frozen until the catalogue decision is complete. | | **Review tool meaning** | Confirm semantic details such as effect, amount unit and currency before relying on amount-based policies. | | **Unavailable** | Use **Check connection**, then verify the HTTPS URL, authentication and upstream health. | #### Manage the Connection [Screenshot: The Connections list: MCP Connections with their tool counts, assigned Agents and status.](https://aethis.io/docs/guides/connect-an-mcp-server) The Connections list shows each Connection's usage and status. Open one to see its **Overview**, **Tools**, **Assigned agents** and **Settings**. - **Settings** shows the name, Connection ID, server URL, authentication and execution boundary. Select **Edit connection** to rename it; the Connection ID stays the same. - **Delete connection** removes it from the workspace and removes that path for every assigned Agent. Historical Action Records are kept. Aethis asks you to type a confirmation phrase. #### Model Routes (OpenAI) The **Model Routes** tab holds routes for direct model requests through the Aethis Model Gateway. Direct model routing supports **OpenAI** chat completions. 1. Select **Add connection**, choose **Model**, and create the route. 2. Save the generated **Gateway URL** when it is shown. 3. Assign the route to a **Model-only** or **Combined** Agent in the same workspace. 4. Confirm the route is **Ready**, then use Activity to verify that a model request produces the expected policy decision and Action Record. The Gateway URL is the model route's endpoint. It is distinct from the Agent's Aethis MCP server URL used by MCP-compatible clients, so copy the URL shown for the route instead of substituting the MCP endpoint. **Expected result:** the Agent lists the assigned Model Route and governed model requests appear in Activity. If the route shows **Verify route**, check its workspace allocation. For **Degraded** or **Unavailable**, inspect the route and provider health before retrying. ### Tool discovery and review Canonical source: [https://aethis.io/docs/concepts/tool-discovery](https://aethis.io/docs/concepts/tool-discovery) > Aethis discovers the tools an MCP server offers, fingerprints each definition, and pauses execution when a definition changes until someone reviews it. Aethis can only govern a tool it understands. **Tool discovery** is how Aethis learns what an MCP server offers, and **review** is how you decide whether a new or changed tool may be used. #### Discovery When you select **Refresh tools** on a Connection, Aethis asks the MCP server for its tool catalogue and records each tool's definition: its name, description and parameters. Each definition gets a **capability fingerprint**, so Aethis can tell later whether the tool it is being asked to call is the same tool you reviewed. Discovery requests, health checks and pings are not governed actions and don't count against your plan. #### Why changes pause execution An MCP server can change a tool's definition at any time. A refund tool whose amount switches from whole currency units to cents, for example, would make an approved "SGD 500" limit mean something very different. So when a refresh returns a definition that differs from the one you accepted, Aethis: 1. marks the tool **Changed** and the Connection **Review changes** 2. sets the Connection's execution boundary to **Frozen**, so calls through it don't run 3. opens a **Capability Drift** alert for the affected Agents Nothing runs through the changed Connection until someone reviews the catalogue. #### Review The Connection's **Tools** section shows the previously accepted definition next to the new one. The review decision applies to **all pending changes in the Connection**: - **Accept catalogue** trusts the new definitions and lifts the pause. - **Reject changes** records that you didn't accept them and keeps the Connection **Frozen**. Fix the server, then select **Refresh tools** and review again. Acknowledging the Capability Drift alert doesn't resume execution. Only the catalogue review does, and the alert can't be resolved until the review is done. #### Tool meaning Some tools need more than a matching definition before policy can evaluate them. A refund tool's amount needs a confirmed unit and currency, for example. When a catalogue is current but a tool's meaning is still unresolved, the Connection shows **Review tool meaning**, and the tool's access on an Agent shows **Unresolved** until it is reviewed. #### Tool trust states A discovered tool is **Trusted**, **New**, **Changed**, **Removed** or **Stale**. See [Statuses](https://aethis.io/docs/reference/statuses#tools-and-connections). To do the review, follow [Review tool changes](https://aethis.io/docs/guides/review-tool-changes). ### Review tool changes Canonical source: [https://aethis.io/docs/guides/review-tool-changes](https://aethis.io/docs/guides/review-tool-changes) > When an MCP server's tool definitions change, Aethis pauses the Connection until you compare the definitions and accept or reject the catalogue. When a refresh finds that a tool's definition changed, Aethis pauses execution through that Connection until someone reviews it. This guide covers the review. For why it works this way, see [Tool discovery and review](https://aethis.io/docs/concepts/tool-discovery). #### Before you begin Confirm the expected server release or configuration change with the team that owns the MCP server. The review applies to every pending change in the Connection, so do not accept based on one familiar tool while another changed unexpectedly. #### How you'll know - The Connection's status is **Review changes**, and its overview says "Tool changes are paused until the catalogue is reviewed." - On assigned Agents, the Connection shows **Frozen** and its tools show **Unresolved** with "Connection is paused". - A **Capability Drift** alert opens in **Alerts**. #### Review the catalogue 1. Open the Connection (from **Connections**, or **Review changes** on the alert) and select **Review changes**. The **Tools** section opens. 2. Select **Needs review** to list only the tools that changed. Changed tools are marked with **!**. 3. Select a tool. Compare **Previously accepted** with **New definition**, and check its **Parameters**. [Screenshot: Reviewing a changed tool: Issue refund's amount units changed from whole currency units to not confirmed, with Accept catalogue and Reject changes.](https://aethis.io/docs/guides/review-tool-changes) 4. Decide under **Catalogue review**. The decision applies to **all pending changes in this Connection**: - **Accept catalogue** if every change is expected and safe. The Connection returns to **Governed**. - **Reject changes** if anything is unexpected. The Connection stays **Frozen**. Fix the server, select **Refresh tools**, and review again. **Expected result:** after **Accept catalogue**, the accepted capability fingerprints match the reviewed definitions and the Connection returns to **Governed**. After **Reject changes**, it remains **Frozen** until the upstream server is corrected and a later refresh produces a catalogue you accept. > **Check what the change means for your policies** > A change in units or meaning can change what an existing rule allows. If a refund amount moves from whole units to cents, a "SGD 500" limit no longer means what it did. Update the Policy before or right after you accept. #### Review tool meaning A Connection can show **Review tool meaning** even when its catalogue is current. This means some tools still need their effect or amount format confirmed before policy can evaluate them. Open the Connection's **Tools**, check the flagged tools, and confirm their meaning. If the Connection stays **Review changes**, look for another pending tool in the same catalogue. If it becomes **Review tool meaning**, the definitions are current but a semantic detail such as effect, amount unit or currency still prevents reliable evaluation. If it is **Unavailable**, test reachability with **Check connection** instead of repeatedly accepting the catalogue. #### Close the alert Acknowledging a Capability Drift alert doesn't resume execution. After you accept or reject the catalogue, open the alert and resolve it. See [Respond to Alerts](https://aethis.io/docs/guides/respond-to-alerts). ## Policies ### Policies and decisions Canonical source: [https://aethis.io/docs/concepts/policies](https://aethis.io/docs/concepts/policies) > A Policy is a versioned set of rules. Aethis evaluates the Policies that apply to an Agent and reaches one decision, Allow, Require Approval or Block. A **Policy** is a named, versioned set of rules. Assign a published Policy to an Agent (or a workspace or Connection) and Aethis applies its rules to every governed action in scope. #### Decisions Every governed action gets exactly one decision: | Decision | What happens | | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | | **Allow** | Aethis forwards the call to the upstream server and records the result. | | **Require Approval** | Aethis holds the call and creates a request in the [Approval Queue](https://aethis.io/docs/concepts/approvals). Nothing runs until a reviewer decides. | | **Block** | Aethis stops the call. No upstream execution is attempted. | Redaction is not a decision. Redacting personal data, payment data or secrets is an [Agent control](https://aethis.io/docs/concepts/agents-and-connections#basic-controls) that applies alongside whatever the policy decides. #### Rules Each rule names who it applies to, which tool on which Connection, which resource, an optional condition, and the decision. The dashboard reads a rule back as a sentence, for example: > Require Approval Billing Agent to use tool refund.create from Finance MCP on stripe.production when amount is above SGD 1,000. The full field list is in the [Policy rule model](https://aethis.io/docs/reference/policy-rules). #### When more than one rule could match - **Scope comes first.** A rule for a specific operation and a specific Agent is more specific than a rule for that operation and any Agent, which is more specific than a rule that matches a tool's reviewed meaning (a Semantic Profile). If nothing decides the action, it remains **Unresolved** rather than becoming an implied Allow. - **Keep same-scope rules disjoint.** Conditions at the same scope should cover separate ranges or cases. If two same-scope rules overlap and disagree, narrow one before publishing. - **Treat priority as descriptive metadata.** The editor displays and validates a numeric priority, but you should not rely on that number to make conflicting same-scope rules safe. See [Rule precedence](https://aethis.io/docs/reference/policy-rules#rule-precedence) for the full order. #### Versions and publishing - You edit a **draft**. Drafts don't affect any Agent. - **Publish Version** turns the draft into an immutable published version with its own version label (for example `payments-v12`) and hash. - Agents run against the published version. Every Action Record names the Policy version and the matched rule that produced its decision. - To change a published book, create a new draft from it and publish again. Earlier versions stay in the book's history. #### Where a Policy applies A Policy has a **scope**, such as **Workspace · Production** or **Organization · All**, and **assignments** to Agents, workspaces or Connections. On an Agent's **Policies** section, each book shows how it arrived: - **Direct**: assigned to this Agent. - **Required**: required by the organization. You can't detach it from the Agent. - **Inherited**: applied through a workspace or organization assignment. Organization Policies can be offered to workspaces as **Available**, turned on by default (**Default On**), or made **Required**. #### Library states | State | Meaning | | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- | | **Active** | Published and enforced. | | **Draft** | Not published yet. | | **Disabled** | Published but not enforced. You can enable it again. | | **Archived** | Retired. Custom books can be restored. | | **Conflict** | A rule or assignment references something that no longer resolves, such as a removed Connection. Create a draft to fix the reference and republish. | Books are either **Custom** (yours) or **Aethis Managed** (templates you can clone and adapt). #### Test before you rely on it Use **Evaluate policy** on an Agent's **Tools** section to check an exact action against the Agent's policies without running it. [Observe Mode](https://aethis.io/docs/concepts/observe-mode) goes further: it records what a policy would do to real traffic while execution continues unchanged. ### Create and publish a Policy Canonical source: [https://aethis.io/docs/guides/create-a-policy](https://aethis.io/docs/guides/create-a-policy) > Build a Policy with the Builder, Policy as Code or the refund template, publish a version, and assign it to an Agent. A Policy decides what happens to each governed action: **Allow**, **Require Approval** or **Block**. You work on a draft, publish an immutable version, and assign it. For the model behind this, see [Policies and decisions](https://aethis.io/docs/concepts/policies). [Screenshot: The Policies library with filters for All, Published, Drafts, Disabled, Archived and Conflicts.](https://aethis.io/docs/guides/create-a-policy) #### Before you begin - Create or identify the target Connection and Agent in the intended workspace. - Confirm the tool's definition and meaning. Amount rules need a known unit and currency. - Write down representative actions that should be allowed, held and blocked. Include boundary values. - Decide who will review approval requests and what should happen if no rule decides an action. #### Create a Policy 1. Open **Policies** and select **New Policy**. 2. **Details.** Enter a **Policy Name**, choose the **Scope** (for example **Workspace · Production** or **Organization · All**), and describe the change in **Change Summary**. Select **Continue**. [Screenshot: The New Policy builder with three steps: Details, Rules and Review.](https://aethis.io/docs/guides/create-a-policy) 3. **Rules.** Select **Add rule** for each rule. For an MCP tool rule, choose the **Subject** (who it applies to), the **Connection**, the discovered **Tool**, the **Resource**, an optional **Condition**, the **Decision** and its **Priority**. The builder reads each rule back as a sentence so you can check it. Keep same-scope conditions disjoint. For example, use non-overlapping refund bands: allow through SGD 500, require approval above SGD 500 through SGD 1,000, and block above SGD 1,000. Do not depend on the numeric priority field to settle overlapping decisions. 4. **Review.** Check the rules and select **Validate draft**. Fix anything marked invalid. 5. Select **Save Draft**. Drafts don't affect any Agent. 6. Select **Publish Version**. Aethis creates an immutable version with its own version label and hash. **Expected result:** the Policy has an **Active** published version with a version label and hash. Publishing preserves the version; assignment determines where it applies. > **Prefer code?** > Switch to **Policy as Code** to edit the same draft as JSON (schema `aethis.policy/v1`), and use **Validate Policy** to check it. **Compiled policy** shows exactly what Aethis will evaluate. See the [Policy rule model](https://aethis.io/docs/reference/policy-rules). #### Use the refund template For a common case, select **Create refund policy**. It builds a three-band refund boundary for one Connection: [Screenshot: Create refund policy: choose a Connection and set Allow through and Require approval through limits in SGD.](https://aethis.io/docs/guides/create-a-policy) 1. Choose **New Policy** (or an existing Policy to edit) and enter a **Policy name**. 2. Choose the **Connection / account** and the refund **Action**. 3. Set **Allow through** and **Require approval through**. Amounts above the approval limit are blocked. Other applicable restrictions still apply. 4. Select **Save draft**, then **Publish version**. The template needs the refund tool's meaning to be confirmed first. If it says "Refund meaning needs review before evaluation", [review the tool](https://aethis.io/docs/guides/review-tool-changes#review-tool-meaning). #### Assign it A published version doesn't do anything until it applies to an Agent. - **From the Agent:** open the Agent, select **Policies**, then **Attach Policy**. - **From the Policy:** open it and select **View assignments** to see and manage where it applies. #### Change a published Policy [Screenshot: A Policy's overview: scope, status Active, version payments-v12, and Applied to 4 agents, 1 workspace and 2 connections.](https://aethis.io/docs/guides/create-a-policy) 1. Open the Policy and select **Edit policy**. Aethis creates a draft from the current version. 2. Make your changes and publish a new version. 3. Use **Details & history** to see earlier versions and **Compare Policy Versions** to see exactly what changed. Under **More** you can **Disable Policy** (stop enforcing it without deleting it), **Enable Policy** again, **Replace Policy** with another active book, or delete it. #### Fix a conflict A book in **Conflict** references something that no longer resolves, such as a deleted Connection. Select **Edit policy** to create a repair draft, remove or replace the unavailable targets, and publish again. Published history is kept. #### Check it before you rely on it - On the Agent's **Tools** section, use **Evaluate policy** to test an exact action without running it. - Run the Agent in [Observe Mode](https://aethis.io/docs/concepts/observe-mode) to see what the policy would do to real traffic. Test the boundary and one value on each side. For the example bands above, check SGD 500, SGD 501, SGD 1,000 and SGD 1,001. An **Unresolved** result means you still have a gap, an overlap, an unavailable reference or tool meaning that needs review; do not interpret it as Allow. ### Policy rule model Canonical source: [https://aethis.io/docs/reference/policy-rules](https://aethis.io/docs/reference/policy-rules) > The fields of a Policy and its rules, as shown in Policy as Code (schema aethis.policy/v1). A Policy can be edited in the **Builder** or as JSON in **Policy as Code**. Both edit the same draft. This page describes the JSON form. #### Document ```json { "schemaVersion": "aethis.policy/v1", "metadata": { "name": "Payments Policy", "scope": "Workspace · Production", "summary": "Approval controls for production financial operations." }, "defaultDecision": "No match", "rules": [ { "name": "Finance write approval", "plane": "mcp_gateway", "subject": "Billing Agent", "connection": "Finance MCP", "capability": { "type": "Tool", "id": "refund.create" }, "resource": "stripe.production", "condition": "amount > 1000 SGD", "decision": "require_approval", "obligations": [], "priority": 100 } ] } ``` | Field | Meaning | | ------------------ | ----------------------------------------------------------------------------------- | | `schemaVersion` | Always `aethis.policy/v1`. | | `metadata.name` | The Policy name. | | `metadata.scope` | Where the book lives, for example `Workspace · Production` or `Organization · All`. | | `metadata.summary` | A short description of the book. | | `defaultDecision` | What this book returns when no rule matches: `No match`, or one of the decisions. | | `rules` | The rules. See below. | #### Rule fields | Field | Values | Meaning | | ------------- | ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | `name` | text | A readable name. Shown as the **Matched rule** in Action Records. | | `plane` | `mcp_gateway`, `model_gateway` | Whether the rule governs MCP tool calls or model requests (OpenAI routes). | | `subject` | text | Who the rule applies to, such as an Agent. | | `connection` | a Connection or Model Route in scope | Which upstream destination the rule covers. | | `capability` | `{ "type": "Tool", "id": "…" }` | The discovered capability, such as a tool, the rule covers. | | `resource` | text | The target the action acts on. | | `condition` | text, optional | An extra condition, such as an amount threshold. | | `decision` | `allow`, `require_approval`, `block` | Shown in the dashboard as **Allow**, **Require Approval**, **Block**. | | `obligations` | list | Additional requirements recorded with the decision. | | `priority` | number | Numeric metadata shown and validated by the editor. Do not use it to make overlapping same-scope rules safe. See [Rule precedence](https://aethis.io/docs/reference/policy-rules#rule-precedence). | Every reference must resolve. A rule that points at a Connection or capability that no longer exists puts the book in **Conflict** until you publish a fixed version. #### Rule precedence When more than one rule matches an action, Aethis decides between them in two stages. **1. Scope precedence.** A more specific scope wins over a less specific one. From most to least specific: 1. Workspace + Operation + a specific Agent 2. Workspace + Operation + any Agent 3. Workspace + Semantic Profile (a rule that matches a tool by its reviewed meaning, such as its effect, rather than by the operation) 4. Default deny **2. Disjoint conditions within one scope.** Keep rules at the same scope from overlapping. A numeric `priority` is present in the document and shown in the compiled preview, but it is not a safe way to resolve conflicting decisions. **Conflicts remain unresolved.** If same-scope rules can both apply and disagree, narrow the subject, capability, resource or condition before publishing. Do not change only `priority` and assume the conflict is resolved. #### How rules read in the dashboard The Builder reads each rule back as a sentence: - MCP: **Require Approval** Billing Agent to use tool refund.create from Finance MCP on stripe.production when amount > 1000 SGD. - Model: **Allow** Support Agent to send model requests through Production OpenAI Route to the route's model. #### Versions Publishing creates an immutable version with a version label and a hash. Action Records name the version and the matched rule that produced each decision. Use **Compare Policy Versions** to see the difference between two versions. #### Validation Use **Validate draft** in the Builder or **Validate Policy** in Policy as Code. Aethis reports each problem with its path in the document. **Compiled policy** shows what Aethis will evaluate after publishing. ### Verify a governance boundary Canonical source: [https://aethis.io/docs/guides/verify-governance](https://aethis.io/docs/guides/verify-governance) > Test policy boundaries without execution, confirm Observe or Enforce semantics, and verify the resulting decision, approval, outcome and record integrity. Use this procedure before relying on a policy boundary and when you need evidence that Aethis evaluated a particular action, applied the expected policy and recorded what happened. It combines **Evaluate policy**, Observe or Enforce semantics, the Action Record's three tabs and the **Verify Chain** consistency check. #### Before you begin For a pre-deployment check, you need an Agent with its intended Connection and published Policy attached. Confirm the tool definition and meaning first; a changed, frozen or unresolved tool cannot provide a trustworthy boundary result. For an evidence review, collect the smallest identifiers available: workspace, approximate time, Agent, Connection, resource, approval request ID, correlation ID or Record ID. Do not collect access keys or paste full sensitive arguments into investigation notes. Decide the question before opening Activity. Common examples are: - Did policy block the call before anything reached the upstream server? - Did a reviewer approve this exact action, and was that approval consumed? - Did the allowed call succeed, fail, or end with an unknown outcome? - Are the expected record links and integrity metadata present for this scope? #### Test the policy boundary safely Use **Evaluate policy** on the Agent's **Tools** section. It previews a decision for an exact action without executing the tool. 1. Open the Agent, select **Tools**, and choose the intended tool and Connection. 2. Select **Evaluate policy** and enter a non-production resource with representative arguments. 3. Test each boundary value and one value on either side. 4. Record the Policy version and expected decision for each case. For the sample refund policy used in the quickstart, the checks are: | Safe test input | Expected preview | | --------------- | --------------------- | | SGD 500 | **Allowed** | | SGD 501 | **Approval required** | | SGD 1,000 | **Approval required** | | SGD 1,001 | **Blocked** | Use your own policy's units and boundary values outside the sample. An **Unresolved** preview is not an Allow. Check for a missing or overlapping condition, an unavailable reference, a frozen Connection or unreviewed tool meaning before continuing. **Expected result:** every boundary case produces the intended preview from the intended published Policy. The preview does not run the action. #### Confirm Observe or Enforce semantics Next, use representative traffic and check Activity: - In **Observe**, Aethis records what policy decided but does not block, hold or modify the call. An observed **Block** is evidence of the policy result, not evidence that execution was prevented. - In **Enforce**, **Block** stops the call and **Require Approval** holds it. Confirm the Agent's mode before relying on either decision to prevent execution. Observe is useful for comparing the evaluated decision with real traffic before enforcement. For a consequential test, use a non-production resource and an action whose effect is safe and reversible. #### Verify the resulting evidence ##### Find the Action Record 1. Open **Activity** and switch to **Action Records**. 2. Filter to the workspace, Agent, Connection and narrow time window. 3. Search by Record ID, correlation ID, action, resource or another known identifier. 4. Open the record and confirm that the Agent, Connection, resource and capability fingerprint describe the action you are investigating. If no record appears, clear filters one at a time and confirm the client used the Agent's Aethis endpoint. Calls that bypass Aethis do not produce an Action Record. ##### Check policy and approval evidence Open **Governance** and record: - the Policy and immutable version - the **Matched rule** and decision - the approval request and single-use approval IDs, when present - the sequence and timestamps in **Record lifecycle** For a **Require Approval** decision, open the linked approval and compare its action fingerprint with the record. **Approve Once** only authorizes that exact action and does not execute it. The lifecycle should keep the policy decision, human decision, approval consumption and execution result separate. ##### Check the outcome Open **Summary** and interpret the outcome literally: | Outcome | What it establishes | | -------------------------------- | -------------------------------------------------------------------------------------- | | **Blocked, not executed** | Policy stopped the action at Aethis; no upstream execution was attempted. | | **Approval pending** | The action is held and has not been executed. | | **Approved, awaiting execution** | A single-use approval exists, but the matching call has not used it. | | **Execution succeeded** | The upstream call completed. | | **Execution failed** | The call failed and Aethis knows the side effect did not happen. | | **Outcome unknown** | Dispatch may have happened, but no definite result was received. Check upstream first. | Never treat **Outcome unknown** as a safe retry signal. Check the upstream system for the resource or side effect before another attempt. ##### Check record integrity 1. Open **Integrity** and inspect the record's link status, chain value, previous-record reference and retention. 2. Select **Open Previous Record** when you need to follow the recorded link backward. 3. Return to Activity and select **Verify Chain**. 4. Choose **Current workspace · current filters** for a bounded set, or **Selected record only** when a record is open. 5. Select **Run Verification**. **Expected result:** Aethis reports how many records were checked and whether it found record consistency issues. The check does not change records. ##### Respond to integrity statuses | Status | Response | | -------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | **Intact** | The expected integrity and link metadata is available and the check completed successfully. Continue with policy and outcome review. | | **Delayed** | Wait for expected evidence or link metadata, then run the same scoped check again. Preserve the Record ID if the delay persists. | | **Degraded** | Treat assurance as reduced. Open the record, note which evidence is affected and start an Evidence Integrity investigation. | | **Gap** | An expected event, link or durable result is confirmed missing. Start an investigation and preserve the surrounding record IDs. | | **Unverified** | Run **Verify Chain** for the selected record or bounded scope. If verification cannot complete, start an investigation. | An **Evidence Integrity** alert should have an owner and remain **Investigating** until the underlying record condition is understood. Acknowledge alone does not restore integrity. ##### Record the result For an audit note or support case, include: - workspace and time window - Record ID and correlation ID - Agent, Connection and resource - Policy version, matched rule and decision - approval request or single-use approval ID, if any - outcome and integrity status - verification scope and number of issues reported Keep credentials and unredacted sensitive arguments out of the note. See [Security and data](https://aethis.io/docs/reference/security-and-data) for retention and credential handling. ## Approvals ### Approvals bound to an exact action Canonical source: [https://aethis.io/docs/concepts/approvals](https://aethis.io/docs/concepts/approvals) > When policy says Require Approval, Aethis holds the exact action for a reviewer. An approval is single-use, bound to that action, and does not execute it. When a rule's decision is **Require Approval**, Aethis holds the action and creates an approval request in the **Approval Queue**. A reviewer then approves or denies **that exact action**, not a category of actions and not the Agent in general. [Screenshot: Approval is bound to the exact action: the request, the reviewer's decision and the Action Record share one action fingerprint.](https://aethis.io/docs/concepts/approvals) #### What "exact action" means Each request carries an **action fingerprint** that identifies the precise call: the Agent, the Connection, the tool (by its **capability fingerprint**), the resource, and the arguments. The reviewer sees all of it before deciding: - **Summary**: owner, when it was requested, reversibility, amount and the risk reason. - **Exact Action**: Agent, MCP Connection, capability, resource, arguments summary and fingerprints. - **Policy**: the Policy version and the matched control that required approval. - **Evidence**: the linked Action Record. #### Approve Once and Deny A reviewer has two choices. Both require a written **reason**, which is recorded in the Action Record. - **Approve Once** issues a **single-use approval** for this action fingerprint. Approval does not execute the action. When the Agent makes the same call, it runs once. A different amount, target or tool is a different action and is evaluated again. - **Deny** refuses the request. The action is not executed through this request. Requests have a deadline. A request that isn't decided in time **Expires**, and the action doesn't run. #### Approval is not execution Aethis keeps the decision and the outcome separate. An Action Record shows the **Policy decision**, the **Human decision**, the **Single-use approval**, and the **Execution** result as separate lifecycle steps, so "approved" is never mistaken for "succeeded". Approval lifecycle states are listed in [Statuses](https://aethis.io/docs/reference/statuses#approval-requests). #### Who can review Reviewers are organization members with a role that allows reviewing, such as the built-in **Reviewer** role or a custom role like **Production Reviewer**. See [Manage your organization and workspaces](https://aethis.io/docs/guides/manage-organizations-and-workspaces). ### Review the Approval Queue Canonical source: [https://aethis.io/docs/guides/review-approvals](https://aethis.io/docs/guides/review-approvals) > Find a held action in the Approval Queue, check exactly what it would do, and Approve Once or Deny with a reason. When a rule says **Require Approval**, Aethis holds the action and adds a request to the **Approval Queue**. Your decision applies to that exact action only. See [Approvals bound to an exact action](https://aethis.io/docs/concepts/approvals). #### Before you begin You need a role that can review requests in the request's workspace. You also need enough business context to judge the target, amount and reversibility. If you cannot establish that context, deny the request with a clear reason. #### Find the request Open **Approval Queue**. The sidebar badge counts active requests. [Screenshot: The Approval Queue: four active requests with their agent and target, priority, deadline, assignee and status.](https://aethis.io/docs/guides/review-approvals) - **Active**, **Resolved** and **All** switch between open and decided requests. - Filter by assignee (**Everyone**, **Assigned to me**, **Unassigned**), by **Expiring within 20m**, or by severity. - Each row shows the requested action, the Agent and target, the priority and deadline, the assignee and the status. Start with requests that are about to expire. An expired request doesn't run. #### Check the exact action Select a request to open it. [Screenshot: An approval request for refund.create: summary, risk reason and a lifecycle showing Approval required, human decision Pending, no approval issued, execution not attempted.](https://aethis.io/docs/guides/review-approvals) Work through the tabs: | Tab | Check | | ---------------- | ------------------------------------------------------------------------------------------------------------------- | | **Summary** | Owner, requested time, **Reversibility**, amount, the **Risk reason**, and the **Lifecycle**. | | **Exact Action** | Agent, MCP Connection, capability, **Resource**, **Arguments summary**, and the action and capability fingerprints. | | **Policy** | The Policy version, the **Matched control**, and how organization, workspace and Agent-level policy each evaluated. | | **Evidence** | The linked Action Record. Select **Open Action Record** to see it in Activity. | Ask yourself: is this the right target, the right amount, and something the Agent should be doing? If you can't tell, deny it and say why. For example, a request for `refund.create` should name the expected customer or transaction resource, show the intended amount and currency, and match the reason for the refund. A familiar tool name is not enough if the resource or arguments differ. #### Decide 1. Select **Approve Once** or **Deny**. 2. Enter a **Reason**. It is required and is recorded in the Action Record. [Screenshot: The Approve Once dialog: approve this exact action once; approval does not execute it. A reason is required.](https://aethis.io/docs/guides/review-approvals) 3. Confirm with **Approve Once** or **Deny Request**. - **Approve Once** issues a single-use approval for this exact action. It doesn't run the action. When the Agent makes the same call, it runs once. Any change to the action means a new evaluation. - **Deny** refuses the request. The action isn't executed through this request. **Expected result:** the request moves out of **Pending**. An approval becomes **Approved, awaiting execution** until the Agent submits the matching call; a denial becomes **Denied** and does not execute through that request. #### Follow the outcome The request's **Lifecycle** shows the policy decision, the human decision, the single-use approval and the execution result as separate steps. An approved action moves from **Approved, awaiting execution** to **Execution in progress** and then **Execution succeeded**. It can also end in **Execution failed**, or in **Outcome unknown** if the result was lost; an unknown outcome is never reported as failed. Open the Action Record to see the final outcome. If an approved request stays **Approved, awaiting execution**, check whether the Agent retried the exact action before the approval expired. A changed target, amount, arguments or capability fingerprint is a different action and needs a new evaluation. If the result is **Outcome unknown**, check the upstream system before allowing any retry. #### Bring in more reviewers Invite teammates with a reviewing role. See [Manage your organization and workspaces](https://aethis.io/docs/guides/manage-organizations-and-workspaces#invite-a-member), or run the **Bring in an approval reviewer** journey from **Get started**. ## Activity & evidence ### Governed actions Canonical source: [https://aethis.io/docs/concepts/governed-actions](https://aethis.io/docs/concepts/governed-actions) > A governed action is one agent action that Aethis evaluated and recorded. It is the unit of your plan allowance. A **governed action** is one agent action that Aethis **evaluated and recorded**. It is the unit Aethis counts against your plan's monthly allowance. The count follows evaluation, not execution. An action counts once Aethis has evaluated it and written its Action Record, whether the decision was to allow it, block it, or hold it for approval. #### Counting rules | Scenario | Governed actions | | ------------------------------------------------ | ---------------: | | One model call | 1 | | One tool call | 1 | | One model call followed by 4 governed tool calls | 5 | | An action blocked by policy | 1 | | An action waiting for approval | 1 | | An idempotent retry of the same action | 1 total | | MCP discovery, health checks and pings | 0 | #### Why a model call and its tool calls count separately A model deciding to issue a refund and the refund being issued are two actions with two consequences. Aethis evaluates each one, and either can be allowed, held or blocked on its own. A turn with one model call and four governed tool calls is five governed actions. #### Why blocked and held actions count A blocked or held action still needed Aethis to identify the Agent, evaluate policy, reach a decision and write an Action Record. The governance work happened even though nothing ran upstream. #### Retries An idempotent retry of the same action belongs to the original governed action and doesn't add to the count. #### What doesn't count Traffic that carries no agent action: MCP tool discovery, health checks and pings. #### Governed actions are not spend Your plan allowance is measured in governed actions per month. It is not a spending limit and it is not a count of model requests. To limit monetary spend, set the workspace **Monthly spend cap**. Agent pages track **Spend this month** against an Agent **Monthly spend cap**, with an **Alert at** warning threshold, so you can identify which workload is contributing to the total. See [Manage spend and usage](https://aethis.io/docs/guides/manage-spend-budgets). See [Plans and governed actions](https://aethis.io/docs/reference/plans) for each plan's allowance. ### Action Records Canonical source: [https://aethis.io/docs/concepts/action-record](https://aethis.io/docs/concepts/action-record) > An Action Record connects one governed action's Agent, tool, policy version, decision, approval and outcome. Records are tamper-evident through HMAC hash-chaining and append-only storage. An **Action Record** is the evidence for one governed action. It connects, in one place: - the **Agent** and its workspace - the **Connection** and the exact tool (capability fingerprint) - the **resource** and a summary of the arguments - the **Policy version** and **matched rule** - the **Policy decision**: Allow, Require Approval or Block - any **approval request**, reviewer, reason and single-use approval - the **execution** result and **outcome**, with duration - identifiers that tie it all together: record ID, correlation ID and action fingerprint Every governed action produces one Action Record, including actions that were blocked or are waiting for approval. [Screenshot: An Action Record in Activity: refund.create by Billing Agent through Finance MCP, policy decision Require Approval, outcome Approval pending.](https://aethis.io/docs/concepts/action-record) #### The three tabs | Tab | Shows | | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Summary** | Agent, Connection, Policy decision, duration, created time, the outcome, resource and fingerprints. | | **Governance** | The Policy version, matched rule, decision and approval request, plus the **Record lifecycle**: each step from request captured to outcome, with timestamps. | | **Integrity** | The record's link status, its **Chain hash**, the previous record in the chain, and its retention. | #### Outcomes The **Outcome** says what happened to the action, separately from the policy decision. It follows the decision's lifecycle: - **Allow**: **Allowed, awaiting execution**, then **Execution in progress**, then **Execution succeeded**. - **Require Approval**: **Approval pending**, then **Approved, awaiting execution**, then **Execution in progress**, then **Execution succeeded**. - **Block**: **Blocked, not executed**. An action that was allowed or approved can also end in **Execution failed** or **Outcome unknown**. If the call may have been dispatched but the response was lost, for example to a timeout, the outcome is **Outcome unknown**. Aethis never reports it as **Execution failed**, because the side effect may have happened. **Execution failed** means it is known that the side effect didn't happen. All outcome labels are in [Statuses](https://aethis.io/docs/reference/statuses#action-outcomes). #### Integrity Action Records are **tamper-evident**. - **Append-only storage.** Records are written once and not edited in place. New facts, such as an approval or an execution result, are added as later lifecycle events. - **HMAC hash-chaining.** Each record's **Chain hash** is computed with HMAC and chains to the previous record. Changing or removing a record breaks the chain at that point, and the break shows up as a non-**Intact** integrity status, such as **Gap**. To check a set of records, use **Verify Chain** in **Activity**. It checks record consistency for the current workspace and filters, or for a selected record, without changing anything. For a repeatable review procedure, see [Verify a governance boundary](https://aethis.io/docs/guides/verify-governance). Each record's integrity status is **Intact**, **Delayed**, **Degraded**, **Gap** or **Unverified**. These describe the record's consistency and integrity state. See [Statuses](https://aethis.io/docs/reference/statuses#action-record-integrity). #### Retention Action Records are kept for your plan's retention period (Developer 30 days, Pro 90 days, Scale 365 days or custom) and removed after it. Deleting an Agent or a Connection doesn't delete its historical records. See [Security and data](https://aethis.io/docs/reference/security-and-data). #### Where to find them Open **Activity** and switch to **Action Records**, or follow **Open Action Record** from an approval request, an evaluated tool, or an Alert. See [Investigate in Activity](https://aethis.io/docs/guides/investigate-activity). ### Investigate in Activity Canonical source: [https://aethis.io/docs/guides/investigate-activity](https://aethis.io/docs/guides/investigate-activity) > Use Activity's Timeline and Action Records views, the Execution Trace, and the Action Record drawer to find out what an Agent did and why. **Activity** holds every governed action in the workspace. Use it to answer "what did this Agent do, what did Aethis decide, and what happened?" #### Two views - **Timeline** tells the story in time order, one line per governed action: "Billing Agent requested approval for refund.create." - **Action Records** is a table of records with the action, Agent and target, decision, duration, integrity and time. [Screenshot: The Action Records view: four records with their decision, duration, integrity status Intact, and time.](https://aethis.io/docs/guides/investigate-activity) #### Narrow it down Select **Filters** to filter by **Outcome**, **Agent**, **Connection**, date range and time window. Select **Clear filters** to reset. Other pages link here already filtered. For example, **View Activity** on an Agent, or **View related activity** on an Alert. Start with the smallest useful scope: one workspace, one Agent or Connection, and the time window around the event. This reduces unrelated records in both the investigation and a later **Verify Chain** check. #### Follow one action end to end 1. In **Timeline**, find the action and select **View Execution Trace**. 2. The trace shows each step in order: the **Request** as captured, the **Agent** that was identified, any correlated **Model** request, the **Governed action** and its decision, the **Policy** and matched rule, any **Approval request**, the **Action Record**, and the **Outcome**. [Screenshot: A Timeline entry with its Execution Trace open: request, agent, model request, governed action, policy, approval request, Action Record and outcome.](https://aethis.io/docs/guides/investigate-activity) 3. Select **Inspect** on the Action Record step (or select a record in **Action Records**) to open the record. Select **Hide Execution Trace** to collapse it. #### Read the Action Record The record opens in a drawer with three tabs. **Summary**: the Agent, Connection, **Policy decision**, duration, created time, the **Outcome** in plain words, the resource, and the fingerprints. **Governance**: the Policy version, **Matched rule**, decision and approval request, and the **Record lifecycle**: request captured, Agent identity resolved, capability fingerprinted, policy evaluated, approval request created, and so on, each with a time. [Screenshot: The Governance tab: Payments Policy v12, matched rule finance-write-approval, decision Require Approval, and the record lifecycle.](https://aethis.io/docs/guides/investigate-activity) **Integrity**: the **Record link status**, the **Chain hash**, the previous record in the chain (**Open Previous Record**), and **Retention**. [Screenshot: The Integrity tab: record link status Intact, the chain hash, the previous record, and retention.](https://aethis.io/docs/guides/investigate-activity) **Copy Record ID** copies the ID for a support ticket or an audit note. When the record is tied to an approval, **Open Approval** takes you to the request. #### Check integrity Action Records are tamper-evident: each record's chain hash is chained to the previous one with HMAC, and records are stored append-only. 1. Select **Verify Chain**. 2. Choose the **Verification Scope**: the current workspace with your current filters, or the selected record only. 3. Select **Run Verification**. Aethis checks record consistency for that scope without changing any record. Anything other than **Intact** needs a look. See [integrity statuses](https://aethis.io/docs/reference/statuses#action-record-integrity) and [Verify a governance boundary](https://aethis.io/docs/guides/verify-governance) for a full review procedure. #### Common questions **Was the action blocked, or did it fail?** Look at the outcome. **Blocked, not executed** means policy stopped it at Aethis and nothing reached upstream. **Execution failed** means Aethis allowed it and it is known that the call didn't take effect. **What does Outcome unknown mean?** The call may have reached upstream, but Aethis didn't get a definite result, for example because of a timeout. It is not a failure: the side effect may have happened. Check the upstream system before you retry. **Was an approved action actually run?** **Approved, awaiting execution** means approved but not yet run. **Execution in progress** means it has been dispatched, and **Execution succeeded** means it ran. **Why can I not find the call?** Confirm the workspace and filters first. Then confirm that the client used the Agent's Aethis endpoint: calls that bypass Aethis do not create Action Records. **What should I save for escalation?** Copy the Record ID and note the workspace, time window, Agent, Connection, outcome and integrity status. Do not paste access keys or full sensitive arguments into a ticket. ### Read the Control Map Canonical source: [https://aethis.io/docs/guides/read-the-control-map](https://aethis.io/docs/guides/read-the-control-map) > The Control Map draws what an Agent can reach, the state of each Connection, and how many policies apply. Use it to check configured access against activity. The **Control Map** is a graph of an Agent's configured access: the Agent, the Connections it can reach, and the policies on each path. Use it to answer "what can this Agent touch, and what governs it?" The map shows configuration, not proof that a call ran. Use it before a rollout to inspect reachability, then use Activity to verify actual governed actions. [Screenshot: The Control Map for Billing Agent: the Agent in the center, linked to a Gateway route marked Governed and two MCP servers marked Frozen, with policy counts on each.](https://aethis.io/docs/guides/read-the-control-map) #### Focus the map Use the controls along the top: - **Agent**: choose which Agent to draw. **View All Agents** shows every Agent in the workspace. - **Authority**: show **All authority**, or only **Approval controls**, **Block controls**, or **Changed / frozen** paths. - **Policy**: show only paths governed by one Policy. - **Search**: find a tool, route or policy by name. #### Read a node Each node to the right of the Agent is a Connection: - its name and type, such as **MCP server · 12 capabilities** or **Gateway route** - its state: **Governed**, or **Frozen** when tool changes are waiting for review - how many policies apply to that path - a badge with the number of tools Select a node to inspect its Connection and policy context. Select **+** on a Connection to expand its tools. #### Move around Drag the canvas to pan. When the canvas has focus, use `Ctrl` or `Cmd` with `+` or `-` to zoom, and `0` to fit. **Fit View**, the zoom buttons and **Reset** do the same. `Tab` moves between nodes and controls. #### Compare configuration with activity The map shows what an Agent **can** do. To see what it **did**, select **View Related Activity**. This opens Activity filtered to the same Agent. A path that is configured but never used may be access the Agent doesn't need. A **Frozen** path means calls through it are paused; see [Review tool changes](https://aethis.io/docs/guides/review-tool-changes). You can also open the map from an Agent (**Open Control Map**) or from an Alert. #### A practical review 1. Choose one production Agent and expand every Connection. 2. Confirm that each Connection belongs to the expected environment and has a named owner. 3. Filter to **Changed / frozen** and resolve every unexpected path. 4. Filter to **Approval controls** and **Block controls** to confirm consequential tools have the intended boundary. 5. Open related Activity and look for configured paths that are unused, or used paths that the map does not explain. If the map and Activity appear to disagree, confirm that both views use the same workspace and Agent. Then check whether the call bypassed Aethis, whether the Connection was attached after the recorded event, or whether a tool definition changed. ### Respond to Alerts Canonical source: [https://aethis.io/docs/guides/respond-to-alerts](https://aethis.io/docs/guides/respond-to-alerts) > Find the alerts that need a response, take ownership, act on the next step, and resolve them. **Alerts** are operational problems that need an owner: a tool definition changed, a policy conflict is blocking rollout, workspace spend is near its enforced cap, or an approval is about to expire. [Screenshot: The Alerts list: five alerts with their affected Agent, severity, status, owner and response deadline.](https://aethis.io/docs/guides/respond-to-alerts) #### Find what needs attention - The tabs show **All alerts**, **Needs response** and **Critical**. - Filter by severity (**Critical**, **High**, **Medium**) and by state (**Open**, **Acknowledged**, **Investigating**, **Resolved**). - The **Response** column shows when an alert escalates if nobody responds. The sidebar badge counts alerts that aren't resolved. #### Work an alert 1. Select the alert. The drawer starts with the **Next step**, for example **Review the tool change**, with a button that takes you there. [Screenshot: A Capability Drift alert: next step Review the tool change, with context, affected path and response actions.](https://aethis.io/docs/guides/respond-to-alerts) 2. Check the **Context**: severity, **Affected scope**, **Owner**, when it was first and last seen, occurrences and escalation. 3. If it's yours, select **Assign to me**. 4. Select **Acknowledge** to show that someone has it, or **Start investigation** while you work on the cause. 5. Follow the **Affected path** (for example Agent, route, Connection, tool). **View related activity** opens Activity, and **Open Control Map** shows the path on the map. 6. Fix the cause, then resolve the alert. > **Note** > Acknowledging an alert doesn't fix anything. A Capability Drift alert, for example, can't be resolved until the tool change has been accepted or rejected, and acknowledging it doesn't resume execution. A resolved alert can be reopened if the problem comes back. **Expected result:** the alert has an owner, its state reflects the work in progress, the underlying control is restored, and the final resolution can be traced through related Activity or configuration. If the fix depends on another team, keep the alert **Investigating** and record the owner rather than resolving it early. #### Alert types | Type | Usually means | Where to act | | ---------------------- | ---------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- | | **Capability Drift** | A tool definition changed after it was accepted. The Connection is paused. | [Review tool changes](https://aethis.io/docs/guides/review-tool-changes) | | **Policy Conflict** | A Policy references something that no longer resolves. | [Fix a conflict](https://aethis.io/docs/guides/create-a-policy#fix-a-conflict) | | **Budget Enforcement** | Workspace spend is at or near the enforced **Monthly spend cap**. Agent usage helps identify contributors. | [Manage spend and usage](https://aethis.io/docs/guides/manage-spend-budgets) | | **Approval Expiry** | An approval request is close to its deadline. | [Review the Approval Queue](https://aethis.io/docs/guides/review-approvals) | | **Provider Health** | An upstream provider or server is degraded or recovered. | The Connection's **Check connection** | | **Evidence Integrity** | An Action Record's integrity check needs attention. | [Check integrity](https://aethis.io/docs/guides/investigate-activity#check-integrity) | Alert states are listed in [Statuses](https://aethis.io/docs/reference/statuses#alerts). ## Administration ### Organizations and workspaces Canonical source: [https://aethis.io/docs/concepts/organizations-and-workspaces](https://aethis.io/docs/concepts/organizations-and-workspaces) > An organization holds members, roles and organization-wide policy. Workspaces separate environments such as Production and Staging, each with its own Agents, Connections and records. #### Organizations An **organization** is your company's account in Aethis. It holds: - **Members** and their **organization roles** - **Roles & Permissions**, including custom roles - **Workspaces** - organization-wide Policies and governance defaults - SSO and security settings You can belong to more than one organization. Switch between them with the organization switcher at the top left of the dashboard. ##### Roles When you invite someone, you choose their **Organization Role** and **Initial Workspace**. The built-in roles are: | Role | Typical use | | ---------------------- | ---------------------------------------------------------------------------- | | **Owner** | The account owner. Has access to all workspaces. | | **Organization Admin** | Manages members, workspaces, credentials and security. | | **Reviewer** | Reviews actions in the Approval Queue for the workspaces they can access. | | **Member** | Works in the workspaces they are given access to. | Use **Create Role** under **Roles & Permissions** to define a narrower role, such as a reviewer for production only. Give people the minimum role they need. #### Workspaces A **workspace** is a separate operating environment inside an organization. Each workspace has an environment type (**Production**, **Staging** or **Development**) and its own: - Agents and their access keys - Connections and Model Routes - Policy assignments - Approval Queue, Activity and Alerts Agents can only be assigned Connections from the same workspace, so a staging Agent can't reach a production MCP server by accident. Keep production and non-production work in separate workspaces. Switch workspaces with the workspace switcher in the top bar. Most of the dashboard shows the current workspace only. #### Organization-wide policy A Policy scoped to the organization can apply across workspaces. An organization can offer it as **Available**, turn it on by default (**Default On**), or make it **Required**, in which case workspaces and Agents can't detach it. See [Policies and decisions](https://aethis.io/docs/concepts/policies#where-a-policy-applies). To manage members and workspaces, see [Manage your organization and workspaces](https://aethis.io/docs/guides/manage-organizations-and-workspaces). ### Manage your organization and workspaces Canonical source: [https://aethis.io/docs/guides/manage-organizations-and-workspaces](https://aethis.io/docs/guides/manage-organizations-and-workspaces) > Invite members with the right role, create custom roles, and use workspaces to separate Production from Staging and Development. Organization settings control who can do what, and in which workspace. For the model, see [Organizations and workspaces](https://aethis.io/docs/concepts/organizations-and-workspaces). Open **Settings**, then choose the **Organization** scope in the settings navigation. #### Before you begin Decide which responsibilities belong at the organization level and which belong inside one workspace. Use separate Production, Staging and Development workspaces when their Agents or Connections should never be interchangeable. #### Members **Members** lists everyone in the organization with their **Organization Role**, **Workspace Access** and when they were last active. [Screenshot: Organization Members: three members with their organization role, workspace access and last active time.](https://aethis.io/docs/guides/manage-organizations-and-workspaces) ##### Invite a member 1. In **Members**, select **Invite Member**. 2. Enter their **Email Address**. 3. Choose the minimum **Organization Role** they need: **Member**, **Reviewer** or **Organization Admin**. 4. Choose their **Initial Workspace**, or **No Workspace**. 5. Select **Send Invitation**. **Expected result:** the member appears with the selected organization role and initial workspace access. For a reviewer, confirm that the Approval Queue for that workspace is visible before relying on them for production coverage. [Screenshot: Invite Organization Member: email address, organization role and initial workspace.](https://aethis.io/docs/guides/manage-organizations-and-workspaces) To add an approval reviewer, invite them as **Reviewer** with access to the workspace whose approvals they'll handle. The **Bring in an approval reviewer** journey on **Get started** walks you through it. ##### Change a role Select **Edit Role** on a member's row. The **Owner** role can't be edited from this list. #### Roles & Permissions **Roles & Permissions** lists built-in and custom roles with their members and key capabilities. Select **Create Role** to define a narrower role, such as a reviewer for production only, and **Edit Role** to change a custom role. #### Workspaces **Workspaces** lists each workspace with its environment, administrator and members, and status. Select **Create Workspace** to add one. Keep production and non-production work in separate workspaces. Agents can only use Connections from their own workspace, so a staging Agent can't reach production tools by accident. After creating a workspace, add its members, set its spend control, and create workspace-specific Connections before registering Agents. If an Agent cannot attach a Connection, compare their workspace IDs first; cross-workspace assignment is intentionally unavailable. #### Switch organization or workspace - The **organization switcher** at the top left lists your organizations. Select **Manage organizations** for more. - The **workspace switcher** in the top bar lists the workspaces in the current organization. Select **Manage workspaces** to open this settings page. #### Workspace settings Open **Settings** with a workspace selected to manage that workspace: its name and environment in **General**, who can access it in **Members & Access**, and its enforced monetary ceiling under **Workspace spend controls**. See [Manage spend and usage](https://aethis.io/docs/guides/manage-spend-budgets). ### Plans and governed actions Canonical source: [https://aethis.io/docs/reference/plans](https://aethis.io/docs/reference/plans) > Each Aethis plan includes a monthly allowance of governed actions and a retention period for Action Records. Every plan includes a monthly allowance of [governed actions](https://aethis.io/docs/concepts/governed-actions) and a retention period for Action Records. | Plan | Governed actions per month | Action Record retention | | --------- | -------------------------: | ----------------------- | | Developer | 10,000 | 30 days | | Pro | 100,000 | 90 days | | Scale | 1,000,000 | 365 days or custom | Retention is enforced per plan: records older than your plan's retention period are removed. Monetary pricing isn't published. [Contact us](https://aethis.io/contact) about plans. #### What counts A governed action counts when Aethis evaluates and records it, whatever the decision. | Scenario | Governed actions | | ------------------------------------------------ | ---------------: | | One model call | 1 | | One tool call | 1 | | One model call followed by 4 governed tool calls | 5 | | An action blocked by policy | 1 | | An action waiting for approval | 1 | | An idempotent retry of the same action | 1 total | | MCP discovery, health checks and pings | 0 | An action evaluated in [Observe Mode](https://aethis.io/docs/concepts/observe-mode) also counts as one. #### Allowance vs spend budget The allowance is a count of governed actions. It is not spend and it is not a count of model requests. A **spend budget** is a separate governance control, in money. Each Agent can show a **Monthly spend cap**, **Spend this month** and an **Alert at** warning threshold for tracking. The workspace **Monthly spend cap** is the enforced ceiling for supported cost-bearing execution. See [Manage spend and usage](https://aethis.io/docs/guides/manage-spend-budgets). ### Security and data Canonical source: [https://aethis.io/docs/reference/security-and-data](https://aethis.io/docs/reference/security-and-data) > Where Aethis processes and stores data, how long Action Records are kept, how record integrity works, and how Agent credentials are handled. #### Where data is processed and stored Aethis processes governed traffic at the Cloudflare edge and stores control-plane and evidence data in Supabase PostgreSQL, with Upstash Redis used for low-latency policy/cache state. Aethis doesn't make a geographic data-residency commitment. #### What is recorded For each governed action, the [Action Record](https://aethis.io/docs/concepts/action-record) holds the Agent, Connection, tool, resource, an arguments summary, the policy version and decision, any approval and reviewer reason, and the outcome. Turn on the Agent's redaction controls (**PII redaction**, **Payment data redaction**, **Secrets redaction**) to mask sensitive values before they leave for a provider or tool. #### Retention Action Records are kept for your plan's retention period and then removed: | Plan | Retention | | --------- | ------------------ | | Developer | 30 days | | Pro | 90 days | | Scale | 365 days or custom | Deleting an Agent or a Connection doesn't delete its existing records; they follow the same retention period. #### Record integrity Action Records are tamper-evident: - **Append-only storage.** Records are written once and not edited in place. - **HMAC hash-chaining.** Each record's **Chain hash** is computed with HMAC and chains to the previous record, so a change or a missing record shows up as a break in the chain. Use **Verify Chain** in **Activity** to check record consistency for a scope. Each record's **Integrity** tab shows its link status. See [Verify a governance boundary](https://aethis.io/docs/guides/verify-governance) for the verification workflow and how to respond to **Delayed**, **Degraded**, **Gap** and **Unverified** results. #### Agent credentials - Each Agent has one Aethis MCP endpoint, `https://mcp.aethis.io/v1/agents/{agent_id}/mcp`, and its own **Aethis access key**: a scoped Agent credential your client sends as `Authorization: Bearer `. - The endpoint URL isn't a secret. The access key is what authenticates the Agent. - The key is shown in full once, when the Agent is created or rotated. Afterwards the dashboard shows only its fingerprint. - **Rotate Key** replaces the key. Rotating, pausing and deleting an Agent each require a typed confirmation. - Keep keys in a secret manager. Never put them in source control, screenshots or support tickets. #### Access control Organization roles (**Owner**, **Organization Admin**, **Reviewer**, **Member** and custom roles) control who can manage Agents, publish policy and review approvals. Workspaces separate environments, and Agents can only use Connections in their own workspace. See [Organizations and workspaces](https://aethis.io/docs/concepts/organizations-and-workspaces). #### Trust Center For Aethis's security program, architecture and disclosure policy, see the [Trust Center](https://aethis.io/security). ## Reference ### Terminology Canonical source: [https://aethis.io/docs/reference/terminology](https://aethis.io/docs/reference/terminology) > The exact labels used in the Aethis dashboard, what each one means, and the retired names they replace. These are the labels you'll see in the dashboard. The docs use them exactly. #### Surfaces | Label | Group | Meaning | | ------------------ | ------- | ------------------------------------------------------------------------------------- | | **Get started** | Control | Guided journeys, starting with **Protect your first Agent**. | | **Overview** | Control | The workspace at a glance, including **Needs attention**. | | **Control Map** | Control | A graph of an Agent's configured access and the policies on each path. | | **Agents** | Govern | Agent identities and their **Overview**, **Connections**, **Policies** and **Tools**. | | **Connections** | Govern | MCP Connections and Model Routes. | | **Approval Queue** | Govern | Actions held for a human decision. | | **Policies** | Govern | Versioned rule sets. | | **Activity** | Observe | Every governed action, as a **Timeline** or as **Action Records**. | | **Alerts** | Observe | Operational problems that need an owner. | | **Support** | Operate | Your support tickets with Aethis. | | **Settings** | Admin | **Personal**, **Workspace** and **Organization** settings. | #### Terms | Term | Meaning | | ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Agent** | The identity a client uses to make governed calls. Has an access key, Connections, Policies and controls. | | **Aethis MCP server URL** | The Agent's one MCP endpoint, `https://mcp.aethis.io/v1/agents/{agent_id}/mcp`, which your agent calls instead of the upstream server. All the Agent's Connections resolve behind it. Not a secret. | | **Client** | How an Agent connects: **MCP-compatible agent** (no SDK required) or **Custom HTTP** (OpenAI chat completions through the model gateway). | | **Aethis access key** | The Agent's scoped credential, sent as `Authorization: Bearer `. Shown once; afterwards only the **Agent key fingerprint** is shown. | | **Connection** | An upstream destination: an **MCP Connection** (remote MCP server) or a **Model Route** (OpenAI). | | **Model Route** | A route for direct model requests through the Aethis Model Gateway. OpenAI only. | | **Execution boundary** | A Connection's shared state: **Governed** (calls can run) or **Frozen** (paused for review). | | **Capability** | A tool, resource or prompt that an MCP server offers. | | **Capability fingerprint** | Identifies one exact tool definition, so changes can be detected. | | **Action fingerprint** | Identifies one exact action: Agent, Connection, tool, resource and arguments. Approvals bind to it. | | **Governed action** | One agent action that Aethis evaluated and recorded. The unit of your plan allowance. | | **Policy** | A named, versioned set of rules. | | **Decision** | **Allow**, **Require Approval** or **Block**. | | **Matched rule / Matched control** | The rule that produced the decision. | | **Approve Once** | Issues a single-use approval for one exact action. Doesn't execute it. | | **Deny** | Refuses the request. Confirmed with **Deny Request**. | | **Action Record** | The tamper-evident evidence for one governed action. | | **Execution Trace** | The step-by-step path of one action in Activity (**View Execution Trace**). | | **Enforcement mode** | A per-Agent setting: **Observe** or **Enforce**. New Agents default to Observe. | | **Observe Mode** | Aethis evaluates policy and records the decision, without blocking, holding or modifying execution. | | **Spend budget** | A limit on spend in money, tracked for an Agent and aggregated at the workspace. | | **Monthly spend cap** | The monthly amount shown for an Agent or workspace. The workspace cap is the documented enforced monetary boundary. | | **Spend this month** | Spend attributed to an Agent in the current month. | | **Alert at** | A percentage of an Agent's spend cap. A warning threshold; it does not stop execution. | | **Tamper-evident evidence** | The Agent control that records a hash-chained decision and policy snapshot. | | **Chain hash** | An Action Record's HMAC chain value, linking it to the previous record. | | **Basic controls** | Agent-level controls: redaction, unknown tool approval and tamper-evident evidence. | | **Refresh tools** | Runs tool discovery on a Connection. | | **Accept catalogue / Reject changes** | The decision on a Connection's pending tool changes. | | **Capability Drift** | The alert type raised when a tool definition changes. | #### Retired names Older material may use these names. They are not used in the product. | Retired | Use instead | | ----------------------------- | -------------------------------------------------------------------------- | | Evidence Trail | **Activity** | | Agent Control Map | **Control Map** | | Policy Book, Policy Books | **Policy**, **Policies** | | Refresh Discovery | **Refresh tools** | | Runs, Trace Mode | **Activity** with **View Execution Trace** | | Flow, Risk and Cost map modes | None. The Control Map has **Agent**, **Authority** and **Policy** filters. | | Redact (as a policy decision) | Redaction is an Agent **Basic control**, not a decision. | | Shadow mode | **Observe Mode** | ### Statuses Canonical source: [https://aethis.io/docs/reference/statuses](https://aethis.io/docs/reference/statuses) > Every status label in the Aethis dashboard, for decisions, approval requests, action outcomes and their lifecycles, evidence integrity, health, coverage, tools, Policies, Agents and alerts. #### Decisions | Decision | Meaning | | -------------------- | ------------------------------------------------------------------ | | **Allow** | Forwarded to the upstream server. | | **Require Approval** | Held in the Approval Queue until a reviewer decides. | | **Block** | Stopped at Aethis. No upstream execution is attempted. | When you use **Evaluate policy**, the preview reads **Allowed**, **Approval required**, **Blocked**, or **Unresolved** when Aethis can't evaluate the action yet. #### Approval requests | State | Meaning | | -------------------------------- | ---------------------------------------------------------------------------- | | **Pending** | Waiting for a reviewer. | | **Escalated** | Waiting, and escalated because the response target passed. | | **Approved, awaiting execution** | Approved once; the Agent hasn't made the matching call yet. | | **Approved and executed** | The matching call used the single-use approval. The Action Record's outcome shows the execution result. | | **Denied** | A reviewer denied it. The action doesn't run through this request. | | **Expired** | Not decided before the deadline. The action doesn't run. | | **Cancelled** | Withdrawn before a decision. | A single-use approval is **Issued**, **Consumed** (used by the matching call), **Expired** or **Revoked**. #### Action outcomes | Outcome | Meaning | | -------------------------------- | --------------------------------------------------------------------------------------------------------- | | **Approval pending** | Held for approval. Execution hasn't been attempted. | | **Approved, awaiting execution** | A reviewer approved it once. The Agent hasn't made the matching call yet. | | **Allowed, awaiting execution** | Policy allowed it. It hasn't been dispatched upstream yet. | | **Execution in progress** | Dispatched to the upstream server. No result yet. | | **Execution succeeded** | The upstream server completed the call. | | **Execution failed** | The call failed, and it is known that the side effect didn't happen. | | **Outcome unknown** | The call may have been dispatched, but the response was lost, for example to a timeout. It may or may not have taken effect. | | **Blocked, not executed** | Policy blocked it at Aethis. Nothing reached upstream. | Each decision follows its own lifecycle: - **Allow**: **Allowed, awaiting execution**, then **Execution in progress**, then **Execution succeeded**. - **Require Approval**: **Approval pending**, then **Approved, awaiting execution**, then **Execution in progress**, then **Execution succeeded**. - **Block**: **Blocked, not executed**. An allowed or approved action can end in **Execution failed** or **Outcome unknown** instead of **Execution succeeded**. > **Outcome unknown is not a failure** > Aethis never reports **Outcome unknown** as **Execution failed**. A timeout or a lost response only becomes **Execution failed** when it is known that the side effect didn't happen. Before you retry an action with an unknown outcome, check the upstream system to see whether it ran. Execution state on its own is **Not attempted**, **Executing**, **Succeeded**, **Failed** or **Outcome unknown**. #### Action Record integrity These statuses describe a record's consistency and integrity state: whether the expected evidence and chain links are present and checked. | Status | Meaning | | -------------- | ------------------------------------------------------------------------------------------------------------------------ | | **Intact** | All expected integrity and link metadata is available, and the checks completed successfully. | | **Delayed** | Some expected evidence or link metadata hasn't arrived yet. There is no confirmed permanent gap; Aethis is waiting for it. | | **Degraded** | The record exists, but the normal level of integrity assurance couldn't be provided for part of it. Assurance is reduced. | | **Gap** | An expected event, link or durable result is confirmed missing. Investigation is required. | | **Unverified** | Integrity verification hasn't completed, or hasn't been run. | See [Action Records](https://aethis.io/docs/concepts/action-record#integrity). #### Tools and Connections **Tool trust state** | State | Meaning | | ----------- | ------------------------------------------------------------------------- | | **Trusted** | The definition matches the one you accepted. | | **New** | Discovered for the first time; not accepted yet. | | **Changed** | The server returned a different definition. Needs review. | | **Removed** | No longer offered by the server. | | **Stale** | The last discovery is out of date. | **Tool access on an Agent**: **Conditional** (policy evaluates each call), **Blocked**, or **Unresolved** (can't be evaluated yet; the reason is shown). **MCP Connection status** | Status | Next step | | -------------------------- | -------------------------------------------------------------------------- | | **Connect account** | Authorize the server's account. | | **Refresh tools** | Run discovery to confirm the catalogue. | | **Review changes** | Tool changes are paused until the catalogue is reviewed. | | **Review tool meaning** | The catalogue is current; some tools' effect or amount format needs review. | | **Unavailable** | Check the connection. | | **Ready** | The catalogue is current and available for policy checks. | **Model Route status**: **Ready**, **Degraded**, **Unavailable**, or **Verify route** (check the route and its workspace allocation). **Execution boundary**: **Governed** or **Frozen**. ##### Health | Health | Meaning | | --------------- | ----------------------------------------------- | | **Healthy** | The last check succeeded. | | **Degraded** | Reachable, with problems. | | **Unavailable** | Not reachable. | | **Unknown** | Not checked yet. | ##### Coverage | Coverage | Meaning | | -------------- | ------------------------------------------------------------------- | | **Governed** | Calls on this path are evaluated by policy. | | **Partial** | Some tools or calls on this path can't be evaluated yet. | | **Uncovered** | No policy evaluation on this path. | | **Changed** | Tool definitions changed and need review. | | **Unverified** | Coverage hasn't been confirmed. | #### Policies | Status | Meaning | | ------------ | -------------------------------------------------------------------- | | **Active** | Published and enforced. | | **Draft** | Not published. | | **Disabled** | Published, not enforced. | | **Archived** | Retired. | | **Conflict** | A reference no longer resolves. Create a draft to fix it. | On an Agent, a Policy can also show **Needs review**. Its assignment is **Direct**, **Inherited** or **Required**. #### Agents | Status | Meaning | | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Active** | Available. Governed paths operate normally. | | **Degraded** | Still operates, but a dependency needs attention: a degraded provider, a partially available Connection, discovery drift, or delayed evidence. | | **Paused** | A temporary stop that a user started. Governed routes stop and the configuration remains. **Resume Route** restores it. | | **Suspended** | A protective stop enforced by Aethis, because of a hard safety boundary, a security condition, an invalid authority state, or a required dependency failure. The triggering condition must be resolved before normal operation resumes. | | **Disabled** | Turned off administratively. The Agent stays registered and configured, but is unavailable until it is explicitly re-enabled. | #### Alerts **Severity**: **Critical**, **High**, **Medium**. | State | Meaning | Next | | ----------------- | ----------------------------------------------- | ----------------------------------------- | | **Open** | Nobody has responded yet. | **Acknowledge** or **Start investigation** | | **Acknowledged** | Someone has it. | **Start investigation**, or resolve | | **Investigating** | Someone is working on the cause. | Resolve | | **Resolved** | Closed. | Reopen if it returns | A Capability Drift alert can't be resolved until its tool change is accepted or rejected.