> ## Documentation Index
> Fetch the complete documentation index at: https://app.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 a file set to an [agent](/learn/agents/overview) with the `sandbox` option on `defineAgent()`. Pass `defineSandbox({ files })` to copy a set from `src/files/` into the agent's `/workspace/agent` directory before each prompt, where the agent can read them like local files.

## Use the agent's own set

The simplest case: `files: true` on `defineSandbox()` uses the file set whose folder name matches the agent's `slug`.

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

export default defineAgent({
  slug: "support",
  systemPrompt: "Read /workspace/agent/product-guide.md before answering.",
  model: "anthropic/claude-sonnet-4.6",
  sandbox: defineSandbox({ files: true }), // uses src/files/support/
});
```

This expects a folder at `src/files/support/`. If it doesn't exist, the agent fails to build with an "unknown file set" error.

## Use a named set

Pass a string to use a different set, useful when several agents share the same documents:

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

export default defineAgent({
  slug: "support",
  systemPrompt: "Read the support handbook before answering.",
  model: "anthropic/claude-sonnet-4.6",
  sandbox: defineSandbox({ files: "support-handbook" }), // uses src/files/support-handbook/
});
```

A shared set lives at `src/files/{name}/` and can be attached to any number of agents.

## Where files land at runtime

The set's folder layout is preserved under `/workspace/agent`:

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

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.",
```

Seeding is idempotent: files are written once per session, and any edits the agent makes during a run are preserved.

## 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="/learn/files/overview">
    What files are and how they differ from skills.
  </Card>

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

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

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