Skip to content

Infisical is the open-source platform for securing secrets, certificates, access, and AI Agents.

create the access bundle once in the quickstart and put sandbox guides first

Adrian Kahaliceaea652e561
diff --git a/docs/docs.json b/docs/docs.json
index ef585d5509..7a17657550 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -702,16 +702,6 @@
{
"group": "Guides",
"pages": [
- {
- "group": "Local development",
- "pages": [
- "documentation/platform/agent-vault/guides/claude-code",
- "documentation/platform/agent-vault/guides/codex",
- "documentation/platform/agent-vault/guides/opencode",
- "documentation/platform/agent-vault/guides/hermes",
- "documentation/platform/agent-vault/guides/openclaw"
- ]
- },
{
"group": "Sandboxes",
"pages": [
@@ -726,7 +716,17 @@
"documentation/platform/agent-vault/guides/openclaw-gateway"
]
},
- "documentation/platform/agent-vault/guides/custom-agent"
+ "documentation/platform/agent-vault/guides/custom-agent",
+ {
+ "group": "Local development",
+ "pages": [
+ "documentation/platform/agent-vault/guides/claude-code",
+ "documentation/platform/agent-vault/guides/codex",
+ "documentation/platform/agent-vault/guides/opencode",
+ "documentation/platform/agent-vault/guides/hermes",
+ "documentation/platform/agent-vault/guides/openclaw"
+ ]
+ }
]
},
{
diff --git a/docs/documentation/platform/agent-vault/guides/custom-agent.mdx b/docs/documentation/platform/agent-vault/guides/custom-agent.mdx
index 200719a366..983979caf3 100644
--- a/docs/documentation/platform/agent-vault/guides/custom-agent.mdx
+++ b/docs/documentation/platform/agent-vault/guides/custom-agent.mdx
@@ -11,45 +11,16 @@ If you have a custom agent harness that you start from code rather than a CLI, y
## Prerequisites
- An Infisical organization where you're an [Agent Vault admin](/documentation/platform/agent-vault/access-control#product-membership)
+- An [access bundle](/documentation/platform/agent-vault/access-bundles) with a service for each key your agent uses (see the [quickstart](/documentation/platform/agent-vault/quickstart))
- The [Infisical CLI](/cli/install) installed on the machine that will run the proxy
-- The API keys your agent uses, such as its model provider's key
<SeparateMachinesNote />
## Step 1: Set up Agent Vault
-### Create an access bundle
-
-First, create an [access bundle](/documentation/platform/agent-vault/access-bundles) that holds a [service](/documentation/platform/agent-vault/services) for each API your agent calls.
-
-<Steps>
- <Step>
- In Infisical, open **Agent Vault** from the product switcher and go to **Access Bundles**.
- </Step>
- <Step>
- Select **Create Access Bundle**. Give the access bundle a **Name**, such as `my-agent`, then select **Create Access Bundle**.
- </Step>
- <Step>
- Select the access bundle you just created, then select **Add Service**.
- </Step>
- <Step>
- On the **Choose a template** panel, pick the template for the API, or select **Custom HTTP API** and enter the API's host.
- </Step>
- <Step>
- On the **Credential** step, paste the real API key.
-
- <Note>
- If the API expects the key somewhere other than a header, such as in the URL, [add a substitution](/documentation/platform/agent-vault/http-apis#add-a-substitution) instead. Note the placeholder you enter in **Replace**, because your agent sends it in [Step 3](#step-3-replace-the-api-keys-with-placeholders).
- </Note>
- </Step>
- <Step>
- Select **Add Service**. Repeat from the third step for each remaining API.
- </Step>
-</Steps>
-
### Create a proxy
-Next, create a proxy. Every request your agent makes goes through the proxy, which attaches the real credential from the access bundle before forwarding the request to the API.
+First, create a proxy. Every request your agent makes goes through the proxy, which attaches the real credential from the access bundle before forwarding the request to the API.
<Steps>
<Step>
@@ -77,7 +48,7 @@ Finally, create a session. The session token is the only credential your agent h
Go to **Sessions** and select **Create Session**.
</Step>
<Step>
- Pick the access bundle you created, set a duration under **Expires**, then select **Create Session**.
+ Pick your access bundle, set a duration under **Expires**, then select **Create Session**.
</Step>
<Step>
Copy the session token from the command in the dialog. It's the value after `--session-token`. The token appears once and can't be retrieved again.
@@ -111,7 +82,7 @@ Store `ca.pem` where the agent can read it. The certificate isn't secret, so you
Delete the real API keys from the agent's code and configuration. Most SDKs refuse to start without a key, so pass a placeholder value instead, such as `agent-vault`. The proxy replaces the placeholder with the real credential:
- **If the service uses Bearer or Basic credentials:** the proxy replaces the header that carries the key, so any placeholder works
-- **If the service uses a [substitution](/documentation/platform/agent-vault/http-apis#substitutions):** use the exact placeholder you entered in [Step 1](#create-an-access-bundle)
+- **If the service uses a [substitution](/documentation/platform/agent-vault/http-apis#substitutions):** use the exact placeholder you entered in **Replace** for that service
## Step 4: Send requests through the proxy
diff --git a/docs/documentation/platform/agent-vault/guides/daytona.mdx b/docs/documentation/platform/agent-vault/guides/daytona.mdx
index 5550117bf2..3606d68f91 100644
--- a/docs/documentation/platform/agent-vault/guides/daytona.mdx
+++ b/docs/documentation/platform/agent-vault/guides/daytona.mdx
@@ -48,10 +48,10 @@ Every proxy starts from the same proxy token, so you set up the proxy once, no m
## Prerequisites
- The **Admin** role in [Agent Vault](/documentation/platform/agent-vault/access-control#product-membership)
+- An [access bundle](/documentation/platform/agent-vault/access-bundles) with a service for each key the agent uses, including its model provider's key, such as **Anthropic** for Claude Code (see the [quickstart](/documentation/platform/agent-vault/quickstart))
- A [Daytona](https://www.daytona.io) organization on [Tier 3 or 4](https://www.daytona.io/docs/en/network-limits/#tier-based-network-restrictions), because on Tiers 1 and 2 you can't limit a sandbox to reaching the proxy, and the proxy can't reach Infisical
- A [Daytona API key](https://www.daytona.io/docs/en/api-keys/) in the `DAYTONA_API_KEY` environment variable on the machine that runs your code
- The Daytona SDK for your language: [Python](https://pypi.org/project/daytona/) (with [`requests`](https://pypi.org/project/requests/)), [TypeScript](https://www.npmjs.com/package/@daytona/sdk), [Go](https://pkg.go.dev/github.com/daytona/clients/sdk-go) (with [`api-client-go`](https://pkg.go.dev/github.com/daytona/clients/api-client-go)), [Ruby](https://rubygems.org/gems/daytona), or [Java](https://central.sonatype.com/artifact/io.daytona/sdk) (with [Jackson](https://github.com/FasterXML/jackson-databind))
-- The API keys your agent uses, such as your Anthropic API key
## Step 1: Set up Agent Vault
diff --git a/docs/documentation/platform/agent-vault/guides/hermes-gateway.mdx b/docs/documentation/platform/agent-vault/guides/hermes-gateway.mdx
index 33eb302bbf..ff436e2e36 100644
--- a/docs/documentation/platform/agent-vault/guides/hermes-gateway.mdx
+++ b/docs/documentation/platform/agent-vault/guides/hermes-gateway.mdx
@@ -53,6 +53,7 @@ This guide walks you through running the [Hermes Agent](https://hermes-agent.nou
## Prerequisites
- An Infisical organization where you're an Agent Vault admin
+- An [access bundle](/documentation/platform/agent-vault/access-bundles) for Hermes (see the [quickstart](/documentation/platform/agent-vault/quickstart))
- Two machines on the same private network, one for the Agent Vault proxy and one for Hermes (physical machines, virtual machines, or containers)
- [Hermes Agent](https://hermes-agent.nousresearch.com/docs/getting-started/quickstart) installed on the Hermes machine, with the [gateway](https://hermes-agent.nousresearch.com/docs/user-guide/messaging) set up and working with your real API keys
- The [Infisical CLI](/cli/install) 0.43.133 or later installed on the Agent Vault machine (earlier versions don't apply [substitutions](/documentation/platform/agent-vault/http-apis#substitutions))
@@ -74,13 +75,12 @@ To list the names of the keys in `~/.hermes/.env` without printing their values,
grep -o '^[A-Za-z_][A-Za-z0-9_]*=' ~/.hermes/.env | tr -d '='
```
-Take note of each key that holds a credential for an API. In [Step 2](#step-2-set-up-agent-vault), you'll create
-[services](/documentation/platform/agent-vault/services) that hold these keys.
+Take note of each key that holds a credential for an API. In [Step 2](#step-2-set-up-agent-vault), you'll make sure your access bundle has a [service](/documentation/platform/agent-vault/services) for each of these keys.
<Accordion title="How do I know which keys to use?">
Most Hermes setups have three kinds of API keys:
-| Kind | Example keys | Service to add in Step 2 |
+| Kind | Example keys | Service for the key |
| --- | --- | --- |
| Model provider (the LLM API Hermes sends its prompts to) | `OPENROUTER_API_KEY`, `ANTHROPIC_API_KEY`, `OPENAI_API_KEY` | The provider's template, such as **OpenRouter**, **Anthropic**, or **OpenAI** |
| Messaging platform (where you chat with Hermes) | `TELEGRAM_BOT_TOKEN` | A **Custom HTTP API** service for `api.telegram.org` |
@@ -93,25 +93,19 @@ If your `~/.hermes/.env` contains any keys that hold non-sensitive information,
## Step 2: Set up Agent Vault
-### Create an access bundle
+### Add the keys to your access bundle
-First, create an [access bundle](/documentation/platform/agent-vault/access-bundles) that holds a service for each API from [Step 1](#step-1-list-the-api-keys-hermes-uses).
+Open your access bundle in Agent Vault and check that it has a service for each key from [Step 1](#step-1-list-the-api-keys-hermes-uses). For each key that's missing:
<Steps>
<Step>
- In Infisical, open **Agent Vault** from the product switcher and go to **Access Bundles**.
+ In the access bundle, select **Add Service**.
</Step>
<Step>
- Select **Create Access Bundle**. Give the access bundle a **Name**, such as `hermes-gateway`, then select **Create Access Bundle**.
+ On the **Choose a template** panel, pick the template for the API, or select **Custom HTTP API**. On the **Details** step, check the hosts, or enter the API's host for a **Custom HTTP API** service, then select **Continue**.
</Step>
<Step>
- Select the access bundle you just created, then select **Add Service**.
- </Step>
- <Step>
- On the **Choose a template** panel, pick the template for the API, or select **Custom HTTP API** and enter the API's host.
- </Step>
- <Step>
- On the **Credential** step, paste the real value of the API key from `~/.hermes/.env`.
+ On the **Credential** step, paste the real value of the API key from `~/.hermes/.env`, then select **Continue**.
<Note>
[Add a substitution](/documentation/platform/agent-vault/http-apis#add-a-substitution) for each key instead if either of these is true:
@@ -123,13 +117,13 @@ First, create an [access bundle](/documentation/platform/agent-vault/access-bund
</Note>
</Step>
<Step>
- Select **Add Service**. Repeat from the third step for each remaining API.
+ On the **Review** step, select **Add Service**.
</Step>
</Steps>
### Create a proxy
-Next, create a [proxy](/documentation/platform/agent-vault/proxies) on the Agent Vault machine. Every request Hermes makes will go through this proxy first. The proxy gets the real credential from the access bundle you just created. It attaches the credential to the request, then forwards the request to the API.
+Next, create a [proxy](/documentation/platform/agent-vault/proxies) on the Agent Vault machine. Every request Hermes makes will go through this proxy first. The proxy gets the real credential from your access bundle. It attaches the credential to the request, then forwards the request to the API.
<Steps>
<Step>
@@ -217,7 +211,7 @@ Finally, create a [session](/documentation/platform/agent-vault/sessions) for th
Go to **Sessions** and select **Create Session**.
</Step>
<Step>
- Pick the access bundle you created, set **Expires** to **Never**, then select **Create Session**.
+ Pick your access bundle, set **Expires** to **Never**, then select **Create Session**.
</Step>
<Step>
Copy the session token from the command in the dialog. It's the value after `--session-token`. The token appears once and can't be retrieved again.
@@ -251,7 +245,7 @@ Compare the colon-separated value with the proxy's fingerprint in Infisical. On
### Replace the API keys with placeholders
-Open `~/.hermes/.env` and replace the value of each API key you added a service for in [Step 2](#create-an-access-bundle):
+Open `~/.hermes/.env` and replace the value of each API key that has a service in your [access bundle](#add-the-keys-to-your-access-bundle):
- **For a service that attaches the credential to a header:** use any value Hermes accepts as a key (the proxy replaces the header with the real credential)
- **For a service with a substitution:** use the exact placeholder you entered in **Replace**
diff --git a/docs/documentation/platform/agent-vault/guides/modal.mdx b/docs/documentation/platform/agent-vault/guides/modal.mdx
index e11aafba8c..1c9e6c6fb7 100644
--- a/docs/documentation/platform/agent-vault/guides/modal.mdx
+++ b/docs/documentation/platform/agent-vault/guides/modal.mdx
@@ -48,44 +48,12 @@ Every sidecar starts its proxy from the same proxy token, so you create the prox
## Prerequisites
- The **Admin** role in [Agent Vault](/documentation/platform/agent-vault/access-control#product-membership)
+- An [access bundle](/documentation/platform/agent-vault/access-bundles) with a service for each key the agent uses, including its model provider's key, such as **Anthropic** for Claude Code (see the [quickstart](/documentation/platform/agent-vault/quickstart))
- A [Modal](https://modal.com) account, with a [Modal token](https://modal.com/docs/reference/cli/token) on the machine that runs your code (run `modal setup`, or set `MODAL_TOKEN_ID` and `MODAL_TOKEN_SECRET`)
- The Modal SDK for your language: the [`modal`](https://pypi.org/project/modal/) and [`requests`](https://pypi.org/project/requests/) packages for Python, the [`modal`](https://www.npmjs.com/package/modal) package for TypeScript, or the [Modal Go SDK](https://pkg.go.dev/github.com/modal-labs/modal-client/go)
-- The API keys your agent uses, such as your Anthropic API key
## Step 1: Set up Agent Vault
-### Create an access bundle
-
-Create an [access bundle](/documentation/platform/agent-vault/access-bundles) that contains a [service](/documentation/platform/agent-vault/services) for each API the agent calls.
-
-<Steps>
- <Step>
- In Infisical, open **Agent Vault** from the product switcher and go to **Access Bundles**.
- </Step>
- <Step>
- Select **Create Access Bundle**. Give the access bundle a **Name**, such as `modal-agent`, then select **Create Access Bundle**.
- </Step>
- <Step>
- Select the access bundle you just created, then select **Add Service**.
- </Step>
- <Step>
- On the **Choose a template** panel, pick the template for the API, such as **Anthropic**, or select **Custom**.
- </Step>
- <Step>
- On the **Details** step, check the hosts the service covers, or enter the API's host if you selected **Custom**, then select **Continue**.
- </Step>
- <Step>
- On the **Credential** step, paste the real API key.
-
- <Note>
- If the API expects the key somewhere other than a header, such as in the URL, [add a substitution](/documentation/platform/agent-vault/http-apis#add-a-substitution) instead, and have the agent send the placeholder you enter in **Replace**.
- </Note>
- </Step>
- <Step>
- Select **Add Service**. Repeat from the third step for each remaining API.
- </Step>
-</Steps>
-
### Create a proxy
<Steps>
@@ -104,7 +72,7 @@ Create an [access bundle](/documentation/platform/agent-vault/access-bundles) th
### Create a machine identity for your code
-Your code creates a session for each run as a [machine identity](/documentation/platform/identities/machine-identities). Give the machine identity the **Member** role and access to only this access bundle, because an Agent Vault admin can create sessions for every access bundle.
+Your code creates a session for each run as a [machine identity](/documentation/platform/identities/machine-identities). Give the machine identity the **Member** role and access to only your access bundle, because an Agent Vault admin can create sessions for every access bundle.
<MachineIdentitySetup />
diff --git a/docs/documentation/platform/agent-vault/guides/openclaw-gateway.mdx b/docs/documentation/platform/agent-vault/guides/openclaw-gateway.mdx
index 035572f320..a844e9d0c5 100644
--- a/docs/documentation/platform/agent-vault/guides/openclaw-gateway.mdx
+++ b/docs/documentation/platform/agent-vault/guides/openclaw-gateway.mdx
@@ -53,6 +53,7 @@ This guide walks you through running the [OpenClaw](https://docs.openclaw.ai/) [
## Prerequisites
- An Infisical organization where you're an Agent Vault admin
+- An [access bundle](/documentation/platform/agent-vault/access-bundles) for OpenClaw (see the [quickstart](/documentation/platform/agent-vault/quickstart))
- Two machines on the same private network, one for the Agent Vault proxy and one for OpenClaw (physical machines, virtual machines, or containers)
- [OpenClaw](https://docs.openclaw.ai/start/getting-started) installed on the OpenClaw machine, with the gateway installed as a service (`openclaw onboard --install-daemon`) and a messaging platform set up and working with your real API keys
- The [Infisical CLI](/cli/install) 0.43.133 or later installed on the Agent Vault machine (earlier versions don't apply [substitutions](/documentation/platform/agent-vault/http-apis#substitutions))
@@ -68,13 +69,12 @@ OpenClaw can keep API keys in three places. Check each one on the OpenClaw machi
- **Channel tokens in OpenClaw's config:** such as `channels.telegram.botToken` for Telegram
- **`~/.openclaw/.env`:** if you added keys to this file yourself, list their names without printing their values by running `grep -o '^[A-Za-z_][A-Za-z0-9_]*=' ~/.openclaw/.env | tr -d '='`
-Take note of each key that holds a credential for an API. In [Step 2](#step-2-set-up-agent-vault), you'll create
-[services](/documentation/platform/agent-vault/services) that hold these keys.
+Take note of each key that holds a credential for an API. In [Step 2](#step-2-set-up-agent-vault), you'll make sure your access bundle has a [service](/documentation/platform/agent-vault/services) for each of these keys.
<Accordion title="How do I know which keys to use?">
Most OpenClaw setups have three kinds of API keys:
-| Kind | Example keys | Service to add in Step 2 |
+| Kind | Example keys | Service for the key |
| --- | --- | --- |
| Model provider (the LLM API OpenClaw sends its prompts to) | `OPENROUTER_API_KEY`, `ANTHROPIC_API_KEY`, `OPENAI_API_KEY` | The provider's template, such as **OpenRouter**, **Anthropic**, or **OpenAI** |
| Messaging platform (where you chat with OpenClaw) | `channels.telegram.botToken` or `TELEGRAM_BOT_TOKEN` | A **Custom HTTP API** service for `api.telegram.org` |
@@ -87,25 +87,19 @@ Settings that hold non-sensitive information don't need services in Agent Vault.
## Step 2: Set up Agent Vault
-### Create an access bundle
+### Add the keys to your access bundle
-First, create an [access bundle](/documentation/platform/agent-vault/access-bundles) that holds a service for each API from [Step 1](#step-1-list-the-api-keys-openclaw-uses).
+Open your access bundle in Agent Vault and check that it has a service for each key from [Step 1](#step-1-list-the-api-keys-openclaw-uses). For each key that's missing:
<Steps>
<Step>
- In Infisical, open **Agent Vault** from the product switcher and go to **Access Bundles**.
+ In the access bundle, select **Add Service**.
</Step>
<Step>
- Select **Create Access Bundle**. Give the access bundle a **Name**, such as `openclaw-gateway`, then select **Create Access Bundle**.
+ On the **Choose a template** panel, pick the template for the API, or select **Custom HTTP API**. On the **Details** step, check the hosts, or enter the API's host for a **Custom HTTP API** service, then select **Continue**.
</Step>
<Step>
- Select the access bundle you just created, then select **Add Service**.
- </Step>
- <Step>
- On the **Choose a template** panel, pick the template for the API, or select **Custom HTTP API** and enter the API's host.
- </Step>
- <Step>
- On the **Credential** step, paste the real value of the API key.
+ On the **Credential** step, paste the real value of the API key, then select **Continue**.
<Note>
[Add a substitution](/documentation/platform/agent-vault/http-apis#add-a-substitution) for each key instead if either of these is true:
@@ -117,13 +111,13 @@ First, create an [access bundle](/documentation/platform/agent-vault/access-bund
</Note>
</Step>
<Step>
- Select **Add Service**. Repeat from the third step for each remaining API.
+ On the **Review** step, select **Add Service**.
</Step>
</Steps>
### Create a proxy
-Next, create a [proxy](/documentation/platform/agent-vault/proxies) on the Agent Vault machine. Every request OpenClaw makes will go through this proxy first. The proxy gets the real credential from the access bundle you just created. It attaches the credential to the request, then forwards the request to the API.
+Next, create a [proxy](/documentation/platform/agent-vault/proxies) on the Agent Vault machine. Every request OpenClaw makes will go through this proxy first. The proxy gets the real credential from your access bundle. It attaches the credential to the request, then forwards the request to the API.
<Steps>
<Step>
@@ -211,7 +205,7 @@ Finally, create a [session](/documentation/platform/agent-vault/sessions) for th
Go to **Sessions** and select **Create Session**.
</Step>
<Step>
- Pick the access bundle you created, set **Expires** to **Never**, then select **Create Session**.
+ Pick your access bundle, set **Expires** to **Never**, then select **Create Session**.
</Step>
<Step>
Copy the session token from the command in the dialog. It's the value after `--session-token`. The token appears once and can't be retrieved again.
@@ -275,7 +269,7 @@ OpenClaw's gateway runs on Node.js, which only reads its trusted certificates wh
### Replace the API keys with placeholders
-Replace each API key you added a service for in [Step 2](#create-an-access-bundle) with a placeholder, wherever OpenClaw keeps it:
+Replace each API key that has a service in your [access bundle](#add-the-keys-to-your-access-bundle) with a placeholder, wherever OpenClaw keeps it:
- **For a service that attaches the credential to a header:** use any value (the proxy replaces the header with the real credential)
- **For a service with a substitution:** use the exact placeholder you entered in **Replace**
@@ -293,7 +287,7 @@ openclaw config set channels.telegram.botToken __TELEGRAM_BOT_TOKEN__
```
<Note>
-If the channel's service uses a substitution, make sure you set the token to the exact value you entered in **Replace** in [Step 2](#create-an-access-bundle).
+If the channel's service uses a substitution, make sure you set the token to the exact value you entered in **Replace** for that service.
</Note>
The real values are now stored in Infisical, so you don't need to keep them on the OpenClaw machine.
diff --git a/docs/documentation/platform/agent-vault/plan-your-setup.mdx b/docs/documentation/platform/agent-vault/plan-your-setup.mdx
index 8efe2e8737..46644948d1 100644
--- a/docs/documentation/platform/agent-vault/plan-your-setup.mdx
+++ b/docs/documentation/platform/agent-vault/plan-your-setup.mdx
@@ -188,11 +188,8 @@ Follow these pages in order:
<AgentVaultSetupBranch building="personal,assistant" agent="none">
<li>[Quickstart](/documentation/platform/agent-vault/quickstart): create an access bundle with a service for each API the agent calls, then follow the guide for where your agent runs</li>
</AgentVaultSetupBranch>
- <AgentVaultSetupBranch building="personal,assistant" agent="claude-code,codex,opencode">
- <li>[Quickstart](/documentation/platform/agent-vault/quickstart): create an access bundle with a service for each API the agent calls</li>
- </AgentVaultSetupBranch>
- <AgentVaultSetupBranch building="personal" agent="hermes,openclaw">
- <li>[Quickstart](/documentation/platform/agent-vault/quickstart): create an access bundle with a service for each API the agent calls</li>
+ <AgentVaultSetupBranch building="personal,assistant" agent="claude-code,codex,opencode,hermes,openclaw,custom">
+ <li>[Quickstart](/documentation/platform/agent-vault/quickstart): create an access bundle with a service for each key the agent uses</li>
</AgentVaultSetupBranch>
<AgentVaultSetupBranch building="personal,assistant" agent="claude-code">
<li>[Agent Vault with Claude Code](/documentation/platform/agent-vault/guides/claude-code): create a proxy, create a session, and start Claude Code with the session token</li>
@@ -210,13 +207,13 @@ Follow these pages in order:
<li>[Agent Vault with OpenClaw](/documentation/platform/agent-vault/guides/openclaw): create a proxy, create a session, and start OpenClaw in your terminal with the session token</li>
</AgentVaultSetupBranch>
<AgentVaultSetupBranch building="assistant" agent="hermes">
- <li>[Agent Vault with the Hermes gateway](/documentation/platform/agent-vault/guides/hermes-gateway): create a session that never expires, then send the Hermes gateway's requests through the proxy</li>
+ <li>[Agent Vault with the Hermes gateway](/documentation/platform/agent-vault/guides/hermes-gateway): add Hermes's keys to the access bundle, create a session that never expires, then send the Hermes gateway's requests through the proxy</li>
</AgentVaultSetupBranch>
<AgentVaultSetupBranch building="assistant" agent="openclaw">
- <li>[Agent Vault with the OpenClaw gateway](/documentation/platform/agent-vault/guides/openclaw-gateway): create a session that never expires, then send the OpenClaw gateway's requests through the proxy</li>
+ <li>[Agent Vault with the OpenClaw gateway](/documentation/platform/agent-vault/guides/openclaw-gateway): add OpenClaw's keys to the access bundle, create a session that never expires, then send the OpenClaw gateway's requests through the proxy</li>
</AgentVaultSetupBranch>
<AgentVaultSetupBranch building="personal,assistant" agent="custom">
- <li>[Connect your own agent](/documentation/platform/agent-vault/guides/custom-agent): create an access bundle, create a proxy, create a session, and send your agent's requests through the proxy</li>
+ <li>[Connect your own agent](/documentation/platform/agent-vault/guides/custom-agent): create a proxy, create a session, and send your agent's requests through the proxy</li>
</AgentVaultSetupBranch>
<AgentVaultSetupBranch building="scheduled,platform">
diff --git a/docs/documentation/platform/agent-vault/quickstart.mdx b/docs/documentation/platform/agent-vault/quickstart.mdx
index 1a3fbd9590..4dedc53fd0 100644
--- a/docs/documentation/platform/agent-vault/quickstart.mdx
+++ b/docs/documentation/platform/agent-vault/quickstart.mdx
@@ -4,12 +4,12 @@ sidebarTitle: "Quickstart"
description: "Store your API credentials in an access bundle and connect the agents that use them."
---
-This quickstart walks you through the setup shared by every Agent Vault workflow. You'll create an [access bundle](/documentation/platform/agent-vault/access-bundles), add a [service](/documentation/platform/agent-vault/services) with the real credentials for each API your agents call, and then continue with the guide for where your agents run.
+This quickstart walks you through the setup shared by every Agent Vault workflow. You'll create an [access bundle](/documentation/platform/agent-vault/access-bundles), add a [service](/documentation/platform/agent-vault/services) for each key your agent uses, and then continue with the guide for where your agent runs.
## Prerequisites
- An Infisical organization where you're an [Agent Vault admin](/documentation/platform/agent-vault/access-control#product-membership)
-- Credentials for each API you want your agents to call (such as an API token)
+- The API keys your agent uses, such as its model provider's key
## Step 1: Add your credentials
@@ -17,14 +17,14 @@ This quickstart walks you through the setup shared by every Agent Vault workflow
<Tab title="Infisical dashboard">
### Create an access bundle
- In Agent Vault, an [access bundle](/documentation/platform/agent-vault/access-bundles) defines the [services](/documentation/platform/agent-vault/services) your agents can reach. To create an access bundle:
+ In Agent Vault, an [access bundle](/documentation/platform/agent-vault/access-bundles) defines the [services](/documentation/platform/agent-vault/services) your agents can reach. To create an access bundle:
<Steps>
<Step>
In Infisical, open **Agent Vault** from the product switcher and go to **Access Bundles**.
</Step>
<Step>
- Select **Create Access Bundle**. Give the access bundle a **Name**, then select **Create Access Bundle**.
+ Select **Create Access Bundle**. Give the access bundle a **Name**, such as `code-review`, then select **Create Access Bundle**.
<Frame>
<img src="/images/platform/agent-vault/access-bundle-create.png" alt="The Create Access Bundle dialog with code-review entered as the name" />
@@ -34,28 +34,40 @@ This quickstart walks you through the setup shared by every Agent Vault workflow
### Add a service
+ Next, add a service for each key your agent uses.
+
+ <Accordion title="What services do I need?">
+ - Its model provider's API key, such as `ANTHROPIC_API_KEY`, if the agent uses one
+ - Each API it calls, such as GitHub
+ - For a messaging gateway, the platform's token (see the keys that [Hermes](/documentation/platform/agent-vault/guides/hermes-gateway#step-1-list-the-api-keys-hermes-uses) or [OpenClaw](/documentation/platform/agent-vault/guides/openclaw-gateway#step-1-list-the-api-keys-openclaw-uses) uses)
+ - Each remote MCP server it connects to, such as Linear's (see [add an MCP server](/documentation/platform/agent-vault/mcp-servers#add-an-mcp-server))
+ </Accordion>
+
<Steps>
<Step>
- Select the access bundle you just created, then select **Add Service**.
+ In the access bundle, select **Add Service**.
</Step>
<Step>
- Find the template for the API you want your agents to call, then select it.
+ On the **Choose a template** panel, pick the template for the API, or select **Custom HTTP API**.
<Frame>
<img src="/images/platform/agent-vault/service-template-picker.png" alt="The Choose a template panel with GitHub among the available services" />
</Frame>
-
- If the API isn't on the list, select **Custom** and set the host, header name, and prefix yourself.
</Step>
<Step>
- The template fills in the host and the header that the API expects. Paste your credential in the **Credential** section.
+ On the **Details** step, check the hosts the service covers, or enter the API's host if you selected **Custom HTTP API**. Select **Continue**.
</Step>
<Step>
- Select **Add Service**.
+ On the **Credential** step, paste the real key, then select **Continue**.
+
+ <Note>
+ If the API takes the key somewhere other than a header, such as Telegram's bot token in the URL, [add a substitution](/documentation/platform/agent-vault/http-apis#add-a-substitution) instead. Your agent sends the placeholder you enter in **Replace**.
+ </Note>
+ </Step>
+ <Step>
+ On the **Review** step, select **Add Service**. Repeat from the first step for each remaining key.
</Step>
</Steps>
-
- Repeat these steps for each API your agents call.
</Tab>
<Tab title="API">
### Log in as a machine identity
@@ -74,6 +86,8 @@ This quickstart walks you through the setup shared by every Agent Vault workflow
</Step>
</Steps>
+ Use this machine identity only for setup. If your agents' sessions come from code, the guide for your agents has you create a separate machine identity with access to only one access bundle.
+
Call [the login endpoint for Universal Auth](/api-reference/endpoints/universal-auth/login) with the client ID and client secret:
<CodeGroup>
@@ -100,7 +114,7 @@ This quickstart walks you through the setup shared by every Agent Vault workflow
### Create an access bundle
- Call [the endpoint to create an access bundle](/api-reference/endpoints/agent-vault-access-bundles/create), replacing `<access-token>` with the `accessToken` from the login response. In the body, send a name for the access bundle:
+ In Agent Vault, an [access bundle](/documentation/platform/agent-vault/access-bundles) defines the [services](/documentation/platform/agent-vault/services) your agents can reach. Call [the endpoint to create an access bundle](/api-reference/endpoints/agent-vault-access-bundles/create), replacing `<access-token>` with the `accessToken` from the login response. In the body, send a name for the access bundle:
<CodeGroup>
```bash US Cloud
@@ -129,6 +143,15 @@ This quickstart walks you through the setup shared by every Agent Vault workflow
### Add a service
+ Add a service for each key your agent uses.
+
+ <Accordion title="What services do I need?">
+ - Its model provider's API key, such as `ANTHROPIC_API_KEY`, if the agent uses one
+ - Each API it calls, such as GitHub
+ - For a messaging gateway, the platform's token (see the keys that [Hermes](/documentation/platform/agent-vault/guides/hermes-gateway#step-1-list-the-api-keys-hermes-uses) or [OpenClaw](/documentation/platform/agent-vault/guides/openclaw-gateway#step-1-list-the-api-keys-openclaw-uses) uses)
+ - Each remote MCP server it connects to, such as Linear's (see [add an MCP server](/documentation/platform/agent-vault/mcp-servers#add-an-mcp-server))
+ </Accordion>
+
Call [the endpoint to create a service](/api-reference/endpoints/agent-vault-services/create), replacing `<access-bundle-id>` in the URL with the `id` from the previous step and `<access-token>` with the `accessToken` from the login response.
In the body, send the hosts that the credential applies to and the credential itself. For example, to add a GitHub personal access token:
@@ -180,32 +203,20 @@ This quickstart walks you through the setup shared by every Agent Vault workflow
```
</CodeGroup>
- Set `credential.type` to `bearer` for an API that takes a token in a header, `basic` for an API that takes a username and password, or `passthrough` for a host that the agent can call without a credential.
+ Set `credential.type` to `bearer` for an API that takes a token in a header, `basic` for an API that takes a username and password, or `passthrough` for a host that the agent can call without a credential. For a key that goes somewhere other than a header, send a [substitution](/documentation/platform/agent-vault/http-apis#substitutions) instead.
- Repeat this request for each API your agents call.
+ Repeat this request for each remaining key.
</Tab>
</Tabs>
## Step 2: Connect your agents
-Pick the guide for where your agents run. Each guide walks you through setting up a [proxy](/documentation/platform/agent-vault/proxies) and creating [sessions](/documentation/platform/agent-vault/sessions) for your agents.
+Pick the guide for where your agents run. Each guide continues from the access bundle you just created.
<Tip>
If you're not sure which guide fits, [plan your setup](/documentation/platform/agent-vault/plan-your-setup) to get a recommendation.
</Tip>
-### Local development
-
-Launch an agent from your terminal with the Infisical CLI.
-
-<CardGroup cols={3}>
- <Card title="Claude Code" icon="/images/agent-vault-agents/claude-code.svg" href="/documentation/platform/agent-vault/guides/claude-code" />
- <Card title="Codex" icon="/images/agent-vault-agents/OpenAI.png" href="/documentation/platform/agent-vault/guides/codex" />
- <Card title="OpenCode" icon="/images/agent-vault-agents/opencode.svg" href="/documentation/platform/agent-vault/guides/opencode" />
- <Card title="Hermes Agent" icon="/images/agent-vault-agents/hermes.png" href="/documentation/platform/agent-vault/guides/hermes" />
- <Card title="OpenClaw" icon="/images/agent-vault-agents/openclaw.svg" href="/documentation/platform/agent-vault/guides/openclaw" />
-</CardGroup>
-
### Sandboxes
Start each agent in its own sandbox, with its own proxy.
@@ -233,3 +244,15 @@ Keep an assistant running on a server so people can message it from Slack, Teleg
<Card title="Your own agent" icon="code" href="/documentation/platform/agent-vault/guides/custom-agent">
Launch your custom agent with Agent Vault so it can make authenticated API calls without needing an actual token.
</Card>
+
+### Local development
+
+Launch an agent from your terminal with the Infisical CLI.
+
+<CardGroup cols={3}>
+ <Card title="Claude Code" icon="/images/agent-vault-agents/claude-code.svg" href="/documentation/platform/agent-vault/guides/claude-code" />
+ <Card title="Codex" icon="/images/agent-vault-agents/OpenAI.png" href="/documentation/platform/agent-vault/guides/codex" />
+ <Card title="OpenCode" icon="/images/agent-vault-agents/opencode.svg" href="/documentation/platform/agent-vault/guides/opencode" />
+ <Card title="Hermes Agent" icon="/images/agent-vault-agents/hermes.png" href="/documentation/platform/agent-vault/guides/hermes" />
+ <Card title="OpenClaw" icon="/images/agent-vault-agents/openclaw.svg" href="/documentation/platform/agent-vault/guides/openclaw" />
+</CardGroup>
diff --git a/docs/snippets/agent-vault/SandboxAgentVaultSetup.mdx b/docs/snippets/agent-vault/SandboxAgentVaultSetup.mdx
index 832bac666b..31a47544e0 100644
--- a/docs/snippets/agent-vault/SandboxAgentVaultSetup.mdx
+++ b/docs/snippets/agent-vault/SandboxAgentVaultSetup.mdx
@@ -1,37 +1,5 @@
import MachineIdentitySetup from "/snippets/agent-vault/MachineIdentitySetup.mdx";
-### Create an access bundle
-
-Create an [access bundle](/documentation/platform/agent-vault/access-bundles) that holds a [service](/documentation/platform/agent-vault/services) for each API the agent calls.
-
-<Steps>
- <Step>
- In Infisical, open **Agent Vault** from the product switcher and go to **Access Bundles**.
- </Step>
- <Step>
- Select **Create Access Bundle**. Give the access bundle a **Name**, such as `sandbox-agent`, then select **Create Access Bundle**.
- </Step>
- <Step>
- Select the access bundle you just created, then select **Add Service**.
- </Step>
- <Step>
- On the **Choose a template** panel, pick the template for the API, such as **Anthropic** for Claude Code, or select **Custom HTTP API**.
- </Step>
- <Step>
- On the **Details** step, check the hosts the service covers, or enter the API's host if you selected **Custom HTTP API**, then select **Continue**.
- </Step>
- <Step>
- On the **Credential** step, paste the real API key, then select **Continue**.
-
- <Note>
- If the API expects the key somewhere other than a header, such as in the URL, [add a substitution](/documentation/platform/agent-vault/http-apis#add-a-substitution) instead, and have the agent send the placeholder you enter in **Replace**.
- </Note>
- </Step>
- <Step>
- On the **Review** step, select **Add Service**. Repeat from the third step for each remaining API.
- </Step>
-</Steps>
-
### Create a proxy
<Steps>
@@ -52,6 +20,6 @@ Create an [access bundle](/documentation/platform/agent-vault/access-bundles) th
### Create a machine identity for your code
-Your code creates a session for each run as a [machine identity](/documentation/platform/identities/machine-identities). Give the machine identity the **Member** role and access to only this access bundle, because an Agent Vault admin can create sessions for every access bundle.
+Your code creates a session for each run as a [machine identity](/documentation/platform/identities/machine-identities). Give the machine identity the **Member** role and access to only your access bundle, because an Agent Vault admin can create sessions for every access bundle.
<MachineIdentitySetup />