> For the complete documentation index, see [llms.txt](https://docs.enclaive.cloud/virtual-hsm/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.enclaive.cloud/virtual-hsm/cli/server-and-infrastructure-management/vhsm-agent.md).

# vhsm agent

The `vhsm agent` command starts a **vHSM Agent** that performs automatic authentication in environments where persistent and seamless authentication is required. This is useful for managing token lifecycle, writing tokens to sinks, and acting as an identity broker in specific deployment scenarios.

#### **Usage**

```bash
vhsm agent [options]
```

This command starts the agent using a specified configuration file and optional flags.

**Example**

Start a vHSM agent using a configuration file:

```bash
vhsm agent -config=/etc/vhsm/config.json
```

**HTTP Options**

| Option                      | Description                                                                                                 |
| --------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `-address=<string>`         | Address of the vHSM server (default: `https://127.0.0.1:8200`). Can be set using `VAULT_ADDR`.              |
| `-agent-address=<string>`   | Address of the agent. Can be set using `VAULT_AGENT_ADDR`.                                                  |
| `-ca-cert=<string>`         | Path to a PEM-encoded CA certificate (overrides `-ca-path`). Set via `VAULT_CACERT`.                        |
| `-ca-path=<string>`         | Path to a directory of PEM-encoded CA certificates. Set via `VAULT_CAPATH`.                                 |
| `-client-cert=<string>`     | Path to a PEM-encoded client certificate for TLS auth. Requires `-client-key`. Set via `VAULT_CLIENT_CERT`. |
| `-client-key=<string>`      | Path to the PEM-encoded private key matching the client cert. Set via `VAULT_CLIENT_KEY`.                   |
| `-disable-redirects`        | Prevents automatic HTTP redirect following (default: false). Set via `VAULT_DISABLE_REDIRECTS`.             |
| `-header=<key=value>`       | Adds custom HTTP headers (cannot start with `X-Vault-`). Repeatable.                                        |
| `-mfa=<string>`             | Supply MFA credentials for `X-Vault-MFA`. Set via `VAULT_MFA`.                                              |
| `-namespace=<string>`       | Set namespace for the command. Shortcut: `-ns`. Set via `VAULT_NAMESPACE`.                                  |
| `-non-interactive`          | Disables interactive prompts (default: false).                                                              |
| `-output-curl-string`       | Outputs equivalent cURL command instead of executing (default: false).                                      |
| `-output-policy`            | Outputs example HCL policy instead of executing (default: false).                                           |
| `-policy-override`          | Override Sentinel policy with soft-mandatory enforcement (default: false).                                  |
| `-tls-server-name=<string>` | Set TLS SNI host name. Set via `VAULT_TLS_SERVER_NAME`.                                                     |
| `-tls-skip-verify`          | Skip TLS certificate verification (not recommended). Set via `VAULT_SKIP_VERIFY`.                           |
| `-unlock-key=<string>`      | Key to unlock a namespace API lock.                                                                         |
| `-wrap-ttl=<duration>`      | Wrap response with a cubbyhole token (e.g., `30s`, `5m`). Set via `VAULT_WRAP_TTL`.                         |

#### **Command Options**

| Option                          | Description                                                                                  |
| ------------------------------- | -------------------------------------------------------------------------------------------- |
| `-config=<string>`              | Path to the agent configuration file. This file should contain agent directives only.        |
| `-exit-after-auth`              | Agent exits with code 0 after one successful authentication and sink write (default: false). |
| `-log-file=<string>`            | File path to write agent logs.                                                               |
| `-log-format=<string>`          | Log format: `standard` or `json`. Set via `VAULT_LOG_FORMAT`.                                |
| `-log-level=<string>`           | Log verbosity: `trace`, `debug`, `info`, `warn`, or `error`. Set via `VAULT_LOG_LEVEL`.      |
| `-log-rotate-bytes=<int>`       | Maximum size in bytes before log rotation.                                                   |
| `-log-rotate-duration=<string>` | Max duration before log rotation (e.g., `30s`, `1h`).                                        |
| `-log-rotate-max-files=<int>`   | Max number of rotated log files to retain.                                                   |

#### **Subcommands**

| Subcommand        | Description                                            |
| ----------------- | ------------------------------------------------------ |
| `generate-config` | Generate a base configuration file for the vHSM agent. |

***


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.enclaive.cloud/virtual-hsm/cli/server-and-infrastructure-management/vhsm-agent.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.