> ## 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.

# Create Agent Vault sessions with the CLI

> Create a new session for each agent run with the Infisical CLI and a machine identity.

The Infisical CLI can create a new [session](https://infisical.com/docs/documentation/platform/agent-vault/sessions) each time an agent starts. A short script authenticates as a [machine identity](https://infisical.com/docs/documentation/platform/identities/machine-identities.md), creates a session with an [access bundle](https://infisical.com/docs/documentation/platform/agent-vault/access-bundles.md), starts the agent with the session token, and revokes the session when the agent exits.

This is useful if your agent runs from cron, in a container, in CI, or as a long-running service.

> [!TIP]
>
> If your own code starts the agents, or creates sessions for agents that run on other machines, such as an orchestrator that gives each container its own session, you can [create sessions with the API](https://infisical.com/docs/documentation/platform/agent-vault/sessions-api.md) instead.

## Prerequisites

* An [access bundle](https://infisical.com/docs/documentation/platform/agent-vault/access-bundles.md) with a service for each API the agent calls
* A running [proxy](https://infisical.com/docs/documentation/platform/agent-vault/proxies.md) that the agent's machine can reach, in the same [Agent Vault project](https://infisical.com/docs/documentation/platform/agent-vault/projects.md) as the access bundle
* The [Infisical CLI](https://infisical.com/docs/cli/install.md) installed on the agent's machine
* An agent command that runs without anyone at the terminal, such as `claude -p "<prompt>"` for Claude Code
* The **Admin** role in the [Agent Vault project](https://infisical.com/docs/documentation/platform/agent-vault/access-control.md#product-membership), or an admin of the project who can complete [Step 1](#step-1-set-up-a-machine-identity) for you

## Step 1: Set up a machine identity

The CLI creates sessions as a machine identity, so that the agent's access doesn't depend on a person's account.

**Step 1**

In your Agent Vault project, go to **Access Control** > **Machine Identities** and select **Add Machine Identity**.

**Step 2**

On the **Create New** tab, enter a **Name**, choose **Member** in **Role**, then select **Create**. Infisical creates the machine identity with [Universal Auth](https://infisical.com/docs/documentation/platform/identities/universal-auth.md) and opens its page.

![The Add Machine Identity to Project panel on the Create New tab, with ci-runner as the name and Member as the role](https://mintlify.s3.us-west-1.amazonaws.com/infisical/images/platform/agent-vault/machine-identity-create.png)

> [!TIP]
>
> To use a machine identity that already exists in your organization, select the **Assign Existing** tab instead.

**Step 3**

On the machine identity's page, select **Universal Auth** under **Authentication**. Copy the **Client ID**, then select **Add Client Secret** and copy the client secret.

**Step 4**

Go to **Access Bundles** and open the access bundle the agent uses. Select **Options** > **Manage Access**. Under **No Access**, select **Grant Access** next to the machine identity.

> [!NOTE]
>
> We recommend creating a machine identity for each agent and granting it only the access bundle that agent uses.
>
> If you plan on using one machine identity to create sessions with different access bundles for different agents, you should [create sessions with the API](https://infisical.com/docs/documentation/platform/agent-vault/sessions-api.md) instead.

## Step 2: Start the agent

If the agent won't start without an API key, such as `ANTHROPIC_API_KEY` for Claude Code, set the key to a placeholder, such as `agent-vault`. The proxy replaces the placeholder with the real key from the service. If the service uses a [substitution](https://infisical.com/docs/documentation/platform/agent-vault/http-apis.md#substitutions), set the key to the service's placeholder instead.

On the agent's machine, set the machine identity's credentials, the ID of your Agent Vault project, and the proxy's address as environment variables. To get the project's ID, see [Find the project ID](https://infisical.com/docs/documentation/platform/agent-vault/projects.md#find-the-project-id).

```bash theme={"dark"}
export INFISICAL_UNIVERSAL_AUTH_CLIENT_ID=<client-id>
export INFISICAL_UNIVERSAL_AUTH_CLIENT_SECRET=<client-secret>
export INFISICAL_AGENT_VAULT_PROJECT_ID=<project-id>
export INFISICAL_AGENT_VAULT_PROXY_ADDRESS=<proxy-host>:17323
# If you self-host Infisical, also set the address of your instance
export INFISICAL_DOMAIN=<your-instance-url>
```

Then save this script as `run-agent.sh` and make it executable with `chmod +x run-agent.sh`:

```bash run-agent.sh theme={"dark"}
#!/bin/sh
INFISICAL_AGENT_VAULT_SESSION_TOKEN=$(infisical agent-vault sessions create --access-bundle <access-bundle-name> --ttl 2h) || exit 1
export INFISICAL_AGENT_VAULT_SESSION_TOKEN

infisical agent-vault run -- <agent-command>
status=$?

infisical agent-vault sessions revoke
exit $status
```

The script does three things:

1. [`infisical agent-vault sessions create`](https://infisical.com/docs/cli/reference#agent-vault-sessions-create) creates a session in the project and prints only the session token, which the script saves in `INFISICAL_AGENT_VAULT_SESSION_TOKEN`
2. [`infisical agent-vault run`](https://infisical.com/docs/cli/reference#agent-vault-run) starts the agent with the session in `INFISICAL_AGENT_VAULT_SESSION_TOKEN`, and the agent's requests go through the proxy
3. [`infisical agent-vault sessions revoke`](https://infisical.com/docs/cli/reference#agent-vault-sessions-revoke) ends the same session after the agent exits, and the script exits with the agent's exit code

Run `./run-agent.sh` to start the agent.

> [!TIP]
>
> `infisical agent-vault run --access-bundle <access-bundle-name> -- <agent-command>` creates the session and revokes it when the agent exits, in one command. It reads the project from the same environment variable.

### Choose how long each session lasts

Set `--ttl` a little longer than the longest run you expect:

* If a run takes longer than the `--ttl`, the agent loses access to the APIs partway through the run
* If the CLI can't revoke the session, such as when the machine shuts down mid-run, the session keeps working until the `--ttl` runs out (a session created without `--ttl` never expires)

### Pin the proxy's certificate

The CLI downloads the proxy's certificate at the start of each run. If the agent's machine reaches the proxy over a network you don't fully control, add `--ca-fingerprint` with the proxy's fingerprint to the `run` command in the script, so the CLI only starts the agent if the certificate matches:

```bash theme={"dark"}
infisical agent-vault run --ca-fingerprint <fingerprint> -- <agent-command>
```

Copy the fingerprint from the **Certificate Authority** column on the **Proxies** page of your Agent Vault project. If you [rotate the proxy's token](https://infisical.com/docs/documentation/platform/agent-vault/proxies.md#rotate-a-proxy’s-token), update the fingerprint.

## Step 3: Run the agent automatically

Run the script from [Step 2](#step-2-start-the-agent) wherever your agents start. The systemd and container examples run `infisical agent-vault run --access-bundle` instead, so the CLI revokes the session when the service or container stops:

> [tab] Schedule (cron)
>
> Store the environment variables in a file that only the job's user can read, such as `/etc/agent-vault/agent.env` with mode `0600`:
>
> ```bash theme={"dark"}
> export INFISICAL_UNIVERSAL_AUTH_CLIENT_ID=<client-id>
> export INFISICAL_UNIVERSAL_AUTH_CLIENT_SECRET=<client-secret>
> export INFISICAL_AGENT_VAULT_PROJECT_ID=<project-id>
> export INFISICAL_AGENT_VAULT_PROXY_ADDRESS=<proxy-host>:17323
> ```
>
> Then load the file in the crontab entry. This entry runs the agent every 30 minutes:
>
> ```bash theme={"dark"}
> */30 * * * * . /etc/agent-vault/agent.env && /usr/local/bin/run-agent.sh
> ```

> [tab] Service (systemd)
>
> For an agent that keeps running, such as a bot, a session has to last as long as the process. Instead of a session that never expires, restart the service on a schedule, so each restart gets a new session and revokes the old one.
>
> Store the variables in `/etc/agent-vault/agent.env` with mode `0600`, without the `export` keyword, then create `/etc/systemd/system/agent.service`:
>
> ```ini theme={"dark"}
> [Unit]
> Description=Agent through Infisical Agent Vault
> After=network-online.target
>
> [Service]
> EnvironmentFile=/etc/agent-vault/agent.env
> ExecStart=/usr/bin/infisical agent-vault run --access-bundle <access-bundle-name> --ttl 25h -- <agent-command>
> Restart=always
> RuntimeMaxSec=1d
>
> [Install]
> WantedBy=multi-user.target
> ```
>
> `RuntimeMaxSec=1d` restarts the service every day, and `--ttl 25h` gives each session an hour more than that. Start the service with `sudo systemctl enable --now agent`.

> [tab] Container
>
> Install the CLI in the agent's image and start the agent through `infisical agent-vault run`. For an image based on Debian or Ubuntu:
>
> ```dockerfile theme={"dark"}
> RUN apt-get update && apt-get install -y curl \
>   && curl -1sLf 'https://artifacts-cli.infisical.com/setup.deb.sh' | bash \
>   && apt-get install -y infisical
>
> ENTRYPOINT ["infisical", "agent-vault", "run", "--access-bundle", "<access-bundle-name>", "--ttl", "2h", "--"]
> CMD ["<agent-command>"]
> ```
>
> Pass the environment variables when you start the container, such as from a file:
>
> ```bash theme={"dark"}
> docker run --env-file agent.env <agent-image>
> ```
>
> In Docker, an `--env-file` lists each variable as `NAME=value`, without the `export` keyword. When Docker stops the container, the CLI passes the stop signal to the agent and revokes the session after the agent exits.

> [tab] CI (GitHub Actions)
>
> Store the client ID and client secret as [repository secrets](https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions), commit the script to the repository, then run it in a job step:
>
> ```yaml theme={"dark"}
> - name: Install the Infisical CLI
>   run: |
>     curl -1sLf 'https://artifacts-cli.infisical.com/setup.deb.sh' | sudo -E bash
>     sudo apt-get install -y infisical
>
> - name: Run the agent
>   env:
>     INFISICAL_UNIVERSAL_AUTH_CLIENT_ID: ${{ secrets.AGENT_VAULT_CLIENT_ID }}
>     INFISICAL_UNIVERSAL_AUTH_CLIENT_SECRET: ${{ secrets.AGENT_VAULT_CLIENT_SECRET }}
>     INFISICAL_AGENT_VAULT_PROJECT_ID: <project-id>
>     INFISICAL_AGENT_VAULT_PROXY_ADDRESS: <proxy-host>:17323
>   run: ./run-agent.sh
> ```
>
> The script exits with the agent's exit code, so the step fails if the agent fails.
>
> The runner has to reach the proxy. If the proxy is on a private network, run the job on a [self-hosted runner](https://docs.github.com/en/actions/hosting-your-own-runners) in that network.

To run agents on many machines, give every machine the same script or command and point them all at the same proxy. Each run gets its own session, so you can see and revoke each run separately on the **Sessions** page. You don't need a proxy for each machine, but the proxy has to be in the same Agent Vault project as the sessions.

## Step 4: Verify it works

After the agent runs, go to **Sessions** in your Agent Vault project and select **All Sessions**. Each run has its own session, with the machine identity's name in the **Identity** column. A session's **Status** is **Active** while the agent runs, and **Revoked** after the agent exits.

[View a session's logs](https://infisical.com/docs/documentation/platform/agent-vault/sessions#view-session-logs) to check which requests the agent made during that run.

> [!TIP]
>
> Your agent now runs on its own with a new session each time, and each session ends when the agent exits.

## Troubleshooting

> [accordion] The job hangs or fails before the agent starts
>
> If the output mentions logging in, the CLI didn't find the machine identity's credentials. Check that `INFISICAL_UNIVERSAL_AUTH_CLIENT_ID` and `INFISICAL_UNIVERSAL_AUTH_CLIENT_SECRET` are set in the job's environment. Cron starts jobs with an almost empty environment, so load the variables in the cron job, as the [cron example](#step-3-run-the-agent-automatically) shows.

> [accordion] The CLI stops because no Agent Vault project is set
>
> `infisical agent-vault sessions create` needs to know which Agent Vault project to create the session in. Set `INFISICAL_AGENT_VAULT_PROJECT_ID` to the [project's ID](https://infisical.com/docs/documentation/platform/agent-vault/projects.md#find-the-project-id) in the job's environment, or pass `--project-id <project-id>`. If neither is set, the CLI reads the project from `INFISICAL_PROJECT_ID`.

> [accordion] Creating the session fails after the CLI reads the project from INFISICAL\_PROJECT\_ID
>
> `INFISICAL_PROJECT_ID` may be set to the ID of a Secrets Management project. Set `INFISICAL_AGENT_VAULT_PROJECT_ID` to the ID of your Agent Vault project, which the CLI reads first.

> [accordion] The CLI fails with "the proxy address is required"
>
> Set `INFISICAL_AGENT_VAULT_PROXY_ADDRESS`, or pass `--proxy <proxy-host>:17323`.

> [accordion] The CLI fails with "No access bundle named ... is granted to you"
>
> The machine identity doesn't have a grant on the access bundle, the name in `--access-bundle` is wrong, or the access bundle is in a different Agent Vault project from the one the CLI uses. Check the name on the **Access Bundles** page of the project, and [grant the bundle](#step-1-set-up-a-machine-identity) to the machine identity.

> [accordion] Requests fail with "the session is no longer valid, or it belongs to a different Agent Vault project" as soon as the agent starts
>
> The proxy and the session are in different Agent Vault projects. A proxy only accepts sessions from its own project, so it refuses every request with a 403 and logs `agent-vault: refused, the session is no longer valid, or it belongs to a different Agent Vault project than this proxy`. Set `--proxy` or `INFISICAL_AGENT_VAULT_PROXY_ADDRESS` to the address of a proxy in the session's project, or [create a proxy](https://infisical.com/docs/documentation/platform/agent-vault/proxies.md#create-a-proxy-and-start-it) in that project.

> [accordion] The agent loses access to APIs partway through a run
>
> If the agent's requests start failing with a 403 from the proxy, such as `CONNECT tunnel failed, response 403`, the session expired before the agent finished. Set a longer `--ttl`.

> [accordion] Requests to a service fail with "needs your own credential or sign-in" or "needs your personal values"
>
> The service needs each member's own credential or sign-in, and whoever the session belongs to hasn't set theirs up yet. For a session a machine identity started [on behalf of a user](https://infisical.com/docs/documentation/platform/agent-vault/sessions-on-behalf-of-users.md), that's the user. A user sets it up under **Access Bundles** in the Agent Vault project: select the bundle named in the message, then [set up the personal values](https://infisical.com/docs/documentation/platform/agent-vault/access-bundles.md#set-up-your-personal-values). A machine identity sets typed values with [the set personal values endpoint](https://infisical.com/docs/api-reference/endpoints/agent-vault-services/set-personal-values.md), but it can't sign in to an OAuth service, so start the session [on behalf of a user](https://infisical.com/docs/documentation/platform/agent-vault/sessions-on-behalf-of-users.md) who has. Once it's saved, the proxy picks it up within one [poll interval](https://infisical.com/docs/documentation/platform/agent-vault/proxies.md#poll-interval).

> [accordion] A session stays Active after the agent stopped
>
> The CLI couldn't revoke the session, for example because the machine shut down or the process was killed. [Revoke the session](https://infisical.com/docs/documentation/platform/agent-vault/sessions#revoke-a-session) on the **Sessions** page, or let it expire at the end of its `--ttl`.

## Next steps

> [card] [Create sessions with the API](https://infisical.com/docs/documentation/platform/agent-vault/sessions-api.md)
>
> Create a session for each agent run from your own code.

> [card] [CLI reference](https://infisical.com/docs/cli/reference.md#agent-vault-sessions-create)
>
> Every flag of `infisical agent-vault sessions create` and `infisical agent-vault run`.


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