Overview

Static context copied into the agent workspace.

Files are static context you give an agent: documents, instructions, reference material that get copied into the agent’s workspace so it can read them like local files. Use files for the background an agent needs every time, such as a product guide, a style sheet, or an API reference, that the agent should read rather than have packed into its system prompt.

Use files for material the agent should read. Use skills for instructions about how the agent should do a task.

Example requests

Ask your coding agent which reference material an agent should always have on hand. It can attach those documents as files.

“Give the sales agent our pricing sheet and competitor comparison to reference on every call prep.”

“Attach our refund policy and support macros so the support agent can read them before drafting replies.”

How files work

Files live in your project under src/files/, grouped into folders called file sets. Attach a set (or specific paths inside src/files/) with sandbox: defineSandbox({ files }) on defineAgent(), and Keystroke materializes the contents into /workspace/agent before a prompt runs.

src/files/support/
  product-guide.md
  support-instructions.md
  context/seed.txt

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: "xai/grok-4.5",
  sandbox: defineSandbox({ files: "support" }),
});

With defineSandbox({ files: "support" }), Keystroke copies src/files/support/ into the agent workspace. The folder layout is preserved under /workspace/agent, so src/files/support/context/seed.txt becomes /workspace/agent/context/seed.txt. Point the agent at the paths it should read from the systemPrompt.

You can also attach multiple sets, or only specific files under src/files/ — see Attach files to agents.

Files vs skills

Files and skills both materialize into the agent workspace, but they serve different purposes:

	Files	Skills
What it is	Static context: documents to read	A playbook: instructions for a task
Where it lands	/workspace/agent/{path}	/workspace/agent/skills/{slug}/
Attach with	sandbox: defineSandbox({ files: "set" }) or files: ["set", "other/file.md"]	skills: ["name"]
Reach for it when	The agent needs reference material	The agent needs procedural guidance

Many agents use both: files for the documents, a skill for how to use them.

Files vs memory

Files, the agent’s own file system, and memory all involve “files,” but they answer different questions: what you give the agent, what the agent writes during a run, and what the agent remembers across runs.

	Files (src/files/)	Agent file system (/workspace)	Memory
Who owns it	You, authored in your project and version-controlled	The agent, during a run	The agent, written and recalled automatically
What it’s for	Static context the agent should read	/workspace/agent = shared across sessions (files/skills); /workspace/session = scratch, clones, installs	Carrying knowledge between sessions
Where it lives	Seeded into /workspace/agent/{path}	/workspace/agent and /workspace/session	A memory area outside /workspace (MEMORY.md, USER.md, archived notes, searchable past sessions)
Lifetime	Reconciled from your project on each prompt after deploy (add/update/delete)	Agent mount persists; session mount is per-session	Persists across sessions

The relationship in one line: files are the project-managed context you seed into the agent file system, while memory is the separate, durable store the agent uses to remember things from one session to the next.

Because deployed files are reconciled from your project, treat them as managed input rather than a place the agent saves work. If an agent needs to remember something for next time, that’s memory, enabled by default and managed by the agent itself. Set memory: false on an agent to make it stateless.

Files and the sandbox

Files seed the agent’s /workspace/agent directory — the shared filesystem (skills and deployed files). Keystroke tracks which paths came from your project and reconciles them on each prompt:

• Added files appear on the next prompt after deploy
• Changed files overwrite the previous deployed content (including agent edits to that path)
• Removed files are deleted from /workspace/agent
• Paths the agent creates on its own (not in your attachment) are left alone

The agent system prompt lists every deploy-owned path under /workspace/agent/, and notes that other files written there persist across sessions and deploys. Treat /workspace/agent as shared context only — not a place to clone git repos or install packages (node_modules, Playwright browsers, etc.). Prefer /workspace/session for scratch, clones, and installs, and memory for knowledge that should survive across sessions. Details: Sandboxes.

Next steps

Attach files to agents

Attach sets, multiple sets, or specific files.

Skills

Give agents reusable playbooks alongside files.

Build agents

Configure models, tools, skills, and files.

Sandboxes

How the agent workspace and file system work.