# <File />

Replace one UTF-8 file through the nearest active Workspace or Sandbox filesystem.
Canonical: https://agent-markup-language.com/docs/reference/primitives/file/
Documentation index: https://agent-markup-language.com/docs/
Complete documentation: https://agent-markup-language.com/docs/llms.txt

`<File />` writes exactly one application-owned source or resolved AML subtree into the nearest active filesystem and contributes no text to the surrounding AML result. Inside [`<Sandbox />`](https://agent-markup-language.com/docs/reference/primitives/sandbox/) it writes the live guest; otherwise it writes the active [`<Workspace />`](https://agent-markup-language.com/docs/reference/primitives/workspace/) materialization.

```tsx
<Workspace id="review-42" provider={workspace} save>
  <File path="handoff/plan.md">
    <Agent provider={planner}>Write the implementation plan.</Agent>
  </File>
  <Agent provider={reviewer}>Review handoff/plan.md.</Agent>
</Workspace>
```

The first Agent completes before `<File />` writes its result, so the later sibling sees the complete file.

To copy an application file instead of resolving children, use `src`:

```tsx
const runtime = new AmlRuntime({ cwd: import.meta.dirname })

await runtime.evaluate(
  <Sandbox provider={sandbox} access="read-write">
    <File src="./fixtures/policy.md" path=".agents/context/policy.md" />
  </Sandbox>
)
```

## Props

| Prop       | Type            | Default   | Meaning                                                                                  |
| ---------- | --------------- | --------- | ---------------------------------------------------------------------------------------- |
| `path`     | `string`        | required  | Portable relative destination beneath the nearest active filesystem root.                |
| `children` | `AmlRenderable` | exclusive | AML content resolved to the UTF-8 file body.                                             |
| `src`      | `string`        | exclusive | Application-owned UTF-8 file resolved from [`AmlRuntime.cwd`](https://agent-markup-language.com/docs/reference/runtime/). |

Exactly one of `children` or `src` is required. Empty resolved child text is a valid empty file; a local source must be a regular file containing valid UTF-8.

## Placement and write behavior

- Lexical placement selects the owner. A Sandbox guest wins over an enclosing Workspace replica; there are no routing props.
- Without an active Workspace or Sandbox, evaluation rejects.
- A read-only Sandbox still permits private Agent staging, but `<File />` cannot write its live guest filesystem.
- Parent directories are created where the provider permits, non-file destinations are rejected, and built-in providers replace complete files rather than append.
- A Workspace write affects the current materialization. The Workspace `save` policy decides whether a revision is published.

Use [`<Include />`](https://agent-markup-language.com/docs/reference/primitives/include/) to read a live file into prompt text or emit a bounded Agent read instruction. See [Sandbox and Workspace composition](https://agent-markup-language.com/docs/cookbook/sandboxes-and-workspaces/) for the two resource boundaries.