Local proxy quickstart

With a local proxy, everything happens on the computer you are already working on. The proxy starts alongside your agent, hands it placeholder credentials, swaps in the real ones as its requests leave, and stops when the agent exits. There is nothing to deploy and no machine identity to create: the proxy brokers as your logged-in user, against secrets you can already read.

Because the proxy and the agent share a machine, an OS sandbox is what keeps them apart. The agent cannot read your keyring or your credential files, and its only route to the network is the proxy.

  +- your computer ------------------------+
  |  +- sandbox ----+    +--------------+  |      +----------------+
  |  |  your agent  |--->|    proxy     |  |----->| api.github.com |
  |  +--------------+    +--------------+  |      +----------------+
  +----------------------------------------+

By the end of this page an agent on your machine makes authenticated GitHub calls with a token it never sees.

Before you begin

• Set up credentials finished, so you have a GITHUB_PAT secret and a github proxied service in /coding-agent.
• The Infisical CLI installed.
• macOS, or Linux with bubblewrap installed.
• Optional: GitHub's gh CLI, used for the check at the end. A curl fallback is provided, so this is not required.

The sandbox comes from the operating system, so what you install depends on which one you are on:

<Tabs>
  <Tab title="Debian / Ubuntu">
    ```bash
    sudo apt install bubblewrap
    ```
  </Tab>
  <Tab title="Fedora / RHEL">
    ```bash
    sudo dnf install bubblewrap
    ```
  </Tab>
  <Tab title="Arch">
    ```bash
    sudo pacman -S bubblewrap
    ```
  </Tab>
  <Tab title="Alpine">
    ```bash
    apk add bubblewrap
    ```
  </Tab>
</Tabs>

On a distribution not listed here, look for `bubblewrap` in your package manager.

1. Log in

infisical login

run brokers as you, so this is the only credential involved.

2. Launch your agent

Everything after -- is your agent's own command. Run it from the directory you want the agent to work in:

infisical secrets agent-proxy run --projectId=<project-id> --env=dev --path=/coding-agent -- claude

This one command starts the proxy and your agent together, and shuts the proxy down when the agent exits. The agent behaves exactly as if you had launched it directly. In its environment it finds GITHUB_TOKEN, set to the fake ghp_… placeholder, and uses it like a normal token. Calls to api.github.com get the real token swapped in as they pass through; everything else goes out untouched. Meanwhile the agent is sandboxed: it cannot read your keyring, your ~/.aws or ~/.ssh, or your Infisical token.

3. Verify it works

Each check below makes the same GET /user call to api.github.com, and the client only ever sends the fake ghp_… placeholder. As the request passes through the proxy the placeholder is swapped for the real value of your GITHUB_PAT, so 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 runs the command and GitHub answers with your profile. Requires `gh` on your machine.

```bash
infisical secrets agent-proxy run --projectId=<project-id> --env=dev --path=/coding-agent -- gh api user
```

`gh` reads `GITHUB_TOKEN` automatically, so there is nothing else to pass.

```bash
infisical secrets agent-proxy run --projectId=<project-id> --env=dev --path=/coding-agent -- \
  sh -c 'curl -sS https://api.github.com/user -H "Authorization: Bearer $GITHUB_TOKEN"'
```

For more depth, the Local Agent Proxy reference covers what the sandbox allows and denies, how certificates work, and every flag run takes.