> ## Documentation Index
> Fetch the complete documentation index at: https://infisical.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Plan your Agent Vault setup

> Get a recommended Agent Vault setup for what you're building.

Get started

# Plan your Agent Vault setup

Get a recommended Agent Vault setup for what you're building.

Configure the following options to get custom guidance and best practices tailored to your agent's setup.

## What are you building?

Your answer decides who creates each session and how long each session lasts.

Your answer decides where to run the proxy and how the agent starts.

## Which agent?

Your answer decides which guide to follow and which command starts the agent.

## Your setup

Before running an agent, you set up two things:

<ul>
  <li>An [access bundle](https://infisical.com/docs/documentation/platform/agent-vault/access-bundles.md) in Infisical: a list of the [services](https://infisical.com/docs/documentation/platform/agent-vault/services.md) (the APIs) that the agent can call, each with its real credential</li>
  <li>A running [proxy](https://infisical.com/docs/documentation/platform/agent-vault/proxies.md): a program on its own machine that every request from the agent goes through</li>
</ul>

> [!NOTE]
>
> One proxy stays running and handles the requests from every agent and every job, so you don't need a separate proxy for each job or each host.

A [session](https://infisical.com/docs/documentation/platform/agent-vault/sessions) gives an agent access to the services in one access bundle, until the session expires or someone [revokes it](https://infisical.com/docs/documentation/platform/agent-vault/sessions#revoke-a-session).

You [create the session in the Infisical dashboard](https://infisical.com/docs/documentation/platform/agent-vault/sessions#create-a-session).

You [create one session in the Infisical dashboard](https://infisical.com/docs/documentation/platform/agent-vault/sessions#create-a-session) that never expires, since the assistant keeps running.

Each time the job runs, the [Infisical CLI](https://infisical.com/docs/cli/overview.md) logs in as a [machine identity](https://infisical.com/docs/documentation/platform/identities/machine-identities.md) and creates a session. [Each session lasts](https://infisical.com/docs/documentation/platform/agent-vault/sessions-cli.md#choose-how-long-each-session-lasts) a little longer than the longest run you expect, because the agent loses access to the APIs if a run outlasts its session.

For each task, the orchestrator logs in as a [machine identity](https://infisical.com/docs/documentation/platform/identities/machine-identities.md) and creates a session through the [Infisical API](https://infisical.com/docs/api-reference/endpoints/agent-vault-sessions/create.md). Each kind of task has its own access bundle, and the orchestrator chooses the access bundle when it creates the session.

The session token only works for the services in the session's access bundle, and only until the session expires or is revoked.

The dashboard shows the token in a command that starts the agent with it.

Because the session never expires, revoking it is what stops the assistant from using the real credentials.

The CLI keeps the token and passes it to the agent in the next step, so you never handle the token yourself.

The orchestrator receives the token in the API response.

The agent gets the session token instead of real API keys. [`infisical agent-vault run`](https://infisical.com/docs/cli/reference#agent-vault-run) starts the agent with its requests set to go through the proxy.

You run the command from the dashboard on the agent's host.

The CLI starts the agent right after it creates the session. The agent can read the machine identity's credentials [from its environment](https://infisical.com/docs/documentation/platform/agent-vault/sessions-cli.md#step-2-start-the-agent), and could use them to create a session for any access bundle the machine identity has. That's why the machine identity only has the access bundle that this agent uses.

The orchestrator starts the agent on a different host and passes it only the session token. The orchestrator stays off the agents' hosts because the machine identity it uses can create sessions for every access bundle it's granted. An agent that read those credentials could reach every service in those access bundles.

Nobody is at the terminal while the agent runs, so Claude Code runs in its [non-interactive mode](https://code.claude.com/docs/en/headless): `claude -p "<prompt>"`.

Nobody is at the terminal while the agent runs, so Codex runs in its [non-interactive mode](https://developers.openai.com/codex/noninteractive): `codex exec "<prompt>"`.

Nobody is at the terminal while the agent runs, so OpenCode runs in its [non-interactive mode](https://opencode.ai/docs/cli/#run-1): `opencode run "<prompt>"`.

Nobody is at the terminal while the agent runs, so Hermes runs in its [non-interactive mode](https://hermes-agent.nousresearch.com/docs/user-guide/cli): `hermes chat -q "<prompt>"`.

> [!NOTE]
>
> Hermes won't start without the API keys in `~/.hermes/.env`, so that file holds [placeholder values](https://infisical.com/docs/documentation/platform/agent-vault/guides/hermes#step-2-launch-your-agent), and the proxy attaches the real keys.

Nobody is at the terminal while the agent runs, so OpenClaw runs in its [non-interactive mode](https://docs.openclaw.ai/cli/agent): `openclaw agent --agent <agent-id> --message "<prompt>" --local`. OpenClaw holds a [placeholder](https://infisical.com/docs/documentation/platform/agent-vault/guides/openclaw#step-2-launch-your-agent) instead of your model provider's key, and the proxy attaches the real key.

> [!WARNING]
>
> The agent runs as your user account. If you're logged in to the [Infisical CLI](https://infisical.com/docs/cli/overview.md) on the same computer, the agent can run Infisical CLI commands with your login.

The agent calls an API the same way it always does, but the request is intercepted by the proxy.

<ul>
  <li>If you don't have a second machine, a small VM on your network can run the proxy</li>

  <li>The agents' containers can't read the proxy token</li>

  <li>The CI runner has to reach the proxy, so if the proxy is on a private network, the job runs on a [self-hosted runner](https://docs.github.com/en/actions/hosting-your-own-runners) in that network</li>
</ul>

> [!NOTE]
>
> The proxy [runs on a different machine](https://infisical.com/docs/documentation/platform/agent-vault/proxies.md#choose-where-to-run-the-proxy) from the agent, on the same private network. If the proxy ran on the agent's machine, the agent could read the proxy token.

The credentials go from Infisical to the proxy, never to the agent. The proxy checks Infisical for updated values every [poll interval](https://infisical.com/docs/documentation/platform/agent-vault/proxies.md#poll-interval) (60 seconds by default).

The [real credential](https://infisical.com/docs/documentation/platform/agent-vault/services.md#credential-types) is added to the request at the proxy, so it never passes through the agent. The request appears in the session's [logs](https://infisical.com/docs/documentation/platform/agent-vault/session-logs.md).

The proxy only attaches credentials for the services in the access bundle. Requests to any other host go out without a credential, unless the proxy's [traffic policy](https://infisical.com/docs/documentation/platform/agent-vault/proxies.md#traffic-policy) blocks them.

From then on, the session token stops working. If the machine shuts down before the CLI can revoke the session, the session keeps working until its `--ttl` runs out.

The orchestrator revokes the session through the [Infisical API](https://infisical.com/docs/api-reference/endpoints/agent-vault-sessions/revoke.md).

## Build your setup

Follow these pages in order:

<ol>
  <li>[Quickstart](https://infisical.com/docs/documentation/platform/agent-vault/quickstart.md): create an access bundle, create a proxy, create a session, and start your agent with the session token</li>

  <li>[Agent Vault with Claude Code](https://infisical.com/docs/documentation/platform/agent-vault/guides/claude-code.md): create an access bundle, create a proxy, create a session, and start Claude Code with the session token</li>

  <li>[Agent Vault with Codex](https://infisical.com/docs/documentation/platform/agent-vault/guides/codex.md): create an access bundle, create a proxy, create a session, and start Codex with the session token</li>

  <li>[Agent Vault with OpenCode](https://infisical.com/docs/documentation/platform/agent-vault/guides/opencode.md): create an access bundle, create a proxy, create a session, and start OpenCode with the session token</li>

  <li>[Agent Vault with Hermes Agent](https://infisical.com/docs/documentation/platform/agent-vault/guides/hermes): create an access bundle, create a proxy, create a session, and start Hermes in your terminal with the session token</li>

  <li>[Agent Vault with OpenClaw](https://infisical.com/docs/documentation/platform/agent-vault/guides/openclaw): create an access bundle, create a proxy, create a session, and start OpenClaw in your terminal with the session token</li>

  <li>[Agent Vault with the Hermes gateway](https://infisical.com/docs/documentation/platform/agent-vault/guides/hermes-gateway.md): create a session that never expires, then send the Hermes gateway's requests through the proxy</li>

  <li>[Agent Vault with the OpenClaw gateway](https://infisical.com/docs/documentation/platform/agent-vault/guides/openclaw-gateway.md): create a session that never expires, then send the OpenClaw gateway's requests through the proxy</li>

  <li>[Connect your own agent](https://infisical.com/docs/documentation/platform/agent-vault/guides/custom-agent.md): create an access bundle, create a proxy, create a session, and send your agent's requests through the proxy</li>

  <li>[Create an access bundle](https://infisical.com/docs/documentation/platform/agent-vault/access-bundles.md#create-an-access-bundle), with a service for each API the agent calls</li>
  <li>[Create a proxy](https://infisical.com/docs/documentation/platform/agent-vault/proxies.md#create-a-proxy-and-start-it), and run it with Docker, Kubernetes, or systemd so that it keeps running between jobs</li>

  <li>[Create sessions with the CLI](https://infisical.com/docs/documentation/platform/agent-vault/sessions-cli.md): set up a machine identity, then run the agent from cron or systemd</li>

  <li>[Create sessions with the CLI](https://infisical.com/docs/documentation/platform/agent-vault/sessions-cli.md): set up a machine identity, then start the agent from the container's entrypoint</li>

  <li>[Create sessions with the CLI](https://infisical.com/docs/documentation/platform/agent-vault/sessions-cli.md): set up a machine identity, then start the agent in a GitHub Actions step</li>

  <li>[Create sessions with the API](https://infisical.com/docs/documentation/platform/agent-vault/sessions-api.md): set up a machine identity for the orchestrator, then create a session for each task and revoke it when the task ends</li>

  <li>[Start each agent with its session token](https://infisical.com/docs/documentation/platform/agent-vault/sessions-api.md#step-4-start-the-agent-with-the-session-token): install the Infisical CLI on each agent's host, and start the agent with `infisical agent-vault run --session-token`</li>

  <li>[Send your agent's requests through the proxy](https://infisical.com/docs/documentation/platform/agent-vault/guides/custom-agent.md#step-4-send-requests-through-the-proxy): set the proxy and the proxy's certificate in your agent's HTTP client</li>
</ol>

> [!NOTE]
>
> When the guide has you create a session, set **Expires** to **Never**. The assistant keeps running, so a session that expires would cut off its access to the APIs.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.