Environments - Flashduty Docs

Private beta: AI SRE is currently in private beta. Pro or higher accounts can apply for free beta access through the AI SRE private beta application form; after approval, Flashduty will add your account to the whitelist. Features and the UI may change during the beta.

Overview

An Environment is where AI SRE agents actually execute actions. Every tool call the agent makes, including running commands, reading and writing files, running Skills, and connecting to MCP services, happens inside an Environment. AI SRE provides two types of Environments:

Cloud Sandbox

A Flashduty-managed temporary container that works out of the box with no install. When no usable BYOC Runner is online for the current member, sessions automatically fall back to the cloud Sandbox.

BYOC Runner

A persistent process deployed on your own machine. It connects to AI SRE over WebSocket and lets the agent execute inside your network boundary.

The default selection logic is: AI SRE uses an online BYOC Runner that the current member can use first; otherwise it uses the cloud Sandbox. Usable Runners include account-scoped Runners and team-scoped Runners that belong to one of the current member’s teams. You can also pin a session to the cloud Sandbox, or to a specific Runner, from the environment selector in the chat input.

The console record is called an Environment. The process running on your machine is called a Runner. One BYOC Environment maps to one Runner process; cloud Sandbox instances are managed by the system per session.

Cloud sandbox

The cloud Sandbox is a temporary execution container managed by Flashduty. It is best for quick starts, demos, and investigations that do not need access to your private network. You do not install a process or maintain a machine. Use the cloud Sandbox when:

you have not deployed a Runner yet and want to try AI SRE first;
the investigation only needs Flashduty data, trusted public services, or public documentation;
the task is one-off and lightweight, so it does not justify a persistent machine;
you want to force execution into the managed environment instead of using an existing Runner in the account.

The cloud Sandbox cannot reach your VPC, dedicated line, private databases, private APIs, or jump hosts. When an investigation needs direct access to those resources, use a BYOC Runner and place execution on a machine that can reach the target.

For lifecycle, egress boundaries, and session-selection details, see Sandbox.

BYOC Runner

A BYOC (Bring Your Own Compute) Runner is a flashduty-runner process that you deploy on your own machine. It keeps a persistent WebSocket connection to AI SRE. When it receives work, it runs commands, reads and writes files, executes Skills, and connects to MCP services that are reachable from that machine. The value of BYOC Runner comes from where execution happens:

Reach your real environment

The Runner runs on your machine, so it can access whatever that machine can reach: VPCs, intranets, dedicated lines, Kubernetes clusters, cloud-provider CLIs, databases, or jump hosts.

Data residency

Command output, logs, temporary files, and tool results primarily stay inside your network boundary. The agent can read and analyze them, while the execution surface remains constrained by your OS account, filesystem permissions, and network policy.

Local permissions under your control

You decide which OS user the Runner runs as, which directories it can access, which CLI credentials it has, and whether to load the permission configuration on this page to narrow the command surface.

BYOC Runner egress is governed by your machine and firewall. The per-domain egress allowlist used by the cloud Sandbox does not apply to BYOC, so the self-hosted Environment form does not provide network-access configuration.

Create and connect

Go to Environments in the AI SRE sidebar and create a self-hosted Environment. The form asks for:

Field	Required	Description
Name	No	Unique within the account, up to 128 characters. If left blank, the first Runner heartbeat auto-fills it with the machine hostname; if that hostname already exists, the Environment ID suffix is appended.
Scope	Yes	Account scope is visible to the whole account. Team scope is visible and editable only by that team. See Scope.
Tags	No	Tags used for task routing, comma-separated, for example `linux, docker, gpu`.

After creation, the setup guide opens with this Environment’s Token, install command, upgrade command, and uninstall command. The key button on a list row, or the “Setup guide” entry for a pending row, opens the same modal.

Installation methods

The setup guide automatically fills in the real TOKEN and URL. The examples below use placeholders; use the command generated by the console.

Linux (systemd)
Docker
Manual / macOS

Run as root / sudo on the target machine:

curl -fsSL https://static.flashcat.cloud/flashduty-runner/install.sh | \
  sudo TOKEN=<your-token> \
  URL=<connect-url> \
  bash

The script installs the binary, creates a systemd service, and writes /etc/flashduty-runner/env. The same command works for fresh installs and upgrades; if the latest version is already installed, it skips automatically.

Start the container on a machine with Docker installed:

docker run -d \
  --name flashduty-runner \
  -e FLASHDUTY_RUNNER_TOKEN=<your-token> \
  -e FLASHDUTY_RUNNER_URL=<connect-url> \
  -v /var/flashduty/workspace:/workspace \
  registry.flashcat.cloud/public/flashduty-runner:latest

Docker access depends on container mounts. If the Runner needs kubeconfig, cloud CLI credentials, or the Docker socket, add the required -v / -e options before the image name.

Install the binary first, then start the process manually:

curl -fsSL https://static.flashcat.cloud/flashduty-runner/install.sh | sudo bash -s -- --no-service

FLASHDUTY_RUNNER_TOKEN=<your-token> \
FLASHDUTY_RUNNER_URL=<connect-url> \
flashduty-runner run

Manual mode does not register a systemd service. Use it for macOS, temporary diagnostics, or your own process manager.

Both connect-url and install_script_url are returned by the backend; the frontend does not hardcode them. Private or air-gapped deployments can replace the install-script distribution source with an internal mirror, but the mirror must serve install.sh, releases/latest, and releases/download/<version>/... release assets.

Linux service user

Linux (systemd) installs run as an auto-created flashduty user by default. That user has no sudo access. The systemd unit enables hardening such as NoNewPrivileges=true, ProtectSystem=strict, and PrivateTmp=true, and only grants write access to the Runner state directory. If the Runner needs to read kubeconfig, cloud CLI credentials, or Docker group access from an existing user, enter a “Linux service user” in the setup guide, or add RUN_AS manually:

curl -fsSL https://static.flashcat.cloud/flashduty-runner/install.sh | \
  sudo TOKEN=<your-token> \
  URL=<connect-url> \
  RUN_AS=<existing-user> \
  bash

RUN_AS is equivalent to the install script’s --run-as <user> flag. The user must already exist on the system. This makes the systemd service run as that user and relaxes the home-directory protection for that user accordingly.

Only set RUN_AS when the Runner truly needs that user’s local credentials or group membership. Otherwise, prefer the default flashduty user.

Token, upgrades, and uninstall

The Token is the only credential a Runner uses to connect to AI SRE. It is written into the install command or environment variables. View it only when installing, upgrading, or debugging the connection, and do not share it. If you suspect a leak, delete the Environment and create a new one. After the Runner starts, it continuously sends heartbeats. List statuses mean:

Status	Meaning
Pending	The Environment exists, but the Runner has never connected.
Online	The Runner is currently connected, heartbeat is healthy, and it can accept work.
Offline	The Runner connected before, but its heartbeat is currently lost.

The backend compares Runner versions during heartbeats. When a newer version is available, the Runner receives an upgrade notification and downloads, verifies, and replaces itself. Re-running the install command also upgrades manually. Uninstall commands are in the setup guide: --uninstall removes the service while preserving config, and --purge removes config and data.

Permission Configuration

By default, Runner uses an allow-all rule:

permission:
  "*": "allow"

When you want to narrow which commands the Runner may execute, create a YAML file on the Runner machine and point the Runner to it with --permission-config or FLASHDUTY_RUNNER_PERMISSION_CONFIG. Permission configuration is a local Runner file; it is not edited in the console form. For a Linux (systemd) install, add this to /etc/flashduty-runner/env:

FLASHDUTY_RUNNER_PERMISSION_CONFIG=/etc/flashduty-runner/permission.yaml

Then restart the service:

sudo systemctl restart flashduty-runner

For manual mode, pass the flag directly:

flashduty-runner run \
  --token <your-token> \
  --permission-config /etc/flashduty-runner/permission.yaml

A common read-only troubleshooting config looks like this:

permission:
  "*": "deny"
  "kubectl get *": "allow"
  "kubectl describe *": "allow"
  "kubectl logs *": "allow"
  "ls": "allow"
  "ls *": "allow"
  "cat *": "allow"
  "head *": "allow"
  "tail *": "allow"
  "grep *": "allow"
  "pwd": "allow"
  "whoami": "allow"
  "date": "allow"

Rule semantics:

permission is the top-level key; beneath it is a flat glob pattern: allow|deny map;
when no config file is set, Runner allows all commands;
once a config file is set, a missing file, invalid YAML, or empty permission map makes Runner refuse to start, avoiding an accidental fallback to allow-all;
commands are matched after shell normalization, so spacing differences do not affect matching;
rules are ordered by specificity: the longer literal prefix before * wins, and * is always the fallback;
Runner checks commands inside pipelines, command substitution, process substitution, and arithmetic expansion;
write redirects are checked as synthetic commands such as > /path, >> /path, and &> /path; read redirects are not blocked by themselves.

Permission configuration loads at Runner startup. Restart the Runner after editing the YAML file.

Permission Configuration

By default, the Runner allows any command — the same trust model as running the AI model directly in your own shell. If you need to restrict which commands the Runner may execute, point it at a YAML rules file with the --permission-config flag or the FLASHDUTY_RUNNER_PERMISSION_CONFIG environment variable:

flashduty-runner run --token <your-token> --permission-config /etc/flashduty-runner/permission.yaml

# Or via environment variable
export FLASHDUTY_RUNNER_PERMISSION_CONFIG=/etc/flashduty-runner/permission.yaml

The rules file’s top-level key is permission, mapping glob patterns to allow/deny:

permission:
  "*": "deny"
  "kubectl get *": "allow"
  "kubectl describe *": "allow"
  "cat *": "allow"

Rules apply everywhere a command can appear — inside pipelines (cmd1 | cmd2), $(...)/backtick command substitution, process substitution, and write-redirect targets (so echo x > /etc/passwd is gated the same way as running a command).
The most specific rule wins: the pattern with the longest literal prefix before its first * is tried first; the catch-all "*" is always tried last, and the first matching rule applies.
The file is loaded once, at Runner startup — edit the rules and restart the Runner for changes to take effect; there is no hot reload.
If the flag/env var is set but the file is missing, malformed, or defines no rules under the permission key, the Runner refuses to start (fails closed) rather than silently allowing every command: pointing the Runner at a permission config is a deliberate request to restrict it, so a broken config should surface as an error, not a silent security gap.
Leaving the flag/env var unset is the default and is equivalent to allowing all commands.

Strict mode (recommended for shared environments)

Deny everything by default, then explicitly allow only what you need:

permission:
  "*": "deny"
  "kubectl get *": "allow"
  "kubectl describe *": "allow"
  "kubectl logs *": "allow"
  "cat *": "allow"
  "ls *": "allow"

Trust mode (for dedicated/isolated environments)

Equivalent to not setting --permission-config at all, but lets you carve out explicit exceptions:

permission:
  "*": "allow"                 # Trust the AI model
  "rm -rf /": "deny"           # Block catastrophic commands if desired

Suitable when the Runner runs in an isolated VM/container with limited blast radius, or when fast incident response matters more than restricting permissions.

Read-only mode (for monitoring only)

Allow only read-only commands — suitable when the Runner should observe but never modify state:

permission:
  "*": "deny"
  "cat *": "allow"
  "head *": "allow"
  "tail *": "allow"
  "ls *": "allow"
  "grep *": "allow"
  "ps *": "allow"
  "df *": "allow"
  "free *": "allow"

Command permission is currently configured only through this file — there is no console UI for it yet.

Selecting an environment in a session

The environment selector at the bottom of the chat input decides where a new session executes:

Option	Meaning
Auto	The default for new sessions. Uses an online Runner the current member can use; otherwise falls back to the cloud Sandbox.
Cloud Sandbox · Default	Forces the system-managed cloud Sandbox and ignores self-hosted Runners.
Self-hosted Environment	Lists Runners the current member can use. Offline, never-connected, or team-mismatched Runners cannot be selected.

Environment selection is locked once per session: the Environment determined when the session sends its first message is recorded and reused for all later turns. Changing the selector afterward does not change that session. To switch environments, start a new session.

When you open a historical session, the selector shows the Environment that session originally locked to, along with its current status, in read-only mode. If the bound Runner is offline or deleted, the session cannot continue sending messages; reconnect that Runner or start a new session and use the cloud Sandbox.

Scope

Each BYOC Environment has account-level or team-level scope:

Scope	Visibility
Account	Visible, selectable, and usable by all members in the account.
Team	Visible, editable, selectable, and usable only by members of that team.

Edit permissions follow the unified rule:

Account owners and account admins can edit any Environment.
Team members can edit team-scoped Environments for their team.
There is no “creator extra permission”; you do not need to be the creator if the rules above allow the edit.

The account remains the runtime security boundary, but team scope also participates in Runner selection. When the system auto-selects a Runner, or when a session is pinned to a Runner by ID, it only uses account-scoped Runners or team-scoped Runners that belong to one of the current member’s teams. This prevents a member from landing a session on a team Runner they cannot use.

Troubleshooting

When troubleshooting Runner issues, start with the Status and Last heartbeat columns in the Environments list.

Runner shows Offline

Offline means the Runner connected before, but AI SRE has not received a heartbeat for about 90 seconds. Check whether the systemd service or process is running, whether the machine is sleeping or offline, and whether outbound traffic to AI SRE is blocked by a firewall. After process and network recovery, the Runner reconnects automatically.

Runner stays Pending

Pending means this Environment has never connected successfully. Confirm that the install command completed, the Token belongs to this Environment, and the URL is reachable from the target machine. If you configured permissions, also confirm that the file exists and the YAML parses.

Session times out or does not respond

If a session is pinned to an offline Runner, AI SRE does not silently move it to another environment. Restore that Runner, or start a new session and choose Auto or cloud Sandbox. If the Runner is online but the task fails, the likely issue is network or permissions between the Runner and the target resource.

Fastest split: Offline / Pending points to the Runner-to-AI-SRE connection; Online but execution fails points to network, credentials, or permissions between the Runner and the target resource.

Sandbox

Learn the cloud Sandbox lifecycle, use cases, and egress boundary.

Console

View the Environment, team, and resources invoked by the agent that are bound to a session.

MCP (External Tools)

MCP connections are established inside the selected environment at agent runtime.

Skills

Skills execute inside the selected Environment.

​Overview

Cloud Sandbox

BYOC Runner

​Cloud sandbox

​BYOC Runner

​Create and connect

​Installation methods

​Linux service user

​Token, upgrades, and uninstall

​Permission Configuration

​Permission Configuration

​Selecting an environment in a session

​Scope

​Troubleshooting

​Related pages

Sandbox

Console

MCP (External Tools)

Skills

Overview

Cloud sandbox

BYOC Runner

Create and connect

Installation methods

Linux service user

Token, upgrades, and uninstall

Permission Configuration

Permission Configuration

Selecting an environment in a session

Scope

Troubleshooting

Related pages