# The Ployz agent

> Ask the agent in the dashboard about your app, have it deploy for you, and approve what it would remove.

The Ployz agent lives on the right edge of every organization page. Ask it about your projects
and deployments, or ask it to change something and deploy. Before a deploy removes
anything, it stops and asks you.

The agent works in the project and environment you're looking at, unless you name another. It
can create a project, add and change services, [configs](https://ployz.dev/docs/services/configs), volumes and
domains, review what's staged, publish and deploy. It can also read your GitHub repositories and
work on your servers. It doesn't create environments, and it can't read a service's logs yet.

## What it can do on your servers

The agent asks your servers and Cloud directly, so its answers are as fresh as the servers that
replied. It can:

- Show a server, a service's containers, and where each volume's copies live
  (**server show**, **service status**, **volume show**).
- Restart, start or stop a service (**service restart**, **service start**, **service stop**).
- Drain, upgrade, clean up after or remove a server (**server drain**, **server upgrade**,
  **server clean**, **server remove**).
- Mirror a volume to another server, refresh that mirror, move a volume, release it, or remove a
  mirror (**volume mirror**, **volume move**, **volume release**, **volume mirror remove**). To
  refresh a mirror, ask for a **volume mirror** to the same server again.
- Read a connected GitHub repository, or tell you how to connect one (**github ls**,
  **github connect**).

## Talk to the agent

1. Click the tab on the right edge of the page.
2. Type in **Ask about your servers…** and press Enter. Shift+Enter starts a new line.
3. To start over, click **New chat** at the top of the panel.

<!-- screenshot: the agent panel open over the canvas of my-app production, with a short conversation -->

The panel's header names your organization and, on an environment's pages, the environment
(like `production`). Your conversation is kept for this organization, so it's still there
after you reload or come back later. Closing the panel keeps the conversation.

Each thing the agent runs shows as a short line under its reply, named for what it does, like
**environment show**. When it deploys or publishes, that line becomes a card with the
deployment's status, like **Deploying** and then **Deployed**, and a link to the deployment once it exists.
When it starts a run on a server or volume, like a restart or a mirror, the card shows the run's
name and its state when Cloud took it, like **Queued · restart web**. Ask the agent how the run
went to see where it got to.
A restart goes one server at a time and starts each container again, even when stopping it
failed. A container counts as back once it passes its healthcheck, like a deploy waits for, and
serves traffic. If a server's containers don't come
back, the restart stops there and leaves the other servers alone. Stopping or restarting a
service also stops its pre-deploy hook containers, and no restart or start runs them again.

## Approve or deny a removal

When a deploy or publish would remove a running service, delete a volume, detach a volume from a
service or remove a domain, the agent stops and shows a card. It does the same before it removes
a server, cleans up after one, drains the last copy of a volume off one, or runs a volume
command that deletes data. The card leads with what would be
destroyed. Everything else the change does is folded under a count, like **2 other changes**;
click it to see them.

1. Read the list of what gets destroyed.
2. Click **Approve** (or press ⌘↵) to let the deploy go ahead.
3. Or click **Deny** (or press Esc) to stop it. To tell the agent why, click
   **Deny with a reason…**, type the reason, and press ⌘↵.

<!-- screenshot: an approval card for Deploy production that deletes the postgres-data volume -->

The agent picks up your answer and carries on. If you denied it, the agent gets your reason.

While approvals are waiting, the tab on the right edge shows how many. An approval you didn't
start from this chat, like one a coding agent opened from the CLI, appears at the top of the
panel under **Waiting on you**, and you answer it the same way. That includes
`ployz server rm`, `ployz server drain` and `ployz server clean`, whose cards are named for the
server, like **Remove fra-1**.

## Good to know

- **Needs an Anthropic API key.** On a [Self-hosted Cloud](https://ployz.dev/docs/self-hosting) without
  `ANTHROPIC_API_KEY`, the agent answers every message by saying it isn't set up yet.
- **Approving never deletes data on its own.** When a deploy or publish would delete a volume's
  data, the agent stops and tells you which volumes. It goes ahead only if you ask it to, like
  "publish, accepting the volume loss", and only in the same project and environment.
- **Only removals ask.** Deploys that roll out a new image, change variables or scale a service
  go ahead without a card. Under such a deploy you'll see **Didn't ask. Nothing destroyed.**
  Restarting, starting or stopping a service never asks, and neither does upgrading a server.
- **One at a time.** The agent runs at most one command that might ask per reply, so you never
  get two cards for one message.
- **You approve one plan.** If the change moves on before you answer, the card says the plan
  changed, and the agent asks again about the new one.
- **Asking is always on.** No setting turns it off. See
  [Destructive actions ask first](https://ployz.dev/docs/account/organizations#destructive-actions-ask-first).
- **Answer anywhere.** An approval is the same in every tab and on every device. Answer it once
  and every other card for it updates. If you answer a card someone already answered, it says the
  approval was already decided elsewhere, and how.
- **Keep backups.** An approved deploy that deletes a volume deletes its data. Keep
  [backups](https://ployz.dev/docs/services/databases#back-up-a-database) of data you can't lose.