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 each time an agent starts. A short script authenticates as a machine identity, creates a session with an access bundle, 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.

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, in the same Agent Vault project as the access bundle
• 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 the Agent Vault project, or an admin of the project 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.

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

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

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.

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.

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

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:

run-agent.sh

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

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:

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, update the fingerprint.

​

Step 3: Run the agent automatically

Run the script from Step 2 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:

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:

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:

*/30 * * * * . /etc/agent-vault/agent.env && /usr/local/bin/run-agent.sh

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:

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

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:

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.

CI (GitHub Actions)

Store the client ID and client secret as repository secrets, commit the script to the repository, then run it 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_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 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 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. 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 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 in the job’s environment, or pass --project-id <project-id>. If neither is set, the CLI reads the project from INFISICAL_PROJECT_ID.

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.

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, 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 to the machine identity.

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 in that project.

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.

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, 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. A machine identity sets typed values with the set personal values endpoint, but it can’t sign in to an OAuth service, so start the session on behalf of a user who has. Once it’s saved, the proxy picks it up within one poll interval.

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 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 sessions create and infisical agent-vault run.