Set environment variables on a custom agent
A custom agent can read settings from its environment, for example which model a connector calls. Jaah sets the variables you list on the agent's process each time a task runs it, so you change a setting without a new commit. Variables are for plain settings only: keys and passwords belong in a credential the agent fetches at run time.
Who can do this: anyone with permission to edit agents. Without it the agent's page says You can view this agent but not edit it. An agent installed from the registry has no Environment tab, and a catalog connector is changed only on the Catalog tab.
-
In the sidebar, select Settings, then Agents under Customize, then the Custom agents tab.
-
Select the agent's name. Its page opens beside the list on the Agent tab.
-
Select the Environment tab. It lists each variable already set as a Name and a Value. Hover Environment to read what the variables are for and which names are refused.

-
Select Add variable and fill in the new row:
- Name: letters, digits and
_, not starting with a digit, such asJAAH_CODEX_MODEL. Each name can appear once; a repeat reads Already set above. - Value: the text the agent receives, exactly as you type it.
- Name: letters, digits and
-
To change a variable, edit its Value. To remove one, select ✕ at the end of its row.
-
Select Save. The page reads Fetching the repository and checking its manifest… for a few seconds, then Saved and the agent's name. Cancel drops your changes.
-
If Jaah refuses the save, the reasons are listed above the buttons. The usual ones:
- … looks like a secret — use a credential: the value looks like a key or password. Remove it and give the agent a credential instead.
- … is named like a secret: the name ends
_TOKEN,_API_KEY,_SECRETorPASSWORD, in any case. Store the value as a credential and have the agent read it at run time. A name like this with an empty value is saved. - … is set by the agent supervisor and cannot be overridden: Jaah sets that variable itself. The
refused names are
JAAH_WORKTREE,PYTHONPATHand any name startingJAAH_AGENT_. Other names startingJAAH_are allowed. - …'s value must be under 4096 characters, with no NUL: shorten the value to at most 4,096 characters, and take out any null character pasted into it.
- At most 50 environment variables: remove the ones the agent no longer reads.
-
Start a task with the agent. Tasks that start after the save get the new values; a task already running keeps the ones it started with.
Related
- Change or remove a custom agent — change its ref or folder, refresh, disable or delete it.
- Agent SDK reference — the variables Jaah sets on every agent.
- Build an agent with the SDK — write an agent and register it.
- Custom agent page — every field on the agent's page.