Setups | 514 Docs

setup prepares the sandbox for an environment or product. Use setup scripts to install tools, create fixtures, start services, or expose resources the agent needs. Anything the script writes into /workspace is agent-visible, so keep those paths and contents a realistic job. See Experiment design.

Each variant has its own isolated /workspace. A setup script cannot rely on files or side effects created by another variant.

Accepted shapes:

# String form: one setup script.
setup: "npm install"

# List of strings: multiple setup scripts, run in order.
setup:
  - "npm install"
  - "npm test -- --help"

# Object form: one named setup with optional scoped resources.
setup:
  name: install-cli
  script: "npm install"

# List of objects: multiple named setups, run in order.
setup:
  - name: install-cli
    script: "npm install"
  - name: smoke-cli
    script: "npm test -- --help"

# Mixed list: strings and setup objects can be combined.
setup:
  - "npm install"
  - name: smoke-cli
    script: "npm test -- --help"

Setup object

A setup object is the named form of setup. Use it when setup needs its own files, environment variables, MCP servers, skills, or setup checks.

Field	Required	Type / values	Notes
`name`	Yes	Kebab-case string	Required for object form.
`script`	Yes	String	Bash run before setup checks and before the agent. Secret values are not injected here.
`description`	No	String	Human-readable notes.
`tags`	No	String list	Free-form labels.
`files`	No	File entry list	Host files staged before this setup's script runs (scoped to variants that resolve this setup).
`environment_variables`	No	Environment variable list	Runtime env vars scoped to variants that use this setup.
`mcp_servers`	No	MCP server list	MCP servers exposed to the agent.
`skills`	No	Skill list	Local Agent Skill bundles staged through the resolved agent's native discovery path.
`setup_checks`	No	Setup check list	Checks run after setup and before the agent.

When both a product and environment contribute setup, product setup runs before environment setup.

A setup's files and skill sources stage before that setup's script and stay visible to the agent for the rest of the run, like top-level files. After the script finishes, Fiveonefour verifies each skill bundle and exposes it through the resolved agent's native discovery path. Setup checks run after that installation. For files only a test should see, use test-scoped files instead.

Agent config from setup

Use setup to write agent config into the sandbox home before the agent starts. For codex, write $HOME/.codex/config.toml. The harness merges that file under its own required keys when it prepares the run, so harness settings win on conflict and every other key you set is preserved.

setup: |
  mkdir -p "$HOME/.codex"
  cat > "$HOME/.codex/config.toml" <<'EOF'
  web_search = "disabled"
  EOF

Keys the harness owns for a Codex run (and will overwrite if you set them):

Key	When
`show_raw_agent_reasoning`	Always
`model_reasoning_summary`	Managed model access
`model_context_window`	When the variant sets a context window
`openai_base_url`, `model_provider`, `[model_providers.gateway]`	Managed model access / custom OpenAI base URL
`[mcp_servers.<name>]` for each declared server	When the experiment declares that MCP server

A malformed $HOME/.codex/config.toml fails the run before the agent starts.

Search documentation

Setup object

Agent config from setup