> 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 <a href="#prerequisites" id="prerequisites"></a>

* [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-<timestamp>.log
```