> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.astropods.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.astropods.com/_mcp/server.

# Policies

A policy is a rule that watches something in your account, such as an agent or a member, and acts when a condition is met. A policy can do things like pause an agent that goes over budget or notify the owner when a deployment fails. Each policy pairs one trigger with the steps that run when it fires.

> **Warning**
>
> Policies are [experimental](/experiments). They are off by default, and the behavior on this page may change.

## Before you start

To complete this guide, you'll need the following:

* An Astropods account at astropods.com. You sign in to the web app to write and manage policies.
* At least one deployed agent. A policy watches agents, so with none deployed there is nothing for a trigger to match.

## Turn the Policies experiment on or off

Policies are an [experimental feature](/experiments) you can turn on or off. When the Policies experiment is on, the **Policies** page and each agent's **Policies** menu item appear in every account you open, including organizations. The feature's on/off state is saved in your browser, so you need to turn the Policies experiment on again if you open Astropods in a different browser.

To turn the Policies experiment on or off, do the following:

1. At astropods.com, click your profile picture at the top right, select **Settings**, then click **Experiments** in the left menu. This menu opens your personal account's settings, where the **Policies** experiment is listed. An organization's **Experiments** page doesn't list it.
2. Turn the **Policies** experiment on or off.

Turning the Policies experiment off hides the page and menu item. It doesn't delete your policies or turn off the ones that are on.

## Create a policy

A policy starts as a description in plain language. Astropods writes the policy from your description and shows it as a flow chart with the trigger at the top and the steps beneath it. You read the policy and edit it before it runs.

To create a policy, do the following:

1. At astropods.com, click **Policies**, then click **New policy**.
2. In the box under **Build a new policy**, describe what you want the policy to do. For example:

   ```text
   Pause any agent that spends more than $1,000 in a billing period,
   and tell the owner which one it was and what it had spent.
   ```

   To start from a ready-made policy, click the lightbulb (**Try example**). To start from a trigger instead, pick one under **or pick a trigger**, set its values in the panel that opens on the right, then continue at step 6.
3. Click **Send** (the arrow) or press Enter. Astropods shows the trigger and steps, and replies in a panel at the bottom of the page.
4. To see the whole policy, click the down arrow beside **Send** to hide the conversation. You can also drag the canvas to move the policy into view.
5. To edit a step, select it and change its values in the panel that appears on the right.
6. To add a step, click the plus at the bottom of the policy or hover between two steps and click the plus sign that appears, then choose a step.
7. To limit the policy, select the trigger and set **Applies to**. An agent trigger offers **Every agent**, **Only these agents**, and **Every agent except these**. A member trigger offers the same choices for members.
8. Click **Save policy**.

Astropods names the policy and replies with a summary of what it built and how it tested it. If your description names no agent, the policy applies to all agents. Use **Applies to** to limit it.

A saved policy is off by default until you turn it on. The account's **Policies** page lists every policy, grouped under **Account-wide** and under each agent's name. See [Turn a policy on or off](#turn-a-policy-on-or-off).

To see each time a policy ran and what it did, open the policy and click **History**.

### Triggers

A trigger is the condition a policy watches. Every policy has one.

| Trigger                                          | Fires when                                                                                              |
| ------------------------------------------------ | ------------------------------------------------------------------------------------------------------- |
| Agent spends over an amount                      | One agent's spend passes your amount in a billing period, calendar month, day, or custom number of days |
| Agent serves a number of requests or fewer       | One agent serves your number of requests or fewer over a window of days                                 |
| Agent deployment                                 | A deployment fails, succeeds, is paused, or is suspended for billing                                    |
| Account spends over an amount                    | The whole account's spend passes your amount in a period                                                |
| Member spends over an amount                     | One member's spend passes your amount in a period (organizations only)                                  |
| A member deploys or pushes to a personal account | A member of your organization works in a personal account (organizations only)                          |

A trigger watches every matching agent or member in the account, and the policy runs once for each match.

### Steps

Steps run in order after the trigger fires.

| Step                      | What it does                                                                                         |
| ------------------------- | ---------------------------------------------------------------------------------------------------- |
| Pause the agent           | Scales the agent that fired the trigger to zero                                                      |
| Pause every running agent | Stops all running agents in the account                                                              |
| Notify                    | Sends a message to the account owner, the account's owners and admins, or the agent's maintainers    |
| Refuse the action         | Blocks the member's deploy or push (only after **A member deploys or pushes to a personal account**) |
| Check, then branch        | Runs different steps depending on the agent's name, the member, or the agent's status                |

A notification takes an optional headline and message. Both accept placeholders such as `{{agent.name}}`, and Astropods writes them for you when you leave them blank. The **Pause every running agent** step shows how many agents it would stop today.

## Test a policy

A test checks what a policy would do without doing it. A test stores nothing and takes no action, so it never pauses an agent or sends a notification. A policy needs a trigger and at least one step before you can test it.

When you create a policy, Astropods tests it and reports the result in its reply. Click **View test results** to see each scenario marked **Fired** or **Did not fire**, with the values it used.

To test a policy yourself, do the following:

1. At astropods.com, click **Policies**, then click the policy.
2. Click **Test run**.
3. Choose how to test:
   * **Auto test your policy** tries a range of scenarios, including values at the boundary, some that should fire the policy and some that should not, and reports what happened.
   * **Set up a manual test** opens **Test scenarios**. Enter the agent's name, status, deployment outcome, spend, last active time, and requests, or click **Load from an agent** to start from one of yours. Click **Run test**, and Astropods highlights the steps the policy would take.

## Turn a policy on or off

A policy acts only while it's on. A saved policy is off by default until you turn it on.

To turn a policy on or off, do the following:

1. At astropods.com, click **Policies**.
2. On the policy's card, use the toggle at the lower right to turn the policy on or off.

## Limits

* Policies act inside one account. A policy never reaches into another account.
* A personal account has one member, so it offers no member triggers.
* A policy fires once per condition. It does not repeat until the condition clears and the period resets.
* A policy reacts to events. It doesn't control who can use an agent. To set that, see [Access control](/access-control).

## Next steps

* [Working with accounts](/accounts): organizations, members, and roles
* [Usage limits](/usage-limits): quotas and limits on your account's usage
* [Usage](/usage): see what your agents and members spend