> 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/tutorials/vhsm-agent-quickstart.md).
# vHSM Agent quickstart
vHSM Agent acts as a client-side daemon that handles authentication and communication with vHSM on behalf of client applications. It simplifies authentication by obtaining and managing client tokens, eliminating the need for applications or users to manually renew or re-authenticate as tokens expire.
Additionally, vHSM Agent supports [Consul Template markup](https://github.com/hashicorp/consul-template/blob/main/docs/templating-language.md), allowing it to render secrets into files. This enables client applications to seamlessly access and load the required data.
By the end of this tutorial, you'll learn how to seamlessly manage secrets using vHSM without modifying your client application’s code. The client application loads data from the `customer.json` file, while vHSM Agent's Template feature dynamically injects secrets into the file. This approach ensures secure and automated secret management without requiring direct integration with vHSM.
#### Prerequisites
* [Install vHSM CLI](/virtual-hsm/documentation/setup.md)
* [Install vHSM and start a Dev server](/virtual-hsm/documentation/setup/installation.md)
1\. Create a directory for storing test files and configuration.
```bash
mkdir -p $HOME/vhsm-test && cd $HOME/vhsm-test
```
2\. Create a mock dataset `data.json` representing a customer record, using an editor of your choice:
```bash
{
"organization": "Enclaive",
"customer_id": "ABXX2398YZPIE7391",
"region": "US-West",
"zip_code": "94105",
"type": "premium",
"contact_email": "alice@enclaive.com",
"status": "active"
}
```
3. Upload the test data to the vHSM KV v2 secrets engine:
```bash
vhsm kv put secret/customers/enclaive @data.json
```
4\. Create the agent configuration file `agent-config.json` to enable automatic authentication and token management.
```bash
pid_file = "./pidfile"
vault {
address = "$VAULT_ADDR"
tls_skip_verify = true
}
auto_auth {
method {
type = "token_file"
config = {
token_file_path = "$HOME/.vault-token"
}
}
sink "file" {
config = {
path = "$HOME/vault-token-via-agent"
}
}
}
```
> **Note:** For production, consider robust auth methods such as AppRole, Kubernetes Auth, and others.
5. Start the vHSM Agent:
```bash
vhsm agent -config=agent-config.json
```
Expected log output will confirm:
* Token sink created
* Auth handler started and authenticated
```
==> vHSM Agent started! Log data will stream in below:
==> vHSM Agent configuration:
Api Address 1: http://bufconn
Cgo: disabled
Log Level:
Version: Vhsm v1.3.2-0 heads/main-0-g1b8bb7c 2024-10-10T01:15:29+00:00
2025-03-08T17:00:28.700Z [INFO] agent.sink.file: creating file sink
2025-03-08T17:00:28.700Z [INFO] agent.sink.file: file sink configured: path=/tmp/secrets/vault-token mode=-rw-r-----
2025-03-08T17:00:28.701Z [INFO] agent.exec.server: starting exec server
2025-03-08T17:00:28.701Z [INFO] agent.exec.server: no env templates or exec config, exiting
2025-03-08T17:00:28.701Z [INFO] agent.auth.handler: starting auth handler
2025-03-08T17:00:28.701Z [INFO] agent.auth.handler: authenticating
2025-03-08T17:00:28.701Z [INFO] agent.sink.server: starting sink server
2025-03-08T17:00:28.701Z [INFO] agent.template.server: starting template server
```
6\. Stop the running vHSM Agent (`Ctrl + C)`
7\. Use the template rendering feature of vHSM Agent to dynamically fetch and inject secrets into application configuration files and create a template file, `customer.json.tmpl`:
```bash
{
{{ with secret "secret/data/customers/acme" }}
"Organization": "{{ .Data.data.organization }}",
"ID": "{{ .Data.data.customer_id }}",
"Contact": "{{ .Data.data.contact_email }}"
{{ end }}
}
```
8. Create an additional config `agent-template.json`for templates:
```bash
template {
source = "$HOME/vhsm-test/customer.json.tmpl"
destination = "$HOME/vhsm-test/customer.json"
}
```
9. Restart vHSM Agent with both configs:
```bash
vhsm agent -config=agent-config.json -config=agent-template.json
```
You should see a rendered file at `$HOME/vhsm-test/customer.json`.
10. Verify rendered output:
```bash
cat customer.json
```
Output is similar to:
```json
{
"Organization": "Enclaive",
"ID": "ABXX2398YZPIE7391",
"Contact": "alice@enclaive.com"
}
```
11\. Enable logging using the `-log-file` flag:
```bash
vhsm agent -config=agent-config.json \
-log-file=$HOME/vhsm-test/vhsm-agent.log
```
vHSM appends a timestamp to the log file.
12. Check the log file:
```bash
ls | grep .log
cat vhsm-agent-.log
```
---
# 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/tutorials/vhsm-agent-quickstart.md?ask=&goal=
```
`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.