> ## Documentation Index
> Fetch the complete documentation index at: https://keystroke.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Attach files to agents

> Make files available in an agent workspace.

You attach files to an [agent](/docs/learn/agents/overview) with the `sandbox` option on `defineAgent()`. Pass `defineSandbox({ files })` to copy paths from `src/files/` into the agent's `/workspace/agent` directory before each prompt, where the agent can read them like local files.

`files` accepts:

* A **directory** under `src/files/` (a file set), as a string
* One or more **directories and/or specific files**, as a string array
* Inline `{ path, file }` entries when you seed content directly in code

## Attach an entire file set

Pass a string to attach every file in `src/files/{name}/`:

```ts src/agents/support.ts theme={null}
import { defineAgent } from "@keystrokehq/keystroke/agent";
import { defineSandbox } from "@keystrokehq/keystroke/sandbox";

export default defineAgent({
  slug: "support",
  name: "Support",
  description: "Answers using the product guide in the agent file set.",
  systemPrompt: "Read /workspace/agent/product-guide.md before answering.",
  model: "openai/gpt-5.6-sol",
  sandbox: defineSandbox({ files: "support" }), // uses src/files/support/
});
```

If the folder doesn't exist, the agent fails to build with an "unknown file set" error. A shared set can be attached to any number of agents.

## Attach multiple sets

Pass an array of set names when an agent needs several shared folders:

```ts theme={null}
import { defineSandbox } from "@keystrokehq/keystroke/sandbox";

export default defineAgent({
  slug: "ops",
  name: "Ops",
  description: "Answers using PlanetScale and Metabase reference files.",
  systemPrompt: "Use the PlanetScale and Metabase reference files under /workspace/agent.",
  model: "deepseek/deepseek-v4-flash",
  sandbox: defineSandbox({ files: ["planetscale", "metabase"] }),
});
```

Each set's folder layout is preserved under `/workspace/agent`. If two sets contain the same relative path with different contents, resolve fails with a conflicting-path error.

## Attach specific files

Pass paths relative to `src/files/` to attach only those files (or a nested directory):

```ts theme={null}
import { defineSandbox } from "@keystrokehq/keystroke/sandbox";

export default defineAgent({
  slug: "support",
  name: "Support",
  description: "Answers using selected product guide and schema files.",
  systemPrompt: "Read the product guide and schema before answering.",
  model: "xai/grok-4.5",
  sandbox: defineSandbox({
    files: ["support/product-guide.md", "planetscale/schema.md"],
  }),
});
```

You can mix sets and file paths in the same array: `files: ["planetscale", "support/macros.md"]`.

## Where files land at runtime

Paths are relative to the file set root (the top-level folder under `src/files/`):

```
src/files/support/product-guide.md        →  /workspace/agent/product-guide.md
src/files/support/context/seed.txt        →  /workspace/agent/context/seed.txt
src/files/planetscale/schema.md           →  /workspace/agent/schema.md
```

Reference the paths the agent should read from the `systemPrompt` so the agent knows they're there:

```ts theme={null}
systemPrompt:
  "Read /workspace/agent/product-guide.md and /workspace/agent/support-instructions.md first.",
```

Keystroke reconciles attached files on each prompt after deploy: new files are created, changed files overwrite previous deployed content, and removed files are deleted. Agent-created paths that were never part of the attachment are preserved. The agent system prompt includes the full list of deploy-owned paths so the model knows which files may be overwritten.

## Verify it

After deploying, prompt the agent and confirm it's using the files:

```bash theme={null}
keystroke deploy --project <slug>   # or --filter agents/support
keystroke agents prompt support --message "What is our refund window?"
```

## Next steps

<CardGroup cols={2}>
  <Card title="Files overview" href="/docs/learn/files/overview">
    What files are and how they differ from skills.
  </Card>

  <Card title="Attach skills to agents" href="/docs/learn/skills/attach-skills-to-agents">
    Add reusable playbooks alongside files.
  </Card>

  <Card title="Build agents" href="/docs/learn/agents/build-agents">
    Configure models, tools, skills, and files.
  </Card>

  <Card title="Run agents" href="/docs/learn/agents/run-agents">
    Prompt agents and inspect their sessions.
  </Card>
</CardGroup>