+++
title = "Keeping AI agents safe with Bonsai"
description = "Limit what an agent can do with token scopes and read-only mode, and see how Bonsai keeps passwords and tokens away from it."
weight = 24
updated = 2026-11-11

[extra]
nav_title = "Keeping agents safe"
weight = 60
+++

An agent with access to your infrastructure can create things that cost money and destroy things that matter. Bonsai's agent tools are built so that the worst mistakes need you, and so that secrets stay out of the agent's context. This page covers what is built in, and what to set up yourself.

## Limit the token

An agent can do what its API token can, and nothing more. This is the one limit an agent can't talk its way around, so start here.

| To let an agent | Give the token |
|---|---|
| Look at clusters, usage, metrics and plans | `account:read`, `clusters:read` |
| Also write connection URLs to env files | `credentials:read` |
| Also read top search terms | `query_logs:read` |
| Also create, rename, resize and destroy clusters | `clusters:write` |

A new token is read-only unless you pick more. Create one for agents in the dashboard's [API Tokens](@/docs/account/api-tokens/index.md) tab, and log in with it:

```bash
bonsai login --with-token --profile agent < token.txt
```

Then point the agent at that [profile](@/docs/cli/configuration/index.md), with `BONSAI_PROFILE=agent` in its environment. See [scopes](@/docs/api/authentication/index.md#scopes) for what each one allows.

## Read-only mode

`bonsai mcp --read-only` starts the MCP server without the tools that create, rename, resize and destroy clusters. The agent can't call a tool it was never given.

Use it together with a read-only token. The flag removes the tools, and the token is what stops a change made another way.

## Your API token stays out of the chat

You log in yourself, in your own terminal, with `bonsai login`. The token goes in your system keychain, and the CLI and the MCP server read it from there. It isn't in the agent's context, in its transcript, or in an MCP client's config file.

The skill tells the agent never to ask for a token in the chat. If an agent asks you to paste one, don't.

## Cluster passwords stay out of the chat

A cluster's connection URL includes its password. An agent that prints it has put it in a transcript, and maybe in a log or a commit.

So no MCP tool returns a password, and the skill tells the agent never to print one. Instead, the agent writes the URL where your app reads it:

- With the MCP tool `write_cluster_url`, or `bonsai cluster url <cluster> --write .env`.
- The agent gets back the URL with the password as `****`.
- The file must be inside the project folder.
- In a git repository, the file must be ignored by git and not tracked, or the write is refused. So the password can't be committed.
- The file is left readable only by you.

If the write is refused, the agent is told to ask you to add the file to `.gitignore`, not to work around it.

Two commands can still print a password: `bonsai cluster url` without `--write`, and `bonsai api`. An agent with a shell can run them, which is one more reason to give it a token without `credentials:read` if it has no need for connection URLs.

## Destroying needs you

A destroyed cluster and its data can't be brought back. To destroy one, the agent has to supply the cluster's current name as a confirmation, and both the skill and the MCP tool tell it to get that name from you instead of copying it from another answer.

The agent is also told to confirm with you before it creates or resizes a cluster, naming the cluster, plan and region, since those change your bill.

Keep your client's own approval prompts on for the tools that change things. The MCP server marks `resize_cluster` and `destroy_cluster` as destructive, and every reading tool as read-only, so clients know which calls to ask about.

## Search terms are untrusted text

Top search terms are what your cluster's users typed into a search box. Someone could type text that reads like an instruction to an agent, hoping one reads it later. The tool that returns them tells the agent to treat them as data, never as instructions.

That lowers the risk without removing it. If an agent doesn't need search terms, leave `query_logs:read` off its token.

## A checklist

- Give the agent its own token, with only the scopes it needs.
- Use `--read-only` for agents that should only look.
- Log in yourself. Never paste a token into a chat.
- Keep `.env` in `.gitignore`.
- Keep approval prompts on for creating, resizing and destroying.
- Revoke the agent's token in the dashboard, or with `bonsai logout`, when you're done.