Execution Environments
An execution environment is a named connection point between your FYAI project and a machine you control. You connect the FYAI runner to it, and agents that use the environment can call the runner's tools: kubectl, git, a browser, local files, private-network HTTP services, Claude Code, and any local MCP servers you relay.
Use one when an agent needs to:
- reach systems that aren't on the public internet (internal APIs, databases, clusters, file shares)
- work on files or repositories on a specific machine
- use credentials that already live on that machine, such as a kubeconfig or SSH keys
You manage environments under Platform → Environments.
The agent's reasoning stays on the FYAI platform: the model loop, prompts and conversation run in FYAI's managed environment. Only the tool calls to runner tools are sent, over the runner's outbound connection, to your machine. Whatever a tool returns (command output, file contents, page text) goes back to the platform so the agent can use it. An execution environment changes where tools run, not where inference happens, so it isn't a way to keep data off the platform.
Other tools an agent has, such as Local Python functions and MCP server functions, still run in the platform's own isolated sandbox, not on your runner.
How it fits together
Agent (FYAI platform) Your machine
───────────────────── ────────────
model decides to call "kubectl"
│
▼
policy check: allowed? approval? ◄───── outbound WebSocket ───── fyai-runner
│ (runner connects to FYAI; │
└──── tool call ──────────────────────────────────────────► runs kubectl
│
agent receives the result ◄──────────── result ────────────────────┘
- You create an environment and generate a registration token for it.
- You run the runner on your machine with that token. The runner connects outbound over HTTPS/WebSocket. No inbound ports are needed.
- On connect, the runner announces its tool catalogue (the tools available on that machine). The platform sends back the environment's policy: which tools are allowed, which paths file tools may use, and whether to install browser tools.
- When an agent calls one of those tools, the platform checks the environment's policy, then relays the call to the runner and waits for the result.
Creating an environment
- Go to Platform → Environments.
- Select the + (Add environment) button.
- Fill in the form and select Save.
| Field | What it does |
|---|---|
| Name | Display name. Required. |
| Description | Free text. |
| Type | Local, Container, Docker, AKS (Azure), AWS, Windows Native or Linux Native. For a runner you connect yourself the type is a label only and doesn't change how the runner behaves; Local is the usual choice. The type matters only for platform-managed execution: the Deploy action (see below) and workflow schedules that name the environment. |
| Config (JSON) | Not currently saved. Leave it empty. |
| Quotas (JSON) | Not currently saved. Leave it empty. |
| Install browser tools | When the runner connects, it installs Playwright's Chromium so the browser tool can work. |
After you save, select the environment in the list to see the policy sections and the connection instructions. The Tool Access, File Access and Approval Requirements sections only appear once the environment exists.
A new environment starts with a default tool allow-list (kubectl, helm, git, file_read, http_local, browser, claude_code, claude_sessions, claude_status) and no file access. Unrestricted command execution (shell), file_write, docker and terraform are off until you allow them.
Connecting a runner
Select the environment, then:
- Step 1 — Environment ID (Public) shows the environment's ID. You normally don't need it; the runner works it out from the token.
- Step 2 — Set up the runner on your platform has a tab per platform with download links (hover over the short hash to see the full SHA256) and the registration command.
- Select Token to generate a registration token. The Registration Token dialog shows the token and a ready-to-paste Runner Command (Registration) for the platform tab you have selected.
For the full walkthrough, including running the runner as a background service, see Connect a machine with the runner.
Registration tokens
| Behaviour | Detail |
|---|---|
| Reuse | A token is reusable. Restarting or reconnecting the runner doesn't consume it. |
| Expiry | It expires after 90 days without use, measured from its last successful use. A runner that keeps connecting never hits this. |
| Rotation | Selecting Token again generates a new token. The previous token keeps working for 24 hours, so a host you restart in that window isn't locked out. |
| Visibility | The platform stores only a hash. The plaintext is shown once, in the dialog. On the runner side it's kept in the OS secret store or a 0600 file. |
| Revocation | API only: POST /execution-environments/{id}/revoke-token invalidates every token for the environment and disconnects the runner immediately. |
One runner per environment
An environment holds one runner connection. If a second runner connects with the same environment's token, the platform keeps the newest connection and closes the older one. A second runner doesn't add capacity; create another environment instead. The runner also refuses to start twice on the same machine.
Giving agents the runner's tools
There are two ways to attach an environment's tools to an agent.
| Method | Where | Effect |
|---|---|---|
| Agent or team setting | Agent editor → Configure tab → Execution Environment; team editor → Execution Environment | Every tool the environment allows is added to the agent. An agent left on Project Default inherits its team's environment. |
| Execution environment tool function | Resources → Functions, Function Type: Execution environment tool, pick the Execution Environment | Assign the function to agents like any other function. Adds every tool the environment allows, and lets you set an Approval Override for those tools. See Functions. |
Resolution for the agent/team setting is agent → team. If neither sets an environment, the agent gets no runner tools. Project Default in these dropdowns means "don't override"; there's currently no project-wide default environment you can select in the app.
Tools are attached when a chat or run starts, using the runner's last announced catalogue. If the runner is offline at that point the tools are still listed but calls fail with "Runner not connected". In chat, a warning banner appears when the selected agent's or team's environment isn't Running: Execution environment "name" is unreachable — LEA tools may be unavailable. (LEA, Local Execution Agent, is the runner's internal name.)
A workflow schedule also has an Execution Environment field. Agents in a scheduled run still get runner tools from their own or their team's setting, so set the environment on the agents or teams the workflow uses. See Scheduling Workflows.
Controlling what the runner may do
The environment's policy is the authority. It's enforced by the platform before a call is sent to the runner, so a modified runner, or someone calling the API directly, can't bypass it. The runner also receives the policy when it connects, and the environment's settings replace the allow-list and file paths in the runner's local config file.
| Section | Setting | Effect |
|---|---|---|
| Tool Access | Expose all runner tools (wholesale) on | Every tool the runner has is exposed, including shell (unrestricted command execution), file_write, docker, terraform and every relayed MCP tool. |
| Off, with tools ticked | Only the ticked tools are exposed and callable. Relayed MCP tools must be ticked individually (names look like server__tool). | |
| File Access | Paths listed | file_read and file_write work only under these directories. Claude Code runs default to these directories too. |
| No paths | File tools are blocked from every path. | |
| Allow every path | Add * as a path. | |
| Approval Requirements | No tools require approval on | No environment-level approval. Agent, team, function and risk-appetite settings still apply. |
| Off, with tools ticked | Each ticked tool shows an approval card in chat before it runs. A direct API call to a ticked tool is refused, because nobody is there to approve it. |
Select Save (at the top of the form) after changing any of these. Restrictions take effect at once, because the platform checks every call. Newly allowed tools and changed file paths reach the runner the next time it connects; restart the runner to apply them straight away.
For step-by-step instructions and the quirks of the tool checklist, see Control what an environment's tools can do.
On environments created in the app, switching Unrestricted — allow access to all directories on and saving has no effect: the environment goes back to having no paths. To allow every directory, add * as a path instead.
Status
The environment's status chip is in the Connectivity & Deployment section and refreshes every 10 seconds. Last seen shows when the platform last heard from the runner.
| Status | Meaning |
|---|---|
| Not Deployed | No runner has connected yet. |
| Running | A runner is connected. |
| Unreachable | A runner was connected and has disconnected. New tool calls fail until it reconnects; calls in flight when it dropped fail. |
| Deploying, Stopping, Failed | States of the platform-managed Deploy action. Failed shows a Deployment Error. |
Deploy and Undeploy
The Deploy and Undeploy buttons start and stop a platform-managed deployment of the environment. You don't need them to connect a runner yourself, and they aren't generally available.
Deploy generates a new registration token that isn't shown to you. Your runner's current token keeps working for only 24 hours after that, so once the runner restarts or reconnects after that window it's rejected. If this happens, select Token, then restart the runner with the new token.
Deleting an environment
Select the environment, select Delete and confirm. This can't be undone. Agents, teams and functions that still point at the deleted environment silently get no runner tools, so reassign them first. Stop the runner on the machine too; it stops by itself once the environment no longer exists.
API
Everything on this page is also available through the Catalog API (https://catalog.fyai.co.nz) and the FYAI MCP server. See the Platform API for authentication.
| Endpoint | Purpose |
|---|---|
GET /execution-environments, POST, GET/PATCH/DELETE /execution-environments/{id} | List, create, read, update, delete. |
GET /execution-environments/{id}/status | Status, last heartbeat, token hint and token timestamps. |
POST /execution-environments/{id}/generate-token?grace_hours=24 | New registration token. grace_hours (0 to 168, default 24) sets how long the previous token keeps working. |
GET /execution-environments/{id}/token-status | Token age, last use, days until expiry, whether a runner is connected. Never returns the token. |
POST /execution-environments/{id}/revoke-token | Invalidate all tokens and drop the runner connection. |
GET /execution-environments/{id}/tools | The runner's announced tool catalogue, filtered by the allow-list. |
POST /execution-environments/{id}/invoke-tool | Call one runner tool: {"tool_name": "...", "args": {...}, "timeout_s": 300}. timeout_s is 1 to 3600 (default 300). |
The API also accepts a tier of development or production. Environments created in the app are production. On a development environment, an empty file-path list means every path rather than none, and no default tool allow-list is applied.
invoke-tool returns {"result", "exit_code", "error"}. It responds 403 if the tool isn't allowed or needs approval, 503 if no runner is connected, and 504 if the call times out (the runner is then told to cancel it).
Related
- FYAI runner: what the runner is and which tools it provides
- Connect a machine with the runner
- Control what an environment's tools can do
- Agents and Teams: where you assign an environment
- MCP Gateway: governing MCP servers and external agents