> 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/open-a-connection.md).

# Let an agent open a connection with an entry

Let an AI agent open RDP, VNC, SSH, or PowerShell sessions with a vault entry through Devolutions CLI, without ever seeing the entry's password.

You ask, your agent connects. The agent runs `devo session connect` with an entry of your vault, and Devolutions CLI reads the entry's host, user, and password and opens the session with its own built-in client. The agent works in the session (runs commands, reads the output, takes screenshots), but it never receives the password.

Credentials leave the vault the same way as when Devolutions Remote Desktop Manager opens a connection. Because the RDP, VNC, SSH, and PowerShell clients are part of Devolutions CLI, the credentials go to that built-in client: they don't need to be exported to another tool, or shown to the agent.

## Before you start

* An RDP, VNC, SSH, or PowerShell Remote Console entry in your vault, with its host, user, and password.
* Devolutions CLI is installed on the computer where the agent runs commands, and you're signed in to the workspace that holds the entry. The agent uses your current context. See [Quick start](https://docs.devolutions.net/cli/quick-start.md).
* An agent that can run shell commands, for example a coding agent working in your terminal.

## Open a session

The agent opens the session with the entry, by name, path, ID, or `devo://` reference. `--vault-name` selects the vault when the entry isn't in the current one.

```bash
devo session connect rdp --entry "<entry-name>" --vault-name "<vault-name>"
devo session connect vnc --entry "<entry-name>"
devo session connect ssh --entry "<entry-name>"
devo session connect pwsh --entry "<entry-name>"
```

The entry's type must match the command: an RDP entry opens `connect rdp`, an SSH Shell entry opens `connect ssh`, and so on. The session is named after the entry, and stays open after the command ends, with a session daemon of its own. When the entry uses a Devolutions Gateway in Devolutions Server or Devolutions Cloud, the session goes through it.

## Work in the session

Every command takes `--session <name>`. Without it, it acts on the only open session that supports it.

<table><thead><tr><th width="260">COMMAND</th><th>WHAT THE AGENT DOES</th></tr></thead><tbody><tr><td><code>devo session list</code></td><td>Lists the sessions, their type, state, and server.</td></tr><tr><td><code>devo session status</code></td><td>Shows the state of a session.</td></tr><tr><td><code>devo session exec &#x3C;command></code></td><td>Runs a command on an SSH or PowerShell session and gets its output.</td></tr><tr><td><code>devo session read</code></td><td>Reads an SSH or PowerShell console without taking control of it.</td></tr><tr><td><code>devo session screenshot</code></td><td>Saves the screen of an RDP or VNC session as a PNG file.</td></tr><tr><td><code>devo session attach</code></td><td>Uses the session live in a terminal. It needs an interactive terminal, so it's for you, to watch or take over what the agent opened.</td></tr><tr><td><code>devo session disconnect</code></td><td>Closes an SSH or PowerShell session and stops its session daemon.</td></tr></tbody></table>

For every option, see [Session commands](https://docs.devolutions.net/cli/reference/commands/sessions.md).

## What the agent sees, and what it doesn't

<table><thead><tr><th width="200">THE AGENT</th><th>WHAT</th></tr></thead><tbody><tr><td><strong>Sees</strong></td><td>The output of the commands it runs, the text of the consoles it reads, and the screenshots it takes. The host and the user name of the entry. Anything the remote computer shows: if a password is on the screen or in a file it reads, the agent sees it.</td></tr><tr><td><strong>Never sees</strong></td><td>The entry's password. Devolutions CLI reads it from the vault and gives it to the session daemon, never to the output of the command.</td></tr></tbody></table>

## Tell the agent what it may run

The agent has a shell, so it could also run the commands that return a secret value. Add rules like these to its instructions, for example in `AGENTS.md` or `CLAUDE.md`:

```markdown
## Remote connections

- To connect to a server, run `devo session connect <rdp|vnc|ssh|pwsh> --entry "<entry>"`,
  then use `devo session` commands (`list`, `status`, `exec`, `read`, `screenshot`, `disconnect`).
- You may run any `devo session` command.
- Never run `devo secret read`, `devo secret get`, `devo secret inject`, or `devo secret shell`.
- Never add `--no-masking` to a command.
```

If your agent supports command permissions, allow `devo session *` and block `devo secret read`, `devo secret get`, `devo secret inject`, `devo secret shell`, and `--no-masking` there too.

## Require your approval before a connection

The operation policy can hold an operation until you approve it. `devo session connect --entry` reads the entry through the operation `rdm.entries.get`, so a rule that sets it to `ask` makes every connection with an entry wait for you:

```json
{
  "schemaVersion": 1,
  "approvalTimeoutSeconds": 900,
  "rules": [
    { "operation": "rdm.entries.get", "decision": "ask" }
  ]
}
```

1. Save the policy in a file, then load it from an interactive terminal: `devo policy set --file <path> --yes`.
2. When the agent connects, the command waits and prints the ID of the approval request.
3. Check it with `devo approve list` or `devo approve show <approval-id>`, then accept it with `devo approve accept <approval-id> --yes`, or deny it with `devo approve deny <approval-id> --yes`. Without a decision, the request expires after 900 seconds.

{% hint style="warning" %}
The rule holds every read of an entry, not only connections: `devo entry get`, `devo entry references`, `devo ref resolve`, and the MCP tools that get an entry wait for your approval too. To hold fewer reads, add a `vaultId` or an `entryId` to the rule.
{% endhint %}

See [Approvals and operation policy](https://docs.devolutions.net/cli/reference/commands.md#approvals-and-operation-policy).

## Limits

* **An agent that has your shell has your access.** Devolutions CLI runs as you, so the agent can run any `devo` command you can, including the ones that return a secret value. The instructions and command permissions above are what keep it to `devo session`. See [What stays hidden, and what doesn't](https://docs.devolutions.net/cli/guides/understand/security-model.md).
* **Some entries can't be opened with `--entry`.** `--entry` doesn't check out a privileged account, and doesn't send a comment or a ticket number. When an entry needs one of these, the workspace doesn't give out its password, and the connection fails for lack of a password, unless a `*_PASSWORD` environment variable gives one.
* **What happens in the session is real.** Commands the agent runs change the remote computer, and cancelling a command doesn't undo what already ran.

## Next

* [Session commands](https://docs.devolutions.net/cli/reference/commands/sessions.md)
* [Give an agent a credential without exposing it](https://docs.devolutions.net/cli/guides/ai-agents/run-an-agent.md)
* [What stays hidden, and what doesn't](https://docs.devolutions.net/cli/guides/understand/security-model.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/open-a-connection.md?ask=<question>&goal=<user_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.
