Search documentation

Search the Fumadocs-backed documentation index.

Files

Host files staged into each variant's workspace before setup runs.

Top-level files stages host files into every variant's /workspace before setup runs, visible to the agent like the rest of the workspace. The same shape is accepted on setup objects; setup-scoped entries stage only for variants that resolve that setup. For files a test should see but the agent must not, such as a reference implementation or an expected-output fixture, use test-scoped files instead: those stage only for that test, immediately before its script, never while the agent's own turn is still in progress.

dest paths and file contents are part of the job the agent sees. Keep them realistic; do not name them as fixtures, answer keys, or evaluation scaffolding. See Experiment design.

files:
  - name: my-cli
    source: ../build/mycli
    dest: tools/mycli
  - source: https://example.com/fixtures/data.bin
    sha256: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
    dest: fixtures/data.bin

File entry object

FieldRequiredType / valuesNotes
nameSometimesKebab-case stringRequired when source is omitted. Used as the --file NAME=SOURCE handle.
sourceSometimesHost path or http(s) URLRequired when name is omitted. Relative paths resolve against the YAML file's directory.
sha256No64-char hex stringValid for file sources and URL downloads. Invalid for directory sources.
destYesWorkspace-relative pathAbsolute paths, .., .axp-bridge, and :: are rejected.

Notes:

  • Directory sources copy their contents under dest/.
  • File sources land as a single file at dest.
  • URL sources must be publicly fetchable and land as a single file at dest; unpack archives in setup if needed.
  • Sandboxes are Linux containers; macOS binaries staged from a laptop will not run there.
  • Directory walks honor .axpignore, not .gitignore.
  • --file NAME=SOURCE binds or overrides the source of a named entry.
  • --file SOURCE::DEST stages an ad-hoc entry into every variant.
  • Missing or unbound sources abort real runs at preflight. --resolve-variants renders MISSING / UNBOUND annotations without failing.
  • Staging failures roll the variant up as status=error / exit_reason=staging_failed; the rest of the run keeps going.
  • Platform and local runs both stage top-level files.
  • Treat experiment YAML like a script you run: sources are read with your permissions and may point anywhere on the host.

Registered experiments

ax experiment push uploads declared sources and stores their content-addressed blobs with the registered YAML version. ax experiment run <EXPERIMENT_ID> then uses those stored blobs, so another machine does not need the original source paths. Run-time --file values override stored entries for that run only.

ax experiment pull restores the YAML and stored sources as a runnable local package. --stdout remains YAML-only.

File bytes do not yet participate in the version fingerprint. Re-pushing the same YAML with changed files keeps the version id and replaces its stored file manifest.