> ## 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. ## Your setup Before running an agent, you set up two things: > [!NOTE] > > One proxy stays running and handles the requests from every agent and every job in its Agent Vault project, so you don't need a separate proxy for each job or each host. If you have more than one project, each project needs its own proxy. > [!NOTE] > > One proxy stays running and handles the requests from every agent in its Agent Vault project, so you don't need a separate proxy for each task. > [!NOTE] > > Each agent run starts its own proxy beside the agent. Every proxy starts from the same proxy token, so you create the proxy in your Agent Vault project once. 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) and choose when it expires. If the agent keeps running, such as a chat assistant, set the session to never expire. 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](https://infisical.com/docs/documentation/platform/agent-vault/how-it-works.md#orchestrators) 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. If the session never expires, revoking the session is what stops the agent 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. Cursor's worker controller runs your spawn hook, which starts a worker pod with the session token. The worker sends the agent's commands through the proxy, while the worker itself connects to Cursor directly. 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. > [!TIP] > > To keep the machine identity's credentials off the agent's host, choose **A service that starts agents for tasks** instead, where the orchestrator gives the agent only the session token. The orchestrator starts the agent on a different host and passes it only the session token. The orchestrator creates a new container for the task, starts the agent in it, and passes it only the session token. The orchestrator creates a new pod for the task, starts the agent in it, and passes it only the session token. The orchestrator creates a new sandbox for the task, starts the agent in it, and passes it only the session token. The orchestrator creates a new E2B sandbox for the task, gives E2B the session token as the proxy's password, and starts the agent in the sandbox. E2B holds the token on its servers, so the agent can't read it and doesn't need `infisical agent-vault run`. The orchestrator stays out of the agent's environment because the machine identity it uses can create sessions for every access bundle it's granted. If an agent read those credentials, it 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 ""`. 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 ""`. 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 ""`. 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 ""`. > [!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 --message "" --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. The agent calls an API the same way it always does, but the request is intercepted by the proxy.
  • The agents' containers can't read the proxy token
  • 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
> [!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. > [!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. > [!NOTE] > > The proxy runs outside the agent's environment, and the agent's network only reaches the proxy. The agent can't read the proxy token or connect to an API without going through the proxy. > [!NOTE] > > E2B sends the sandbox's connections to the proxy from its own servers, so the proxy runs on a public machine with its SOCKS5 port turned on. Nothing in the sandbox is set up to use the proxy, and the agent can't send traffic that skips it. > [!NOTE] > > The proxy runs in its own namespace, and workers can't read the proxy token. Each worker needs a direct connection to Cursor, so the agent's commands can still reach other public hosts unless you [limit where workers connect](https://infisical.com/docs/documentation/platform/agent-vault/guides/cursor.md#workers’-outgoing-connections). 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/http-apis.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. Cursor doesn't report when a worker exits, so the session lasts until its `ttl` runs out; [keep the `ttl` as short as your runs allow](https://infisical.com/docs/documentation/platform/agent-vault/guides/cursor#sessions-that-outlive-their-workers). 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). The orchestrator also deletes the agent's environment, so nothing from one task carries over to the next. ## Build your setup Follow these pages in order:
  1. [Quickstart](https://infisical.com/docs/documentation/platform/agent-vault/quickstart.md): create an access bundle with a service for each API the agent calls, then follow the guide for where your agent runs
  2. [Quickstart](https://infisical.com/docs/documentation/platform/agent-vault/quickstart.md): create an access bundle with a service for each key the agent uses
  3. [Agent Vault with Claude Code](https://infisical.com/docs/documentation/platform/agent-vault/guides/claude-code): create a proxy, create a session, and start Claude Code with the session token
  4. [Agent Vault with Codex](https://infisical.com/docs/documentation/platform/agent-vault/guides/codex): create a proxy, create a session, and start Codex with the session token
  5. [Agent Vault with OpenCode](https://infisical.com/docs/documentation/platform/agent-vault/guides/opencode): create a proxy, create a session, and start OpenCode with the session token
  6. [Agent Vault with Hermes Agent](https://infisical.com/docs/documentation/platform/agent-vault/guides/hermes) to start Hermes in your terminal, or [Agent Vault with the Hermes gateway](https://infisical.com/docs/documentation/platform/agent-vault/guides/hermes-gateway) to keep Hermes running and answering messages: create a proxy, create a session, and start Hermes with the session token
  7. [Agent Vault with OpenClaw](https://infisical.com/docs/documentation/platform/agent-vault/guides/openclaw) to start OpenClaw in your terminal, or [Agent Vault with the OpenClaw gateway](https://infisical.com/docs/documentation/platform/agent-vault/guides/openclaw-gateway) to keep OpenClaw running and answering messages: create a proxy, create a session, and start OpenClaw with the session token
  8. [Connect your own agent](https://infisical.com/docs/documentation/platform/agent-vault/guides/custom-agent): create a proxy, create a session, and send your agent's requests through the proxy
  9. [Quickstart](https://infisical.com/docs/documentation/platform/agent-vault/quickstart.md): create an access bundle with a service for each external system the agent uses
  10. [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
  11. [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 tasks
  12. [Run agents in Docker containers with Agent Vault](https://infisical.com/docs/documentation/platform/agent-vault/guides/docker.md): create a session for each task, then start the agent in its own container with a proxy beside it
  13. [Run agents on Kubernetes with Agent Vault](https://infisical.com/docs/documentation/platform/agent-vault/guides/kubernetes): choose an isolation level for agent pods
  14. [Set up Agent Vault on Kubernetes](https://infisical.com/docs/documentation/platform/agent-vault/guides/kubernetes-setup.md): deploy the proxy in its own namespace, limit agent pods to it, and start each agent with its own session
  15. [Run agents in Modal sandboxes with Agent Vault](https://infisical.com/docs/documentation/platform/agent-vault/guides/modal.md): create a session for each task, then start the agent in its own sandbox with a proxy beside it
  16. [Run agents in Daytona sandboxes with Agent Vault](https://infisical.com/docs/documentation/platform/agent-vault/guides/daytona.md): create a session for each task, then start the agent in its own sandbox with a proxy beside it
  17. [Run agents in E2B sandboxes with Agent Vault](https://infisical.com/docs/documentation/platform/agent-vault/guides/e2b.md): run one proxy on a public machine with its SOCKS5 port turned on, then create a session for each task and give its token to E2B as the proxy's password
  18. [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
  19. [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
  20. [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
  21. [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
  22. [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`
  23. [Send your agent's requests through the proxy](https://infisical.com/docs/documentation/platform/agent-vault/guides/custom-agent#step-4-send-requests-through-the-proxy): set the proxy and the proxy's certificate in your agent's HTTP client
  24. [Run Cursor Cloud Agents on Kubernetes with Agent Vault](https://infisical.com/docs/documentation/platform/agent-vault/guides/cursor.md): deploy the proxy, then add a spawn hook that creates a session for each run and starts its worker with the session token
> [!NOTE] > > If the agent keeps running, such as a chat assistant, set **Expires** to **Never** when the guide has you create a session. If the session expires, the agent loses access to the APIs. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.