environments

Execution Environments

Execution environments define where your agent runs shell commands.

Configure reusable environments in your fast-agent config file, then select them by name from the Python API or the CLI.

!!! note Do not confuse an execution environment with your workspace or fast-agent home. The workspace is the project file tree for a run; the home is fast-agent's local config and state root, usually <workspace>/.fast-agent.

By default, fast-agent uses the implicit local environment. To start fast-agent with local shell access simply use fast-agent -x.

You can switch to Docker, a Hugging Face Sandbox, or a custom adapter without changing agent definitions.

result = await harness.shell("pwd")
print(result.stdout, result.stderr, result.exit_code)

Simple Setup

The easiest way to configure environments is to prompt fast-agent:

# container
fast-agent -xx \
-m "configure a docker execution environment (ubuntu) named docker-env " \
" with a read only mount of the current working directory. make it the default" \
--model codexplan

# hf sandbox
fast-agent -xx --url https://huggingface.co/mcp?bouquet=files \
-m "i want to set up an execution environment (hf sandbox) with my most " \
" recent dataset attached" \
--model codexplan

Named environments

Add environments: to <home>/fast-agent.yaml. Relative mount sources resolve against the workspace.

default_environment: ubuntu

environments:
  ubuntu:
    type: docker
    image: ubuntu:24.04
    shell: bash
    cwd: /workspace
    mounts:
      - source: .
        target: /workspace
        mode: rw

  hf-gpu:
    type: huggingface
    image: python:3.12
    flavor: cpu-basic
    cwd: /workspace
    volume_mounts:
      - hf://buckets/username/my-bucket:/workspace:rw

  staging:
    type: custom
    class: mycompany.envs:KubernetesEnvironment
    params:
      namespace: agents-staging

Use the configured name wherever an execution environment is accepted: