HashiCorp Vault

Connect your HashiCorp Vault cluster to let CloudThinker agents check seal status and health, list what a secret path holds, audit policies, auth methods, and audit devices, and issue short-lived database or cloud credentials through your Approvals. Agents run the official vault CLI in the CloudThinker managed sandbox and sign in with a token or an AppRole (a role ID plus a secret ID that Vault exchanges for a short-lived token).

Prerequisites

A Vault address CloudThinker can reach over the network, such as a public DNS name or an HCP Vault Dedicated endpoint. localhost and private addresses resolve where CloudThinker runs the command, not on your network. For a Vault behind a firewall, see Reaching private services.
Permission to write a policy and create a token or an AppRole.
The Admin role in the CloudThinker workspace, which you need to add connections. See Roles.
For Vault Enterprise or HCP Vault Dedicated: the namespace your secrets live in. HCP uses admin by default.

A workspace holds one Vault connection. What agents can reach is exactly what the policy on your token or AppRole allows. Vault denies everything else by default.

Choose an auth method

Method	Use it when	Trade-off
AppRole	Production clusters	Rotate the secret ID without reissuing a token. Each session logs in and gets a fresh short-lived token
Token	Trials and dev clusters	Quickest to set up. The token lives until its TTL runs out, so you replace it on that schedule

Setup

Write a least-privilege policy

Start with read and list on the paths agents should see. Replace secret with your KV mount name and narrow the paths to what you need. This example assumes a KV v2 mount:

vault policy write cloudthinker-read - <<EOF
path "secret/data/*" {
  capabilities = ["read"]
}
path "secret/metadata/*" {
  capabilities = ["read", "list"]
}
path "sys/mounts" {
  capabilities = ["read"]
}
path "sys/auth" {
  capabilities = ["read"]
}
EOF

read on secret/data/* lets the token read secret values. CloudThinker shows only key names unless you ask for a value, but that’s CloudThinker’s behavior, not a Vault limit. To have Vault enforce it, drop the secret/data/* block: agents can still list paths and read metadata, but can’t list the keys inside a secret.For a KV v1 mount, replace the two secret/ blocks with one: path "secret/*" { capabilities = ["read", "list"] }.See Required permissions to add policy audits or dynamic credentials.

Create the credential

AppRole
Token

Enable AppRole (skip if it’s already on), bind a role to the policy, then fetch the role ID and a secret ID:

vault auth enable approle

vault write auth/approle/role/cloudthinker \
  token_policies=cloudthinker-read \
  token_ttl=1h \
  token_max_ttl=4h \
  secret_id_ttl=720h

vault read auth/approle/role/cloudthinker/role-id
vault write -f auth/approle/role/cloudthinker/secret-id

Copy the role_id and the secret_id from the output.

Create a token bound to the policy:

vault token create \
  -policy=cloudthinker-read \
  -ttl=720h \
  -display-name=cloudthinker

Copy the token value from the output.

Both examples expire after 30 days (720h): the AppRole secret ID or the token stops working and the connection fails. Set a reminder, then issue a new one and update the connection as described in Security.

Add the connection in CloudThinker

In the sidebar, click More → Workspace settings → Connections and select HashiCorp Vault. Enter VAULT_ADDR, set VAULT_NAMESPACE if you use Enterprise or HCP, pick AppRole or Token in VAULT_AUTH_METHOD, and fill in the credential fields that appear. Click Connect.Success state: the connection shows Connecting and Verifying, then Connected. For a token, CloudThinker runs vault token lookup. For AppRole, it logs in through auth/approle/login and checks that Vault returns a token.

Connection details

Field	Required	Description	Example
VAULT_ADDR	Yes	Full Vault URL, including scheme and port	`https://vault.example.com:8200`
VAULT_NAMESPACE	No	Enterprise or HCP namespace. Leave blank for open-source Vault	`admin`
VAULT_AUTH_METHOD	Yes	Token (default) or AppRole	AppRole
VAULT_TOKEN	Token only	The token from `vault token create`
VAULT_ROLE_ID	AppRole only	The AppRole `role_id`
VAULT_SECRET_ID	AppRole only	The AppRole `secret_id`

Required permissions

Grant only the rows you need. Each row adds paths to the policy from setup.

You want agents to	Add to the policy
List keys and read metadata on KV v2 secrets	`read` on `<mount>/data/`, `read` and `list` on `<mount>/metadata/`
List secret engines and auth methods	`read` on `sys/mounts` and `sys/auth`
Audit policies	`read` and `list` on `sys/policies/acl` and `sys/policies/acl/*`
List AppRole roles	`list` on `auth/approle/role`
List audit devices	`read` and `sudo` on `sys/audit`
Issue dynamic credentials	`read` on `<engine>/creds/<role>`, such as `database/creds/readonly`
Revoke or renew leases	`update` on `sys/leases/revoke` and `sys/leases/renew`
Write or delete KV v2 secrets	See the example below

For KV v2 writes under secret/myapp/, add:

path "secret/data/myapp/*" {
  capabilities = ["create", "update", "delete"]
}
path "secret/destroy/myapp/*" {
  capabilities = ["update"]
}

The health check (sys/health) and vault token lookup on the caller’s own token work under Vault’s built-in default policy, so you don’t need to add them.

Start read-only. Add the write rows only when you have a workflow that needs them. Even then, every write goes through your Approvals first. Choose Manual so a person approves every change. Once CloudThinker turns on Rule enforcement for your workspace, an Ask first Rule can narrow that to the Vault connection alone.

Agent capabilities

Capability	What agents can do	Approval
Health	Check seal status, version, mounted secret engines, and auth methods	No
Secret discovery	List paths and the keys a secret holds, and tell KV v1 from KV v2	No
Policy audit	Read the current token’s policies and TTL, list and read policies, list audit devices and AppRole roles	No
Dynamic credentials	Issue short-lived database or cloud credentials from a secrets engine	Yes
Lease management	Revoke or renew a credential lease	Yes
Secret and config changes	Write, delete, or destroy KV versions, write policies, enable or disable mounts, auth methods, and audit devices	Yes

Agents report keys and metadata, not secret values, unless you ask for a value, and never print your token or secret ID. Issuing a dynamic credential looks like a read in Vault, but it creates a lease, so CloudThinker treats it as a write. Writes go through Approvals before they run.

Verify the connection

Check Vault health and seal status, and list the mounted secret engines and auth methods

Expect the seal status, the Vault version, and a list of mounts such as secret/ (KV v2) and auth methods such as approle/.

Example prompts

Which keys does secret/myapp/config hold, and when was it last updated?
What policies and TTL does the current Vault token have?
Issue a database credential from the readonly role and tell me when the lease expires

Troubleshooting

Connection fails with "no such host" or connection refused

VAULT_ADDR points at an address CloudThinker can’t reach. localhost, 127.0.0.1, and private hostnames resolve where CloudThinker runs the command. Use a public DNS name or your HCP endpoint. A Vault behind a firewall or VPN needs a reachable endpoint or allowlisted access first.

unsupported protocol scheme

The address is missing its scheme. Use https://vault.example.com:8200, not vault.example.com:8200.

Invalid Vault token configuration, or Invalid Vault AppRole configuration

A credential field for the selected auth method is empty. Fill in VAULT_TOKEN for Token, or both VAULT_ROLE_ID and VAULT_SECRET_ID for AppRole.

403 permission denied

Vault returns 403 both when the policy doesn’t cover a path and when the path doesn’t exist, so a 403 never proves a secret is missing. Ask the agent which policies the token has, then add read or list on the path. For KV v2, reading secret/myapp needs the policy on secret/data/myapp.If requests that used to work now all return 403, the token has probably expired. Issue a new one and update VAULT_TOKEN.

"no handler for route" on HCP or Enterprise

VAULT_NAMESPACE is empty or wrong. Set it to the namespace your secrets live in. HCP Vault Dedicated uses admin by default.

invalid secret_id

The AppRole secret ID passed its secret_id_ttl. Generate a new one and paste it into VAULT_SECRET_ID as described in Security:

vault write -f auth/approle/role/cloudthinker/secret-id

Every request fails and health shows sealed: true

The cluster is sealed, so no read or write can succeed. A Vault operator must unseal it with vault operator unseal.

Security

Least privilege — grant only the permissions the agents need for your use case; start read-only and widen later.
Read-only by default — use read-only credentials unless you want agents to make changes through this connection.
Rotate credentials — rotate keys and tokens on your normal schedule; CloudThinker picks up the new value when you update the connection.
Revoke on offboarding — remove the credential at the provider when you delete a connection or a teammate leaves.

Replace a credential: open More → Workspace settings → Connections, select HashiCorp Vault, click the pencil icon (Edit) on the connection, paste the new token or secret ID, and click Save and test. If the test fails, the connection keeps its previous credentials.
Prefer AppRole in production: each session gets a token that expires in the TTL you set, and you rotate the secret ID without touching the role.
Keep secret values out of chat: agents list keys by default. If you ask for a value, it appears in the conversation, so ask only when you need it.
Revoke leases you no longer need: ask the agent to revoke a dynamic credential once the task is done, instead of waiting for it to expire.

Approvals

Decide which Vault writes run, wait for a person, or are refused.

Connections

See every service you can connect and how connection status works.

Connections

Customize

Approvals

Workspace settings

Admin Settings

Artifacts and sharing

Prerequisites

Choose an auth method

Setup

Connection details

Required permissions

Agent capabilities

Verify the connection

Example prompts

Troubleshooting

Security

Approvals

Connections

​Prerequisites

​Choose an auth method

​Setup

​Connection details

​Required permissions

​Agent capabilities

​Verify the connection

​Example prompts

​Troubleshooting

​Security

​Related

Approvals

Connections

Prerequisites

Choose an auth method

Setup

Connection details

Required permissions

Agent capabilities

Verify the connection

Example prompts

Troubleshooting

Security

Related