Environments

Every person and room has a durable sandbox, a computer where the agent runs commands. An environment declares which tools that computer should have, such as Node, the AWS CLI or a deployment tool, so they are installed once and stay installed.

Layout

• Directoryenvironments/

  • Directorytoolchain/

    • environment.json
    • mise.toml
    • setup.sh

Each immediate folder under environments/ with an environment.json declares one item, and it needs at least one of mise.toml or setup.sh. Folders without environment.json are ignored, so support folders can sit alongside. The path environments/ is fixed and cannot be changed in plugin.json.

environments/toolchain/environment.json

{ "name": "toolchain", "description": "Node and deployment tools" }

environments/toolchain/mise.toml

[tools]
node = "24"
aws-cli = "2"
"npm:vercel" = "latest"
"npm:eas-cli" = "latest"

Rule	Value
Key (name, or the folder name)	1 to 63 lowercase letters, digits or hyphens, starting with a letter or digit
description	Required, up to 400 characters
Files	Text only, inside the folder, up to 1 MB per item. .env files, binaries, invalid TOML and duplicate names are rejected.

mise.toml and setup.sh

Tools are installed with mise. setup.sh runs for anything mise cannot express, such as system packages.

• setup.sh runs as root, non-interactively, from its own folder, with CENGRID_ENVIRONMENT, CENGRID_SCOPE and CENGRID_ENV_HASH set.
• It must be idempotent and must not write credentials. Logins come from the keychain.
• Setup times out after 15 minutes by default.
• Installed tools are additive. Disabling an item does not uninstall its packages.

Tools live in /opt/mise, whose shims come first on PATH. A shim runs mise’s copy only where the conversation’s set selects that tool, and otherwise falls through to the host’s.

Scope and ordering

Environments follow the same rules as agents: they live in the organisation, a team or a person, use Added and Available, can be switched off, and can be locked by the organisation. A key can be used once along a chain.

A conversation’s set is built from the scopes it reads, with organisation items first, then the team’s, then the person’s, alphabetical within each. If a key is defined twice, the nearer definition wins. Rooms are not environment homes and membership in another room adds nothing.

When setup fails

A failed item is marked in the error log and the computer status, and later items still run. The first command that completes on the conversation’s computer reports up to five failed items with the redacted tail of the error, so the agent knows those tools may be missing. A failed set retries automatically after five minutes. It retries immediately when its definitions change, the egress policy differs, the computer is new, or a live person in a direct message or an all-internal room triggers it.

Prepared environments

The first use of a set queues a background build so later computers restore the installed tools instead of installing them. The Environments page shows Building, Ready or Failed with the build output and a Retry action. A scope whose network settings or security posture restrict egress shows Not prepared, because its computers install the items directly. Deployment-level details, including bundle storage and AWS image preparation, are in deployment targets.

Install a missing tool

Ask the agent to install a missing tool with mise use <tool> for the current computer, then add it to an environment’s mise.toml to make it repeatable.