Skip to main content
A session gives an agent access to services in an Agent Vault project until the session expires or someone revokes it. You can create a session in the Infisical dashboard, with the Infisical CLI, through the API, or with the Python or Node.js SDK. Each one returns a session token that the agent uses to authenticate to the proxy.
The way you create sessions depends on where you start your agents.

Prerequisites

  • An access bundle with a service for each API the agent calls, and a grant on the bundle for whoever creates the session (admins of the project can use any of its bundles)
  • A running proxy in the same project as the access bundle, which the agent’s machine can reach
  • The ID of your Agent Vault project, if you create the session with the CLI, the API, or an SDK (see Find the project ID)
  • The Infisical CLI on the agent’s machine, if you start the agent with the CLI
  • To create sessions as a machine identity, the Admin role in the Agent Vault project to set up the machine identity, or an admin of the project who can set it up for you

Create the session

If a scheduled job, CI, or your own code creates sessions, it creates them as a machine identity, so the sessions don’t depend on a person’s account. Every tab except Dashboard includes the steps to set up the machine identity.
1
In your Agent Vault project, go to Sessions and select Create Session.
2
Select Your Own Sandbox, then select the Create Now tab.
3
In Access Bundle, select the bundle the agent should use. In Services, select any other services the agent should reach. In Skills, select any skills from the project that the agent should get. You can pick a bundle, services, skills, or any mix of them. Optionally, enter a Label that says what the session is for. Set a duration under Expires, then select Create Session.
The Create Now tab of the Your Own Sandbox dialog, with the on-call access bundle, the vercel service and the triage-notes skill picked, Incident bot as the label, and a seven day expiry
4
Copy the command in the dialog. The dialog shows the session token only once.
The Session Created dialog showing the infisical agent-vault run command with the session token, which is shown once
Run the copied command on the agent’s machine, or give it to the person who starts the agent. The agent’s machine needs the Infisical CLI, but not an Infisical login. To start the agent another way, see Start the agent.

Duration

The duration sets when the session expires. Set a duration of at least one minute, such as 30m, 8h, or 7d, or set never for a session that lasts until someone revokes it. If you leave out the duration, the session lasts:
  • 7d if you create it through the API or an SDK
  • 1h if you create it on behalf of a user
  • never if you create it with the CLI, so set a duration with --ttl unless you always revoke the session
Pick the duration based on how long the agent runs:

Start the agent

If you created the session with infisical agent-vault run --access-bundle, the agent is already running. Otherwise, pass the session token to the agent:
Start the agent with infisical agent-vault run, and pass the session token and the proxy’s address:
The CLI doesn’t revoke a session if you pass it the session’s token, so revoke the session yourself when the agent finishes, for example with infisical agent-vault sessions revoke.

Create a session for each run automatically

To give an agent a new session every time it runs, start the agent as a machine identity with the run-agent.sh script from the CLI tab. 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. Pick the tab for the place that starts your agents:
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:
Then load the file in the crontab entry. This entry runs the agent every 30 minutes:
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. To run agents in a sandbox, follow the guide for Modal, Daytona, or E2B.

Verify the session works

In your Agent Vault project, go to Sessions. If you’re an admin of the project, select All Sessions to see sessions that other users and machine identities created. Find the session by its label. Its Status is Active until it expires or someone revokes it. View the session’s logs to check which requests the agent made. If the proxy attached a credential to a request, the request’s outcome is Brokered.

Troubleshooting

The user or machine identity doesn’t have a grant on the access bundle, the name you sent is wrong, or the access bundle is in a different project from the one you sent. Check the name on the project’s Access Bundles page, and grant the bundle to whoever creates the session.
No access bundle granted to whoever creates the session holds the service, or no service in the project has that name. Check the name on the project’s Services page, and grant an access bundle that holds the service to whoever creates the session.
Two of the session’s services have the same name. This happens if you list a service twice, or if you list a service from the project and an inline service with the same name. Remove one of the two, or give the inline service a different name.
No access bundle granted to whoever creates the session holds the skill, or no skill in the project has that name. Check the name on the project’s Skills page, and grant an access bundle that holds the skill to whoever creates the session.
Two of the session’s skills have the same name. This happens if you list a skill twice, or if you list a skill from the project and send a skill whose SKILL.md has the same name. Remove one of the two, or rename the skill you send.
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 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.
INFISICAL_PROJECT_ID might hold 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.
Set INFISICAL_AGENT_VAULT_PROXY_ADDRESS, or pass --proxy <proxy-host>:17323.
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. Point the agent at a proxy in the session’s project, or create a proxy in that project.
The machine identity’s access token expired. Log in again to get a new access token. Sessions you already created keep working, because a session doesn’t depend on the access token that created it.
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 duration.
The service needs each member’s own credential or sign-in, and the session’s owner hasn’t set theirs up yet. If a machine identity created the session on behalf of a user, the owner is that user.
  • A user sets up their values on the Services page of the Agent Vault project, as described in set up your personal values
  • A machine identity sets its values with the Set personal values endpoint, but it can’t sign in to an OAuth service, so create the session on behalf of a user who has signed in
The proxy picks up the new values within one poll interval.

Next steps

Revoke a session

End a session before it expires so its agent stops getting credentials.

Session logs

Keep an encrypted record of every request, statement, and command an AI agent makes, stored by Infisical or in your own Amazon S3 bucket.