Every agent and every factory has its own set of environment variables — lines of the form KEY=value passed to the application at launch. Service addresses, access keys and connection parameters live there. While you have few agents and factories, you can copy those lines by hand. When there are dozens, the same set has to be repeated manually many times — and it is easy to make a mistake or forget to update one of them.
Environments is a library of named sets of such variables. A set is created once, then uploaded to the agents and factories you choose. Change a value in one place — send it to the agents that need it, instead of walking them one by one.
What an environment set is
A set is a name and a list of KEY=value lines. The rows go by variable name: both in the set editor and after an import, the list reads alphabetically rather than in the order it was typed. The set is stored in the same form the environments of factories and agents live in, so uploaded values behave exactly like the ones entered by hand on the “Environment” tab.
- Values are encrypted. The list and the view show only the key names and their count — the values stay hidden. The full text appears only on explicit expansion, and only in the editing window. That way secrets never flash across the screen and never reach the wrong hands;
- The name is unique. Two sets with the same name cannot exist: saving is rejected with a clear message;
- Empty keys are dropped, while empty values are kept — that is how passing environments to agents works. A line like
PASSWORD=sometimes has to stay there on purpose.
The “Environments” page
The “Environments” page opens as its own item in the sidebar. It shows a table of sets: the name and the number of variables in each. A row has three actions:
- “Upload” — send the set to the chosen agents or factories;
- “Edit” — open the set, fix the lines, expand or hide the values;
- “Delete” — remove the set from the library (with a confirmation).
The same page has a “New environment” button that creates an empty set, and “Import”, which creates a new set straight from another source’s variables. When there are no sets yet, the page offers to create the first one.
Deleting is worth understanding correctly: it removes only the set itself from the library. Nothing changes on any factory or on any agent — the values uploaded some time ago stay where they are. No record of where a set was uploaded is kept, same as in the similar libraries (skills and models, for example).
Importing from a factory or an agent
To avoid typing variables from scratch, you can take them from an existing record: pick the source — the factory’s shared environment or the agent’s extra environment — look at its variables (values hidden until expanded), tick the ones you need and import. The “Import” button on the page does the same, only into a new set.
On import, variables merge by key: when the set already has that key, its value is replaced by the imported one; new keys are appended to the end, and the set’s other variables stay. The import reads already saved values, so it works whether or not the source factory or agent is currently reachable.
Example: the set has B=old and C=3, and A=1 and B=2 are imported from an agent. The result is A=1, B=2, C=3 — the imported value won on the shared key, and the rest stayed untouched.
Uploading to agents
Uploading to the chosen agents adds the set’s variables to their extra environment. The merge goes by key: the set’s value wins, and the agent’s other variables stay. It is strictly an addition, not a replacement: a set never erases what it does not contain. Product records (the ready-made apps from the catalog) are not among the recipients.
What happens next depends on the agent’s state, and every row reports its own outcome separately:
- a running agent whose values really changed is recreated without pulling the image — faster than an ordinary update, and the new values take effect at once. The report row says the recreation has started;
- a stopped agent simply receives the updated environment, and the values apply on the next start or recreate;
- when nothing changed, nothing is written and nothing is recreated — the row says the variables are already in place. Re-uploading the same set is safe.
An agent being unreachable does not block the upload: its saved environment still updates, and the values are picked up on the next launch. And when one row fails for some reason, the rest still upload — one failure does not stop the whole delivery.
Uploading to factories
Uploading to the chosen factories adds the variables to their shared environment — with the same key-based merge: the set’s value wins, and the factory’s other variables stay.
There is one important difference from agents: the factory’s shared environment is not picked up immediately, but together with the next configuration build. Nothing is recreated or restarted that very second — the values reach the factory on the nearest deployment. Each report row says exactly that, so it never looks as if the variables were already working.
What is worth knowing
- Uploading only adds. A set does not delete keys it does not have. To remove a variable from an agent, do it on that agent’s own “Environment” tab;
- Your own set wins over the shared one. When the same key is set in several places, whatever is closest to the application wins: the “Environment” tab of the agent or app itself, then the factory’s shared environment, and only then the deployment template. So you can set a common variable for everyone at once and still override it for one application;
- One more source — the
.envfile at the project root. Its values win over those set at deployment and are picked up on the fly; - sets cannot be uploaded through the programmatic Agent API yet — this capability works from the interface;
- “Environments” is about launch variables, not about models. The former section of that name turned into the catalog of models and providers; today’s Environments is about the ordinary environment variables of containers.
How to set the environment right on an agent or a factory — on the Agents and Factories pages; about the model catalog — on the Accounts page.