Config
Config is where a project keeps its configuration values, API keys and secrets in one governed place. Values are organised into groups. Secret values are encrypted at rest and masked in the dashboard. Other parts of Console, such as agents and sandboxes, can reference a Config item instead of holding their own copy of the value, so changing it in one place updates everything that uses it.
On screen the page is titled Config Management. Operators open it under Settings → Config.
Concepts
| Object | What it is |
|---|---|
| Group | A named container for related items, with a key, description and tags. Deleting a group deletes all of its items. |
| Item | One value: a name, a key, a description, tags, a type, the value, and a Secret flag. Items keep a version number that increases when the value changes. |
Both groups and items are scoped to the active project. Item types are string, number, boolean and json. The create form adapts to the type: a number field, a true/false picker, and so on.
When an item is marked Secret, its value is encrypted at rest and shown masked everywhere in the dashboard and in normal API reads. The encryption key is derived from the PROVIDER_ENCRYPTION_SECRET environment setting (Console falls back to the JWT secret when it is empty). If that setting changes, existing secret values can no longer be decrypted, so treat it as a long-lived value. See Configuration.
What you see on the screen
The Config page lists your groups with the number of items and secrets in each. Tiles at the top show the totals for groups, items and secrets. You can search groups and open one.
A group page lists its items with name and key, type, value (masked for secrets), version and last update. Item actions are Edit, Copy key and Delete. The group page also shows its properties (key, description, tags, created and updated) and a Where it is used section listing the agents and templates that read this group's items, so you can see what a change affects.
Create a group and add items
- Open Settings → Config and choose New Config Group.
- Enter a name, an optional key (it is generated from the name if you leave it empty and cannot be changed later), a description and comma-separated tags.
- Open the group and choose New Config Item.
- Enter a name and an optional key, choose the type, enter the value, and switch Secret on for anything sensitive.
- Save. The item starts at version 1.
To change a value, choose Edit on the item. For a secret, leave the value empty to keep the stored one, or type a new value to replace it.
Use Config from agents and sandboxes
An agent or sandbox can take an environment variable or secret from Config instead of a typed value: pick Config on the variable row and select an item, or bind a whole group so each of its items becomes a variable. The value is read when the agent runs or the sandbox starts, so an update in Config reaches the next run.
Taking a value from Config requires read access to Config in the project, even if you may edit the agent; without it the save is refused and you can type the value instead. A reference resolves only to items of the project it is used in. Console records a read in the Config audit log whenever it reads a secret item for a reference. The full behaviour (name suggestions, precedence, masking) is described in Environment variables from Config.
Read values from your own code
The client API manages groups and items and can resolve keys to their decrypted values, up to 50 keys per request. Resolving a secret writes a read entry to the item's audit log, as do item creates, updates and deletes; the audit log is available through the API (GET /api/client/v1/config/items/:key/audit). See the Config API reference and the Config SDK reference.
Permissions and requirements
| Topic | Behaviour |
|---|---|
| Permission | The config service. It is an administrative service, so write access follows the policy rules for admin services. API tokens need config in their service permissions. |
| Scope | Groups and items belong to a project. |
| Deleting | Deleting a group permanently deletes its items. Check Where it is used first. |
| Secrets | Encrypted at rest; masked in the UI and in standard reads. Only the resolve endpoint and server-side references return the plain value. |
| Env settings | PROVIDER_ENCRYPTION_SECRET (at least 32 characters, different from the JWT secret) is the encryption secret. |