> For the complete documentation index, see [llms.txt](https://docs.devolutions.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.devolutions.net/cli/guides/ai-agents/run-an-agent.md). # Give an agent a credential without exposing it Let an AI agent use a credential from your vault through devo secret run, so the value never appears in its conversation or transcript. An agent that reads a password puts it in its context: the value can end up in the transcript, in logs, or in a later answer. With Devolutions CLI, the agent never needs the value. It works with `devo://` references, which say where a secret is and open nothing on their own, and it starts its tools through `devo secret run`, which hands the values to that tool only. ## Before you start * Devolutions CLI is installed on the computer where the agent runs commands, and you're signed in. The agent uses your current context. See [Quick start](/cli/quick-start.md). * The agent can run shell commands, for example a coding agent working in your terminal. ## How it works 1. The agent asks Devolutions CLI for the references of an entry. The answer contains no secret value. 2. The agent writes a command that maps each reference to an environment variable, and runs it through `devo secret run`. 3. Devolutions CLI reads the values from your vault, starts the tool with those variables, and replaces every resolved value with `` in what the tool prints. The agent sees the tool's output, never the secret. ## Let the agent find references Two commands list the references of an entry without returning any value. They return the same data, so use whichever reads better in your instructions. Only the `command` value of the JSON envelope differs: `secret.catalog.entry` or `entry.references`. ```bash devo secret catalog entry "" --vault-name "" --json devo entry references "" --vault-name "" --json ``` With `--json`, each item in `data.references` has a `field` (such as `password`) and a `reference` to copy. See [Find the reference to a secret](/cli/guides/secrets/find-a-reference.md). {% hint style="info" %} You can also find the references yourself and put them in the agent's instructions or in a `.env` file. References are safe to share: they contain names or IDs, not values. {% endhint %} ## Let the agent launch tools The agent passes each reference with `--env-ref NAME=`. Everything after `--` is the tool to run: ```bash devo secret run --env-ref DB_PASSWORD= -- ``` A few things the agent needs to know, because Devolutions CLI enforces them: * **References go in `--env-ref`, never in the command's arguments.** Devolutions CLI refuses a reference written after `--` with the error `secretLaunchArgumentReference`. * **For several secrets, repeat `--env-ref`**, or use `--env-file` with a `.env` file that holds references. See [Take the passwords out of a .env file](/cli/guides/secrets/replace-env-files.md). * **To test without reading any secret,** add `--check`. Devolutions CLI checks that the command exists and that every reference is well formed, without resolving a value or starting the tool. It doesn't prove each field can be read. * **To stop a tool that hangs,** add `--timeout-seconds `. ## Write the agent's instructions Put rules like these in the agent's instruction file (for example the project's agent instructions or `CLAUDE.md`), and adapt the names to your project: ```markdown ## Credentials - Never read, print, or store a secret value. Never run `devo secret read`, `devo secret get`, `devo secret inject` or `devo secret shell`. - To find a credential, run `devo secret catalog entry "" --vault-name "" --json` and use the `reference` of the field you need. - To run a command that needs a credential, run: `devo secret run --env-ref NAME= -- ` and have the command read the value from the NAME environment variable. - Never put a `devo://` reference in the command's arguments. - Before a long or risky run, check it with `devo secret run --check ...`. ``` ## Why not `devo secret read`? `devo secret read` and `devo secret get` print the value. Whatever an agent prints ends up in its context, so the secret becomes part of the conversation. `devo secret inject` also hands over the value: it writes the filled text to standard output, or to a file with `--out-file`. On standard output, the value lands directly in the agent's context; in a file, the agent can open it. `devo secret shell enter` puts the value in the agent's shell. `devo secret run` is the only command that gives the value to a program without showing it to whoever started it. {% hint style="warning" %} Instructions are guidance, not a lock. An agent that can run shell commands as you can also run `devo secret read`, because it has the same access to your vault as you do. To enforce the rule, use your agent's own command permissions: allow `devo secret run`, and block `devo secret read`, `devo secret get`, `devo secret inject`, and `devo secret shell`. {% endhint %} {% hint style="warning" %} Masking protects what the tool prints, not what it does. A tool that receives a secret can still write it to a file, send it over the network, or print it in a different form, for example encoded. Masking can be turned off with `--no-masking`, so keep that option out of your agent's allowed commands. See [What stays hidden, and what doesn't](/cli/guides/understand/security-model.md). {% endhint %} ## Good to know * `devo secret run` returns the exit code of the tool it started, so the agent can tell whether its command succeeded. * A reference that doesn't resolve stops the launch before the tool starts. See [A secret reference doesn't resolve](/cli/help/troubleshooting/reference-does-not-resolve.md). * If the agent works on another workspace than your current one, it can add `--context ` to any `devo` command. See [Switch between workspaces](/cli/guides/connect/switch-workspaces.md). ## Next * [Run a command with its secrets](/cli/guides/secrets/run-with-secrets.md) * [Connect an AI client with MCP](/cli/guides/ai-agents/connect-mcp.md) * [Limit what an agent can do](/cli/guides/ai-agents/limit-tools.md) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.devolutions.net/cli/guides/ai-agents/run-an-agent.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.