docs/documentation/platform/agent-proxy/quickstart.mdx
This tutorial takes you from an Infisical project to an agent making authenticated API calls through the Agent Proxy, with real credentials it never sees.
To follow along, you'll need:
17322 by default).gh CLI on the agent host, for the recommended verification in step 7. A curl fallback is provided, so this is not required.First, get a GitHub personal access token to broker:
GET /user, which any valid token can reach, so no permissions are needed here; later, grant only what your agent actually does.github_pat_… value. GitHub only shows it once.Then, in your Infisical project, create a folder for the agent (for example /coding-agent in the dev environment) and add a secret named GITHUB_PAT with that token as its value. It is a regular Infisical secret.
A proxied service maps a host to the secret the proxy applies. In the same folder, open the Add Secret dropdown and select Add Proxied Service, then work through the steps:
<Steps> <Step title="Pick the GitHub template"> The template fills everything in for you: the host `api.github.com` and a **Secret Substitution** rule that hands the agent a realistic `ghp_…` placeholder and swaps in the real token on the way out.
Here is how the pieces fit together. When your agent connects, it gets an environment variable `GITHUB_TOKEN` (the placeholder name the GitHub template uses) set to the fake `ghp_…` placeholder. The agent uses it like any GitHub token and sends `Authorization: Bearer <placeholder>`. As the request passes through the proxy, the placeholder is replaced with the real value of your `GITHUB_PAT` secret. The template scopes this swap to headers, since that is where GitHub expects the token; a substitution can also target the URL path, query, or body.
The proxy and the agent authenticate as two separate machine identities with opposite access. That split is the whole security model: the proxy can read your secrets, the agent never can.
<Note> The two templates have similar names but are for different identities: use **Agent Proxy Policies** for the proxy (this step) and **Agent Policies** for the agent (next step). Pick the one that matches the identity you are creating. </Note>The proxy identity reads the secrets.
<Steps> <Step title="Create the identity"> In your project, go to **Access Control → Machine Identities** and click **Add Machine Identity to Project → Create New**. Name it (for example `agent-proxy`), leave the **Role** as **No Access**, select the **Agent Proxy Policies** template under **Additional Privileges**, and create it.
<Note>
**Agent Proxy Policies** grants the proxy these permissions, project-wide:
- `Read Value` and `Describe Secret` on **Secrets**: fetch real secret values
- `Lease` on **Dynamic Secrets**: mint credentials for brokered [dynamic secrets](/documentation/platform/agent-proxy/proxied-services#using-dynamic-secrets)
- `Report Usage` on **Proxied Services**: report service usage back to Infisical
This template is the identity's entire access, so its project **Role** stays **No Access**. For a production deployment, grant these scoped to your services' environments and paths with a [custom role](/documentation/platform/access-controls/role-based-access-controls) or a conditional [additional privilege](/documentation/platform/access-controls/additional-privileges). See [Permissions](/documentation/platform/agent-proxy/security#permissions).
</Note>
Click **Add Client Secret**.
Save the **Client ID** and the **Client Secret**; you will pass both to the proxy in step 5.
The agent identity routes traffic but reads no secrets. It needs the Proxy permission and nothing else.
<Note>
**Agent Policies** grants the agent one permission, project-wide:
- `Proxy` on **Proxied Services**: route traffic and have credentials applied, with no secret read access
This template is the identity's entire access, so its project **Role** stays **No Access**. For a production deployment, grant it scoped to your services' environments and paths with a [custom role](/documentation/platform/access-controls/role-based-access-controls) or a conditional [additional privilege](/documentation/platform/access-controls/additional-privileges). See [Permissions](/documentation/platform/agent-proxy/security#permissions).
</Note>
Remember this host's address; the next step points INFISICAL_AGENT_PROXY_ADDRESS at it. For production deployment, see Deployment.
# Scope: your project, plus the environment and folder from step 1
export INFISICAL_PROJECT_ID=<project-id>
export INFISICAL_ENVIRONMENT=dev
export INFISICAL_SECRET_PATH=/coding-agent
# The agent proxy to route through (from step 5)
export INFISICAL_AGENT_PROXY_ADDRESS=<proxy-host>:17322
```
# Scope: your project, plus the environment and folder from step 1
export INFISICAL_PROJECT_ID=<project-id>
export INFISICAL_ENVIRONMENT=dev
export INFISICAL_SECRET_PATH=/coding-agent
# The agent proxy to route through (from step 5)
export INFISICAL_AGENT_PROXY_ADDRESS=<proxy-host>:17322
```
# Scope: your project, plus the environment and folder from step 1
export INFISICAL_PROJECT_ID=<project-id>
export INFISICAL_ENVIRONMENT=dev
export INFISICAL_SECRET_PATH=/coding-agent
# The agent proxy to route through (from step 5)
export INFISICAL_AGENT_PROXY_ADDRESS=<proxy-host>:17322
```
The agent starts and behaves exactly as if you had launched it directly; nothing about it looks different. In its environment it finds GITHUB_TOKEN, set by connect to the fake placeholder, and uses it like a normal token. Its traffic now routes through the proxy: on calls to api.github.com the placeholder is swapped for the real token, and everything else passes through untouched. The next step makes that visible.
Each method below makes the same GET /user call to api.github.com. The client sends only the ghp_… placeholder that connect put in the environment; as the request passes through the proxy, the placeholder is swapped for the real value of your GITHUB_PAT secret. GitHub returns your account profile even though the real token never reached the client. That is the whole point: real authenticated work without the caller ever holding the credential.
> Run `gh api user` and show me the output.
[GitHub's `gh` CLI](https://cli.github.com/) reads `GITHUB_TOKEN` from the environment on its own, so the agent needs no token wiring; it just runs the command and GitHub returns your profile. Requires `gh` on the host where the agent runs.
```bash
infisical secrets agent-proxy connect -- gh api user
```
`gh` reads `GITHUB_TOKEN` automatically, so there is nothing else to pass. Requires `gh` on the host where you run this.
```bash
infisical secrets agent-proxy connect -- \
sh -c 'curl -sS https://api.github.com/user -H "Authorization: Bearer $GITHUB_TOKEN"'
```