Create Agent Vault sessions with the CLI

The Infisical CLI can create a new session each time an agent starts. The CLI authenticates as a machine identity, creates a session with an access bundle, starts the agent, 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.

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

Prerequisites

An access bundle with a service for each API the agent calls
A running proxy that the agent’s machine can reach
The Infisical CLI 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 Agent Vault, or an Agent Vault admin who can complete Step 1 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.

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

On the Create New tab, enter a Name, choose Member in Role, then select Create. Infisical creates the machine identity with Universal Auth and opens its page.

To use a machine identity that already exists in your organization, select the Assign Existing tab instead.

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.

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

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 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, set the key to the service’s placeholder instead. On the agent’s machine, set the machine identity’s credentials and the proxy’s address as environment variables, then start the agent with infisical agent-vault run:

export INFISICAL_UNIVERSAL_AUTH_CLIENT_ID=<client-id>
export INFISICAL_UNIVERSAL_AUTH_CLIENT_SECRET=<client-secret>
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>

infisical agent-vault run --access-bundle <access-bundle-name> --ttl 2h -- <agent-command>

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 (seven days if you leave out --ttl)

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 command, so the CLI only starts the agent if the certificate matches:

infisical agent-vault run --access-bundle <access-bundle-name> --ttl 2h --ca-fingerprint <fingerprint> -- <agent-command>

Copy the fingerprint from the Certificate Authority column on the Proxies page. If you re-enroll the proxy, update the fingerprint.

Step 3: Run the agent automatically

Put the command from Step 2 wherever your agents start:

Schedule (cron)
Service (systemd)
Container
CI (GitHub Actions)

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:

export INFISICAL_UNIVERSAL_AUTH_CLIENT_ID=<client-id>
export INFISICAL_UNIVERSAL_AUTH_CLIENT_SECRET=<client-secret>
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:

*/30 * * * * . /etc/agent-vault/agent.env && infisical agent-vault run --access-bundle <access-bundle-name> --ttl 1h -- <agent-command>

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:

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

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:

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:

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.

Store the client ID and client secret as repository secrets, then start the agent in a job step:

- 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_PROXY_ADDRESS: <proxy-host>:17323
  run: infisical agent-vault run --access-bundle <access-bundle-name> --ttl 1h -- <agent-command>

The CLI 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 in that network.

To run agents on many machines, give every machine the same 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.

Step 4: Verify it works

After the agent runs, go to Sessions in Agent Vault 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. If you’ve set up session logs, view a session’s logs to check which requests the agent made during that run.

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

Troubleshooting

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 and started an interactive login. 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 shows.

The CLI fails with "the proxy address is required"

Set INFISICAL_AGENT_VAULT_PROXY_ADDRESS, or pass --proxy <proxy-host>:17323.

The CLI fails with "No access bundle named ... is granted to you"

The machine identity doesn’t have a grant on the access bundle, or the name in --access-bundle is wrong. Check the name on the Access Bundles page, and grant the bundle to the machine identity.

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.

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 with SIGKILL. Revoke the session on the Sessions page, or let it expire at the end of its --ttl.

Next steps

Create sessions with the API

Create a session for each agent run from your own code.

CLI reference

Every flag of infisical agent-vault run.

Get started

Agent guides

Concepts

Create Agent Vault sessions with the CLI

Prerequisites

Step 1: Set up a machine identity

Step 2: Start the agent

Choose how long each session lasts

Pin the proxy’s certificate

Step 3: Run the agent automatically

Step 4: Verify it works

Troubleshooting

Next steps

Create sessions with the API

CLI reference

​Prerequisites

​Step 1: Set up a machine identity

​Step 2: Start the agent

​Choose how long each session lasts

​Pin the proxy’s certificate

​Step 3: Run the agent automatically

​Step 4: Verify it works

​Troubleshooting

​Next steps

Create sessions with the API

CLI reference

Prerequisites

Step 1: Set up a machine identity

Step 2: Start the agent

Choose how long each session lasts

Pin the proxy’s certificate

Step 3: Run the agent automatically

Step 4: Verify it works

Troubleshooting

Next steps