Infisical is the open-source platform for securing secrets, certificates, access, and AI Agents.
TypeScript acmeagentsai-agentscertificate-managementdevsecopsenvironment-variableskubernetesopen-sourcepampkipostgresprivate-caprivileged-access-managementsecret-managementsecret-managersecretssecrets-managementsecuritysecurity-toolsvault
import AgentIntroNote from "/snippets/agent-vault/slots/AgentIntroNote.mdx";
import AgentPrereqLine from "/snippets/agent-vault/slots/AgentPrereqLine.mdx";
import AgentLaunchCommand from "/snippets/agent-vault/slots/AgentLaunchCommand.mdx";
import ServiceVerifyIntro from "/snippets/agent-vault/slots/ServiceVerifyIntro.mdx";
import ServiceVerifyProse from "/snippets/agent-vault/slots/ServiceVerifyProse.mdx";
import ServiceVerifyCurl from "/snippets/agent-vault/slots/ServiceVerifyCurl.mdx";
import ServiceCheckCallout from "/snippets/agent-vault/slots/ServiceCheckCallout.mdx";
import SeparateMachinesNote from "/snippets/agent-vault/SeparateMachinesNote.mdx";
This guide walks you through using Agent Vault to launch an agent that calls HTTP APIs and MCP servers without having access to their credentials.
<AgentIntroNote />
## Prerequisites
<ul>
<li>An Infisical organization where you're an [Agent Vault admin](/documentation/platform/agent-vault/access-control#product-membership)</li>
<li>An [access bundle](/documentation/platform/agent-vault/access-bundles) with a service for each API the agent calls (see the [quickstart](/documentation/platform/agent-vault/quickstart))</li>
<li>The [Infisical CLI](/cli/install) installed on the host that will run the Agent Vault proxy and on the host that will run the agent</li>
<AgentPrereqLine />
</ul>
<SeparateMachinesNote />
## Step 1: Set up in Infisical
### Create a proxy
First, create a [proxy](/documentation/platform/agent-vault/proxies) to intercept API calls from your agent.
<Steps>
<Step>
Go to **Proxies** and select **Create Proxy**.
</Step>
<Step>
Give the proxy a **Name**, then select **Create**. The **Proxy Token** dialog shows the proxy token once, with a command to start the proxy. Copy the command from the **CLI** tab for the next step.
</Step>
<Step>
On the host that will act as the proxy, run the command from the previous step.
```bash
INFISICAL_AGENT_VAULT_PROXY_TOKEN=<proxy-token> \
infisical agent-vault proxy \
--domain <your-instance-url>
```
The proxy starts listening on port `17323`. Leave it running and note this host's address. You'll need the address when you launch your agent.
</Step>
</Steps>
<Note>
This runs the proxy in your current terminal, so the proxy stops when the terminal closes. For a persistent setup, use the **Docker** command or the **Kubernetes** manifest from the **Proxy Token** dialog, or [run the proxy with systemd](/documentation/platform/agent-vault/proxies#create-a-proxy-and-start-it).
Check out the [proxies documentation](/documentation/platform/agent-vault/proxies) for more information.
</Note>
### Create a session
Next, create a [session](/documentation/platform/agent-vault/sessions) with your access bundle attached.
<Steps>
<Step>
Go to **Sessions** and select **Create Session**.
</Step>
<Step>
Pick the **Access Bundle** the agent should use, set a duration under **Expires**, then select **Create Session**.
<Frame>
<img src="/images/platform/agent-vault/session-create.png" alt="The Create Session dialog with code-review picked and a seven day expiry" />
</Frame>
</Step>
<Step>
This creates the session and gives you a command to run your agent with it. Copy the command for the next step.
<Frame>
<img src="/images/platform/agent-vault/session-created.png" alt="The Session Created dialog showing the infisical agent-vault run command with the session token" />
</Frame>
</Step>
</Steps>
## Step 2: Launch your agent
On the host where the agent runs, paste the command you copied in the previous step. Replace `<proxy-host>` with your host's actual domain or IP address, and `<agent-command>` with your agent's own command.
<AgentLaunchCommand />
<Tip>
Instead of passing `--session-token` and `--proxy`, you can set the [`INFISICAL_AGENT_VAULT_SESSION_TOKEN` and `INFISICAL_AGENT_VAULT_PROXY_ADDRESS` environment variables](/cli/reference#agent-vault-run).
</Tip>
The CLI adds the proxy's certificate authority to the agent process' trusted CAs and starts the agent with its HTTP traffic routed through the proxy. Any calls to services in your access bundle leave the proxy with the real credential attached, while calls to any other host go out normally.
<Note>
On macOS, you'll need to enter your user password when running your agent for the first time. This is because macOS needs your approval to add the proxy's certificate to your keychain.
</Note>
## Step 3: Verify it works
<ServiceVerifyIntro />
<Tabs>
<Tab title="With your agent">
In your running agent's session, ask it to make the call. For example:
<ServiceVerifyProse />
</Tab>
<Tab title="With `curl`">
Any HTTP client works the same way. Run it through the proxy in place of your agent's command:
<ServiceVerifyCurl />
The proxy logs the request as `brokered`.
</Tab>
</Tabs>
<ServiceCheckCallout />
## Troubleshooting
<AccordionGroup>
<Accordion title="Authentication error from the upstream API">
The credential wasn't applied. Open your access bundle and confirm a service covers the host you called. If one does, the stored token is likely wrong.
</Accordion>
<Accordion title="407 from the proxy">
The session token was missing from the request. Confirm you passed `--session-token`, or that the token appears as the userinfo in your `HTTPS_PROXY` URL (like `http://x-agent-vault:<session-token>@<proxy-address>`).
</Accordion>
<Accordion title="403 from the proxy">
This could be for a few reasons:
- The session was revoked or has expired (check the **Sessions** page in Infisical, and create a new one if needed)
- Under the proxy's [strict traffic policy](/documentation/platform/agent-vault/proxies#traffic-policy), no service in the bundle covers the host you called (add a service that does, or use a pass-through service)
- The service covers the host, but doesn't allow the request's method or path (check the service's [methods and paths](/documentation/platform/agent-vault/http-apis#methods-and-paths))
</Accordion>
</AccordionGroup>
## Next steps
<CardGroup cols={2}>
<Card title="Create sessions with the CLI" icon="calendar-clock" href="/documentation/platform/agent-vault/sessions-cli">
Run your agent from cron, a container, or CI, with a new session for each run.
</Card>
<Card title="Create sessions with the API" icon="calendar-clock" href="/documentation/platform/agent-vault/sessions-api">
Create sessions from code every time you start your agent.
</Card>
<Card title="Skills" icon="book-open-text" href="/documentation/platform/agent-vault/skills">
Give your agent your team's instructions each time it starts.
</Card>
</CardGroup>