Attach files to agents

Make files available in an agent workspace.

You attach files to an agent 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}/:

src/agents/support.ts

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:

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):

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:

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:

keystroke deploy --project <slug>   # or --filter agents/support
keystroke agents prompt support --message "What is our refund window?"

Next steps

Files overview

What files are and how they differ from skills.

Attach skills to agents

Add reusable playbooks alongside files.

Build agents

Configure models, tools, skills, and files.

Run agents

Prompt agents and inspect their sessions.