> ## 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.
# Build agents
> Define agents and configure models, tools, memory, and more.
You build an agent by writing a `defineAgent()` definition in your project. This page starts from the smallest working agent, then serves as the full reference for every option you can configure.
## Build a simple agent
You can build a simple agent in just a few steps.
An agent needs a `slug`, `name`, `description`, `systemPrompt`, and `model`. Create a file in `src/agents/` that default-exports the definition.
```ts src/agents/support.ts theme={null}
import { defineAgent } from "@keystrokehq/keystroke/agent";
export default defineAgent({
slug: "support",
name: "Support",
description: "Answers customer questions concisely.",
systemPrompt: "You are a helpful support assistant. Answer concisely.",
model: "openai/gpt-5.6-sol",
});
```
The `slug` is the stable identity Keystroke uses for discovery, routes, CLI commands, and history.
Ship the project to the platform so the agent runs in the cloud.
```bash theme={null}
keystroke deploy --project
```
Deploy builds and uploads your project, and the CLI now targets it automatically. See [deploy a project](/docs/learn/projects/deploy-a-project) for project setup.
Prompt the deployed agent by its slug, or open **Agents** in the web app.
```bash theme={null}
keystroke agents prompt support --message "Help me understand my bill"
```
The response includes a `sessionId`, the messages, and any error. For repeatable checks, add a [test](/docs/learn/agents/test-agents) that prompts the agent or asserts its definition. You can also use the agent directly from Slack (see [external channels](/docs/learn/agents/external-channels)).
That is a complete, working agent. The rest of this page is the full reference for configuring one.
## Configuration reference
Every agent ships with some capabilities out of the box, then accepts options to change those defaults or add more.
These capabilities are built in, locally and once deployed, with no configuration:
| Built in | What you get | Tune it with |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------- |
| **Workspace** | Isolated `/workspace` with `bash` / `read` / `write` / `edit`; `/workspace/agent` shared across sessions, `/workspace/session` per-session | [`sandbox`, `mode`, `setup`, `git`](#sandboxes) |
| **Web access** | `web_search` and `web_fetch` tools when a web provider is configured | [Web search](#web-search) |
| **Memory** | Session history plus persistent memory, enabled by default | [`memory`](#memory) |
| **Ephemeral triggers** | `set_trigger` and `list_triggers` tools so the agent can schedule its own runs | [Ephemeral triggers](#ephemeral-triggers) |
`defineAgent()` accepts these options. The required fields are all you need to start; the rest are optional.
| Option | Required | What it does |
| --------------- | -------- | --------------------------------------------------------------------------------------------------------------------- |
| `slug` | Yes | Stable identity used for discovery, routes, CLI commands, and history |
| `name` | Yes | Human-readable name shown in the platform |
| `description` | Yes | Short description shown in the platform |
| `systemPrompt` | Yes | Instructions given to the model |
| `model` | Yes | Exact model id from the [catalog](https://keystroke.ai/models.md) in `vendor/model-id` format. See [Models](#models). |
| `thinkingLevel` | No | Reasoning setting. See [Models](#models). |
| `maxSteps` | No | Maximum tool-loop steps per prompt. Defaults to `100`. |
| `tools` | No | Actions, subagents, workflows, or MCP tools. See [Tools](#tools). |
| `skills` | No | Project skill folders. See [Skills and files](#skills-and-files). |
| `sandbox` | No | Workspace file layout and execution mode (`defineSandbox({ files, mode })`). See [Sandboxes](#sandboxes). |
| `memory` | No | Memory options, or `false` to disable. See [Memory](#memory). |
Agent definitions do not have a `credentials` option. Credentials are declared on the actions an agent uses, then resolved when those tools run.
## Tools
Tools allow agents to do real work: look up a customer, send an email, run a workflow, or call another agent. You list the tools an agent is allowed to use in `tools`.
Tools come in a few forms:
| Tool type | What it is | Add it with |
| ------------ | -------------------------------------------------------------- | ------------------------- |
| **Action** | One of your functions, or an action exported by an integration | `tools: [myAction]` |
| **Subagent** | Another agent, exposed as a callable tool | `tools: [researcher]` |
| **Workflow** | A durable, multi-step workflow run as a single tool | `tools: [refundOrder]` |
| **MCP tool** | Tools from an external MCP server, wrapped as app actions | [`MCP tools`](#mcp-tools) |
### Actions as tools
The most common tool is an [action](/docs/learn/actions/overview). The same action works as an agent tool or a workflow step; you just add it to `tools`.
```ts theme={null}
import { defineAgent } from "@keystrokehq/keystroke/agent";
import { lookupCustomer } from "../actions/lookup-customer";
export default defineAgent({
slug: "support",
name: "Support",
description: "Helps customers using the lookupCustomer tool.",
systemPrompt: "Help customers. Use lookupCustomer to find account details.",
model: "openai/gpt-5.6-sol",
tools: [lookupCustomer],
});
```
Integration packages also export actions. Import only the ones the agent should be allowed to use.
```ts theme={null}
import { defineAgent } from "@keystrokehq/keystroke/agent";
import { gmailFetchEmails, gmailSendEmail } from "@keystrokehq/gmail/actions";
export default defineAgent({
slug: "secretary",
name: "Secretary",
description: "Manages Gmail with fetch and send tools.",
systemPrompt: "Help manage Gmail. Confirm ambiguous sends before acting.",
model: "anthropic/claude-sonnet-5",
tools: [gmailFetchEmails, gmailSendEmail],
});
```
Reach for [actions](/docs/learn/actions/agent-tools) for deterministic single-step capabilities, [workflows](#workflows-as-tools) for durable multi-step sequences, [subagents](#subagents-as-tools) for open-ended delegation, and [MCP tools](#mcp-tools) when an external server exposes an MCP surface.
### Subagents as tools
A subagent is an agent exposed as a tool to another agent. Use one when a parent agent should delegate a specialized task (research, a stronger model, a different tool set) without sharing the whole parent conversation as instructions.
Import the agent and add it to the parent agent's `tools`. The tool name is the subagent's `slug`, and the tool expects a `message` string parameter.
```ts theme={null}
import { defineAgent } from "@keystrokehq/keystroke/agent";
import researcher from "./researcher";
export default defineAgent({
slug: "orchestrator",
name: "Orchestrator",
description: "Delegates research tasks to a researcher subagent.",
systemPrompt:
"You are an orchestrator. For research tasks, call researcher before answering.",
model: "openai/gpt-5.6-terra",
tools: [researcher],
});
```
Subagent calls appear as tool calls in the parent session, and the child agent runs as its own queued session. The parent waits for the result; the child counts toward organization concurrency without an extra agent-run dispatch fee. Inspect both in [run history](/docs/learn/logs/agent-runs).
### Workflows as tools
A [workflow](/docs/learn/workflows/overview) packages a fixed, multi-step sequence, often several actions chained together with durable retries. Import it into `tools` when you want the agent to trigger that whole sequence as a single, reliable step instead of orchestrating the steps itself.
```ts theme={null}
import { defineAgent } from "@keystrokehq/keystroke/agent";
import refundOrder from "../workflows/refund-order";
export default defineAgent({
slug: "support",
name: "Support",
description: "Helps customers and can run the refund-order workflow.",
systemPrompt:
"Help customers. To issue a refund, call the refund-order tool with the order ID.",
model: "xai/grok-4.5",
tools: [refundOrder],
});
```
The tool's name and parameters are derived from the workflow's `slug` and input schema, so you do not declare them by hand. The agent calls it like any other tool, and the workflow runs as a queued child with its normal durability, including `ctx.sleep()` and `ctx.hook()`. Inspect the workflow run and the agent session together in [run history](/docs/learn/logs/agent-runs).
Choose a workflow tool when the work is a known sequence that should run reliably, and a [subagent](#subagents-as-tools) when the work needs open-ended reasoning.
### MCP tools
[Model Context Protocol (MCP)](https://modelcontextprotocol.io/) servers expose tools over a standard protocol. Register them as org apps, connect credentials, inspect the live tool list, smoke-test with `apps execute`, author `app.action` wrappers, then put the **app** (or picked actions) in `tools`.
`apps actions list` on a custom MCP is **not** the same as listing an official catalog app. It calls the remote `tools/list` and shows every tool the server advertises. Those tools may not exist as TypeScript `app.action(...)` functions yet — smoke-test with `apps execute`, then wrap what you need.
```bash theme={null}
keystroke docs search "custom apps MCP"
keystroke apps create --mcp https://mcp.deepwiki.com/mcp
keystroke connect my-org/deepwiki --print-url
keystroke apps actions list my-org/deepwiki # remote tools, not project TS actions yet
keystroke apps execute my-org/deepwiki ask_question --input '{"repoName":"facebook/react","question":"…"}'
keystroke apps sync my-org/deepwiki
```
```ts theme={null}
import { defineAgent } from "@keystrokehq/keystroke/agent";
import { deepwiki } from "../apps/deepwiki/app";
// After authoring actions on `deepwiki` via app.action(...):
export default defineAgent({
slug: "researcher",
name: "Researcher",
description: "Answers questions using the DeepWiki MCP app.",
systemPrompt: "Use DeepWiki tools to answer repo questions.",
model: "openai/gpt-5.6-sol",
tools: [deepwiki], // all actions registered on the app
});
```
Do not import `defineMcp` from `@keystrokehq/keystroke/agent`. See [custom apps and MCP](/docs/learn/credentials/custom-integrations).
This is the client side of MCP: your project using an external MCP server. For the reverse, building Keystroke agents, workflows, and triggers from an MCP-capable agent like ChatGPT or Claude, see [MCP for agents](/docs/build-with-ai/mcp-for-agents).
## Skills and files
Skills are reusable instructions in `src/skills/`. Files are static project context in `src/files/`. Both materialize under **`/workspace/agent`** before a prompt runs, so the agent can read them like local files. That directory persists across sessions for shared context — not for git checkouts or package installs (use `/workspace/session` for those). See [Sandboxes](#sandboxes).
```ts theme={null}
import { defineSandbox } from "@keystrokehq/keystroke/sandbox";
export default defineAgent({
slug: "support",
name: "Support",
description: "Answers using the support skill and attached product docs.",
systemPrompt:
"Read /workspace/agent/product-guide.md and the support skill before answering.",
model: "openai/gpt-5.6-sol",
skills: ["support"],
sandbox: defineSandbox({ files: "support" }),
});
```
`files` is a path (or list of paths) under `src/files/`: a set directory, multiple sets, or specific files.
```ts theme={null}
export default defineAgent({
slug: "support",
name: "Support",
description: "Answers using the support handbook file set.",
systemPrompt: "Read the support handbook before answering.",
model: "xai/grok-4.5",
sandbox: defineSandbox({ files: "support-handbook" }),
});
```
```ts theme={null}
sandbox: defineSandbox({
files: ["planetscale", "support/product-guide.md"],
}),
```
See [project skills](/docs/learn/skills/overview) and [files](/docs/learn/files/overview) for the file formats.
## Memory
Memory is what lets an agent remember. It is enabled by default and has two parts:
| Part | What it does |
| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Session history** | Keeps the messages for one conversation so follow-up prompts have context |
| **Persistent memory** | Gives the agent a `memory` tool and a filesystem-backed memory area (`MEMORY.md`, `USER.md`, archive notes, and searchable past sessions) stored outside `/workspace` |
Set `memory: false` for a stateless agent, such as a deterministic classifier or a one-shot extraction agent:
```ts theme={null}
export default defineAgent({
slug: "one-shot-classifier",
name: "One-shot classifier",
description: "Classifies a message and returns only the label.",
systemPrompt: "Classify the message and return only the label.",
model: "deepseek/deepseek-v4-flash",
memory: false,
});
```
Persistent memory is **agent-curated**: the agent writes and edits `USER.md`, `MEMORY.md`, and archive notes itself through the `memory` tool. You don't pre-load it from the definition — put stable, author-provided context in the [`systemPrompt`](#models) or in [files](#skills-and-files) instead. The agent then records what it learns into memory over time.
You can pass an options object to tune memory's limits:
```ts theme={null}
export default defineAgent({
slug: "support",
name: "Support",
description: "Helps users and uses persistent memory when relevant.",
systemPrompt: "Help the user using memory when it is relevant.",
model: "openai/gpt-5.6-sol",
memory: {
memoryCharLimit: 3000,
},
});
```
The `memory` object accepts these options:
| Option | Default | What it does |
| ----------------- | ------- | -------------------------------------------------------------------------- |
| `memoryCharLimit` | `2200` | Char budget for `MEMORY.md`; the memory tool rejects writes that exceed it |
| `userCharLimit` | `1375` | Char budget for `USER.md`; the memory tool rejects writes that exceed it |
| `archiveTocLimit` | `30` | Max archive notes listed in the memory snapshot |
The char limits keep `MEMORY.md` and `USER.md` concise (overflow belongs in unbounded archive notes), so the agent gets a clear error and trims when a write would exceed the budget.
Continue a conversation by passing the same `sessionId` to the next prompt. See [run agents](/docs/learn/agents/run-agents) for session commands.
## Models
The `model` is the LLM that powers the agent's reasoning and tool use. Keystroke supports hundreds of models from providers like Anthropic, OpenAI, and Google, chosen by ID in `vendor/model-id` format.
```ts theme={null}
export default defineAgent({
slug: "researcher",
name: "Researcher",
description: "Researches questions and cites sources when available.",
systemPrompt: "Research the user's question and cite sources when available.",
model: "openai/gpt-5.6-sol",
});
```
### Model selection guide
Same facts as the [models catalog](https://keystroke.ai/models.md) guide (source of truth after nightly refresh). Approximate list prices are USD per 1M tokens (input / output). At the same capability level, OpenAI and Grok are usually cheaper than the Anthropic peer. Any catalog ID works as `model`.
| Capability | Model IDs | Approx. \$/1M in/out | Notes |
| ---------- | ------------------------------------------------------------------- | ---------------------------------------------------- | ------------------------------------------ |
| Everyday | `openai/gpt-5.6-terra`, `xai/grok-4.5`, `anthropic/claude-sonnet-5` | Terra \~$2.50/$15 · Grok \~$2/$6 · Sonnet 5 \~$2/$10 | Routine agents, tools, high volume |
| Stronger | `anthropic/claude-opus-4.8` | Opus 4.8 \~$5/$25 | More capability on harder everyday work |
| Hardest | `openai/gpt-5.6-sol`, `anthropic/claude-fable-5` | Sol \~$5/$30 · Fable 5 \~$10/$50 | Difficult reasoning and long-horizon tasks |
| Budget | `deepseek/deepseek-v4-flash` | \~$0.14/$0.28 | Simple / one-off calls |
| Alt coding | `zai/glm-5.2` | \~$1.40/$4.40 | Coding and long-context work |
Model ids change as providers ship new generations — prefer the live catalog when picking an id. These facts were last reviewed in July 2026.
For the full, current list of model IDs, see the [Keystroke models catalog](https://keystroke.ai/models.md). Copy the **Model ID** column exactly — IDs are opaque catalog strings, not display names you can reformat. Some models use dots in version segments (`openai/gpt-5.6-sol`, `google/gemini-3.5-flash`); others use hyphens (`alibaba/qwen-3-14b`). Do not kebab-case a version number from the model name: `openai/gpt-5-6-sol` is invalid even though the product is called "GPT 5.6 Sol". Unknown IDs fail at build and deploy time.
Hosted workers route through the platform automatically, so deployed agents need no provider keys. To run cloud inference on your own provider API keys instead of platform credentials, connect them in [Managed services](/docs/learn/settings/managed-services) — not as app credentials.
You can use `thinkingLevel` to control the model's reasoning effort when the provider supports it. It defaults to `medium`; valid values are `provider-default`, `none`, `minimal`, `low`, `medium`, `high`, and `xhigh`.
```ts theme={null}
export default defineAgent({
slug: "planner",
name: "Planner",
description: "Plans carefully with higher reasoning effort.",
systemPrompt: "Plan carefully, then give a concise answer.",
model: "openai/gpt-5.6-terra",
thinkingLevel: "high",
});
```
## Structured output
By default `agent.prompt()` returns conversational text in `result.messages`. When you call the agent from code (a [workflow](/docs/learn/workflows/build-workflows#agent-steps), [action](/docs/learn/actions/overview), or script) and need a typed object instead, pass an `outputSchema` (Zod) on the call. `outputSchema` is a **per-prompt** option, not a `defineAgent()` field, so the same agent can return free text on one call and structured data on the next. Read the parsed, typed result from `result.output`:
```ts theme={null}
import { z } from "zod";
import researcher from "../agents/signup-researcher";
const Summary = z.object({ company: z.string(), summary: z.string() });
const result = await researcher.prompt({
message: "Research Acme Corp",
outputSchema: Summary,
});
if (result.error) throw new Error(result.error);
const { company, summary } = result.output!; // typed { company: string; summary: string }
```
Without `outputSchema`, `result.output` is `undefined` and you read the reply from `result.messages`. Structured output is an in-process TypeScript feature — it is not exposed over the HTTP route or `keystroke agents prompt`.
### Schema design: model the shape precisely
Design the schema around the outcomes you actually expect, not one flat object that tries to cover every case with optional fields. This is both better type safety (each result is exhaustively typed) and it sidesteps a hard provider limit: Anthropic's native structured output rejects schemas with **more than 16 union-typed parameters** — every `.nullable()` / `.nullish()` field compiles to a `T | null` union, so a wide flat object blows past the cap and fails at request time with `Schemas contains too many parameters with union types`.
When a result has variants that carry different fields, use a **discriminated union** keyed on a literal so each branch declares only its own required fields:
```ts theme={null}
const Decision = z.discriminatedUnion("action", [
z.object({ action: z.literal("drop"), newPrice: z.number(), reasoning: z.string() }),
z.object({ action: z.literal("no_more_offers"), reasoning: z.string() }),
z.object({ action: z.literal("payment_plan"), months: z.number(), reasoning: z.string() }),
]);
```
Prefer required fields over `.nullable()`/`.nullish()`, and reach for discriminated unions over large optional-heavy objects. OpenAI/Azure strict mode requires every property key in `required` — Zod `.optional()` / `.nullish()` omit keys and the API rejects the schema before the model runs. Keystroke rewrites those wrappers to `.nullable()` on the wire so calls still succeed, but authoring with `.nullable()` (or a discriminated union) matches what providers return and stays under Anthropic's union-parameter limit more predictably.
### Structured output with tools
When an agent has tools **and** you pass `outputSchema`, Keystroke runs a multi-step tool loop: the model calls tools, then returns a schema-validated result. Expect at least two LLM steps (tool call + structured result). See the [AI SDK troubleshooting guide](https://ai-sdk.dev/docs/troubleshooting/tool-calling-with-structured-outputs) for the same step-count rule.
Keystroke applies vendor-specific fixes automatically:
| Vendor | Behavior |
| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Anthropic (Sonnet/Opus)** | Native structured output compatible with extended thinking; forces a tool call on step 1 so the model cannot skip tools by satisfying the schema early. **Haiku** is excluded — tools + schema may still be unreliable. |
| **OpenAI, Google, xAI** | Native structured output; no extra guard needed. |
| **z-ai (GLM), Alibaba (Qwen)** | No native structured output on the gateway. Keystroke uses a **submit tool** (`submit_structured_output`) for `agent.prompt()` with tools and for all `promptLlm()` calls. |
| **Minimax, DeepSeek** | Submit-tool path for `promptLlm()`; native structured output for `agent.prompt()` with tools. |
Gateway model tags (`reasoning`, `tool-use`, `vision`, …) do **not** indicate structured-output support. Pick models from the [models catalog](https://keystroke.ai/models.md) for pricing and capabilities, but rely on the table above for `outputSchema` reliability.
`outputSchema` works in `agent.prompt()` and workflow `promptLlm()` steps. It is not exposed over HTTP or the CLI.
## Web search
Agents can read information from the live web through two built-in host tools, injected when Keystroke can resolve a web provider:
* `web_search` searches the web by query.
* `web_fetch` fetches readable page text from a URL.
In hosted workers the platform can proxy web search automatically. Make the prompt explicit about when to search:
```ts theme={null}
export default defineAgent({
slug: "web-researcher",
name: "Web researcher",
description: "Uses web search and fetch for current factual questions.",
systemPrompt:
"Use web_search before answering factual questions about current companies or events. Use web_fetch to inspect promising sources.",
model: "google/gemini-3.5-flash",
});
```
## Workflow visibility
Deployed agents receive a read-only `list_workflows` tool that lists project-defined workflows
which invoke them, along with the deployed triggers that start each workflow. Trigger details
include configured schedules and timezones plus live active, disabled, or completed status. This
lets an agent recognize that it may be running as one step in a larger workflow and understand how
often that workflow is configured to run. Listing a workflow does not make that workflow callable
by the agent; callable workflows must still be included in `defineAgent({ tools })`.
You can inspect the same relationship from the CLI:
```bash theme={null}
keystroke agents workflows list
```
## Ephemeral triggers
Every agent is given two built-in tools (`set_trigger` and `list_triggers`) so it can schedule its own work without a deploy. The agent can create a cron, webhook, or poll trigger on itself, then update, pause, or delete it later. These are *ephemeral* triggers: the agent manages them at runtime and they live in the database, separate from the triggers you write in `src/triggers/`.
`list_triggers` also reports project-defined triggers that invoke the agent directly or through a
workflow containing it. Workflow triggers are identified by `targetKind: "workflow"` and include
the workflow slug.
These tools are injected automatically; there is no `defineAgent()` option to add them, and they require no configuration. They are how an agent honors a request like "remind me about this in an hour" or "check the deploy every morning and message me if it's red": the agent creates a trigger on itself from inside the conversation instead of needing you to write one.
Ephemeral triggers support the same three kinds as code triggers:
| Kind | Fires |
| ------- | ---------------------------------------- |
| Cron | On a schedule |
| Webhook | When a matching payload hits an endpoint |
| Poll | When a scheduled script reports new work |
Ephemeral poll triggers run a [code mode](#code-mode) script on each tick. The script can call the
agent's tools; its last non-empty line of JSON becomes the trigger payload. Empty output or `null`
skips the run.
For webhook triggers, pass `endpoint` plus an optional `payload` matcher — a shallow map of dot-paths to exact values (e.g. `{ "type": "invoice.paid" }`). Omit `payload` to accept any JSON body. That matches the role of `defineWebhookSource({ payload })` in project code: the matcher is the gate for which deliveries fire the agent. `list_triggers` returns the compiled `payload` schema for webhook triggers.
The agent can give a trigger a `lifecycle` so it stops on its own: `maxExecutions` for a fixed number of runs (a single future reminder is just `maxExecutions: 1`) or `until` for an expiry time. When an ephemeral trigger fires it starts a new agent session and appears in **History** alongside every other run.
When you want a sustained, deploy-time automation instead (a schedule or webhook wired to an agent in code), define it in `src/triggers/`. See [run agents from triggers](/docs/learn/agents/run-agents#run-agents-from-triggers) and the [triggers](/docs/learn/triggers/overview) section.
## Browser use
Browser use means driving a real browser: clicking, filling forms, navigating multi-step flows, and taking screenshots. That goes beyond reading page text with `web_fetch`.
Native browser automation is coming soon. Until then, wrap browser work in a task-specific [action](/docs/learn/actions/agent-tools) or a [workflow](/docs/learn/workflows/overview) step rather than exposing a general browser to the agent.
## Sandboxes
Every agent already gets a `/workspace` with built-in `bash`, `read`, `write`, and `edit` tools, running in-process with no VM. The workspace has two mounts:
| Path | Lifetime | What belongs here |
| -------------------- | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/workspace/agent` | Persists across sessions for that agent (**shared filesystem**) | Deployed [files](/docs/learn/files/overview), [skills](/docs/learn/skills/overview), and other small artifacts the agent wants to **share across sessions** |
| `/workspace/session` | Ephemeral per session | Scratch, clones, installs, builds, and coding-tool defaults |
**Do not** put git repositories or package installs under `/workspace/agent`. That shared filesystem is for files and skills the agent reuses across prompts — not a checkout or `node_modules`. Clone and install under `/workspace/session` (or another session path you choose). Env `setup` installs belong on the **root filesystem** (see [Env setup](#env-setup-setup)), not under `/workspace/agent`.
This default workspace handles a surprising amount on its own: manipulating files, processing text and data, and running shell commands and scripts. Many platforms boot a full sandbox VM for any code execution at all; Keystroke gives agents this lightweight bash environment by default, so **most agents never need a VM**.
The workspace starts empty unless you attach content:
| Source | Where it comes from |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| Agent files | `sandbox: defineSandbox({ files: "key" })` uses `src/files/{key}/`; arrays attach multiple sets or specific paths under `src/files/` |
| Project skills | `skills: ["support"]` materializes `src/skills/support/` under `/workspace/agent/skills/` |
| Inline sandbox files | `defineSandbox({ files: [{ path, file }] })` seeds explicit content in code |
| Runtime files | The agent can create and edit files during the session (`/workspace/session` for scratch; `/workspace/agent` only for cross-session shares) |
Use `defineSandbox()` to attach project file sets or seed specific files directly in code:
```ts theme={null}
import { defineAgent } from "@keystrokehq/keystroke/agent";
import { defineSandbox } from "@keystrokehq/keystroke/sandbox";
const seeded = defineSandbox({
files: [{ path: "context/seed.txt", file: "seeded" }],
});
export default defineAgent({
slug: "sandbox-seeded",
name: "Sandbox seeded",
description: "Reads seeded context files from the sandbox workspace.",
systemPrompt: "Read files from /workspace/agent before answering.",
model: "zai/glm-5.2",
sandbox: seeded,
});
```
### Code mode
In the default in-process workspace, an agent can use **code mode** to call its tools from a
JavaScript or TypeScript script. This is useful when the agent needs to call several tools, loop
over results, filter data, or combine tool output without sending every intermediate result back
through the model.
Code mode is available automatically—there is nothing to add to `defineAgent()`. The agent runs a
script with `js-exec` through its built-in `bash` tool and calls only the tools already available to
that agent:
```bash theme={null}
js-exec -c '
const customer = await tools["lookup-customer"]({ email: "ada@example.com" });
if (customer.openInvoices > 0) {
await tools["send-reminder"]({ email: "ada@example.com" });
}
'
```
Tool names containing hyphens require bracket notation (`tools["tool-name"]`). Tool inputs still
use their normal schemas, credentials resolve normally, and a script cannot call tools that are not
attached to the agent. Errors from a tool fail the script and are returned to the agent.
The `js-exec` tool bridge is available in the default in-process workspace, not in VM-backed
sandboxes. In a VM, use the installed `node` or `python` runtime for scripts and call agent tools
directly from the model.
The in-process bash is not a full machine, though. You can easily enable a VM-backed sandbox with `defineSandbox({ mode: "vm" })` when your agent needs capabilities the default workspace can't provide:
| Enable a VM when your agent needs to… | Example |
| --------------------------------------------- | ------------------------------------------------------------ |
| Run real CLI tools and binaries | `git`, `python`, `ffmpeg`, a package manager |
| Clone, build, and test a real codebase | `git clone` a GitHub repo, install deps, run its tests |
| Install dependencies or system packages | `npm install`, `pip install`, `apt-get`, Playwright/Chromium |
| Run heavy or long-lived processes | compile a project, start a dev server |
| Strongly isolate untrusted code from the host | safely execute arbitrary agent-generated code |
```ts theme={null}
export default defineAgent({
slug: "repo-worker",
name: "Repo worker",
description: "Clones and edits repositories in a VM sandbox.",
systemPrompt: "Clone the repo into /workspace/session, then make the requested change.",
model: "openai/gpt-5.6-sol",
sandbox: defineSandbox({ mode: "vm" }),
});
```
### Hosted VM resources
Hosted VMs use a small CPU/memory request with **no hard limits** (they burst as needed). Author `size` (`small` / `medium` / `large`) is accepted for backward compatibility but **ignored** on hosted cloud. Local microsandbox (`pnpm dev`) may still map size presets to guest resources.
Billable VM time is charged per second of sandbox wall-clock at a flat rate. Persistent agent files live on the **shared filesystem** at `/workspace/agent`; session scratch is ephemeral under `/workspace/session`.
The `bash` tool accepts optional `timeoutMs` so long installs/builds can run past the 180s default (hard-capped at 10 minutes). For **servers that must keep running**, background them (`nohup … &` + log + health poll) — do not block `bash` on them.
### VM credentials and GitHub
Credential env injection and built-in GitHub clone are **VM-only**. Attach credentials on the sandbox, map them into env, and optionally bootstrap a repository with `git.clone`.
Import the app from the package root and use `github.credential` — project builds tree-shake unused actions, so a credentials-only agent does not pull the toolkit catalog. Import from `/actions` only when you attach toolkit tools.
```ts theme={null}
import { github } from "@keystrokehq/github";
sandbox: defineSandbox({
mode: "vm",
credentials: [github.credential] as const,
env: ({ github }) => ({
// Optional aliases — GH_TOKEN / GITHUB_TOKEN are injected automatically when `git` is set
CUSTOM_GITHUB_TOKEN: github.accessToken,
}),
git: {
clone: {
repository: "owner/repo",
credential: "github",
// path defaults to /workspace/session/repo
// branch: "main", // optional branch or tag
// commit: "abcdef01…", // optional full 40-char SHA (takes precedence over branch)
// shallow: false, // default true (`--depth 1`); set false for full history
},
},
setup: [
"npm i -g @posthog/cli",
],
}),
```
With the built-in `git.clone` helper, Keystroke clones into **`/workspace/session`** (default `/workspace/session/repo`). Clones are shallow (`--depth 1`) by default for fast startup; set `shallow: false` for full history. Use `branch` for a branch/tag tip, or `commit` for an exact full 40-character SHA (GitHub supports fetch-by-SHA; abbreviated SHAs and `git clone --branch ` do not). Remounts and later prompts in the same session skip re-clone when the repo already exists.
If you clone or install yourself from `bash` or a skill (instead of `git.clone` / `setup`), keep that work under `/workspace/session` — **never** clone repos or install packages into `/workspace/agent`. The shared filesystem is only for shared files and skills across sessions.
Secrets are merged into every VM exec (not create-time sandbox env). Tokens are model-visible inside the VM so `git` (and `gh` if you install it) can authenticate.
### Env setup (`setup`)
`setup` is an install-style recipe for the **environment root filesystem** — clone-independent global and system packages the agent needs every session (CLIs, runtimes, browsers). Prefer it over installing the same tools from scratch on every prompt. Do **not** use it for long-lived servers or for repo-local `npm install` that depends on a cloned tree (run those under `/workspace/session` after clone).
Hosted env Images are built from `setup` **without** the shared filesystem mounted. After `setup` runs, Keystroke **clears `/workspace/agent`** so session create can attach the shared filesystem. That means:
* Install onto the root filesystem only (`/usr`, `/usr/local`, `$HOME`, Playwright’s default browser cache, etc.).
* **Do not** write under `/workspace/agent` in `setup` — those paths are deleted before the env Image is saved.
* **Do not** expect deployed files or skills under `/workspace/agent` to exist during env setup (the shared filesystem is not mounted yet). Put scripts you need during setup inline in the `setup` commands, or install tools to root-disk paths.
```ts theme={null}
sandbox: defineSandbox({
mode: "vm",
setup: [
// CLIs (global / root-disk — not /workspace/agent)
"npm i -g @posthog/cli",
"curl -fsSL https://bun.sh/install | bash",
// System packages
"apt-get update && apt-get install -y jq ffmpeg",
// Browsers / Playwright (default cache under $HOME — not /workspace/agent)
"npx --yes playwright@1.49.0 install --with-deps chromium",
],
}),
```
Typical `setup` jobs:
| Goal | Example commands |
| --------------------------------- | ------------------------------------------------------------------------------ |
| Global Node CLIs | `npm i -g pnpm@10`, `npm i -g @posthog/cli` |
| Other package managers / runtimes | install Bun, uv, or a pinned Python toolchain |
| System packages | `apt-get install -y jq ripgrep ffmpeg` |
| Playwright / Chromium | `npx playwright install --with-deps chromium` (or a pinned Playwright version) |
| GitHub CLI | `… install gh` then use `gh` with injected `GH_TOKEN` |
Startup order on the **first prompt** of a session: create VM → inject env → git bootstrap → `setup` commands (fail-fast on non-zero exit) → agent tools. Remounts and later prompts in the same session skip `setup` (and skip git clone when the repo already exists).
On hosted VMs:
* Deploy and `keystroke agents snapshot ` build an **org-scoped env Image** (root filesystem snapshot) from `setup` (shared across agents with the same setup fingerprint).
* Cold boots prefer that env Image and skip re-running `setup`; git clone still runs at session start into `/workspace/session`.
* If no env Image is ready yet, the first session runs `setup` inline (with the shared filesystem already mounted) and enqueues a background build.
* Deploy also reconciles `/workspace/agent` files and skills onto the shared filesystem in parallel with env Image builds, so first-prompt file prepare is usually a noop.
**What's already in the VM**
| Runtime | Image / snapshot | `git` | GitHub CLI (`gh`) |
| --------------------------------- | -------------------------------------------------------------- | ---------------------- | ------------------------------------------------ |
| Local / microsandbox (`pnpm dev`) | OCI `node:22` (default) | Included | Not included — install via `setup` or in-session |
| Hosted cloud | Named runtime Image (+ optional org env Image / session Image) | Installed in the Image | Prefer via `setup` → env Image; else in-session |
Built-in `git.clone` uses the `git` binary plus a credential helper that reads `GH_TOKEN` / `GITHUB_TOKEN` — it does not require `gh`. If a managed OAuth provider redacts tokens, the dashboard offers a **Request access** flow (`/{org}/apps?requestAccess={app}`). Legacy Composio API-key connections without a local dual-write need a reconnect (`?connect=`).
In both modes the agent itself runs in the Keystroke worker and works through its `bash`, `read`, `write`, and `edit` tools; `sandbox.mode` only changes where those tools execute. A `bash` call with `mode: "vm"` runs the command inside the VM and returns its output to the agent, rather than running in-process. The agent reaches into the VM through tools; it never runs inside it.
For everything else, we recommend leaving `mode` unset on `defineSandbox()` (the in-process bash is faster to start and saves you money because you aren't running a VM).
## Next steps
Prompt agents from the CLI and inspect sessions.
Add tests and local prompts before deploying agent changes.
Route Slack messages to an agent.
Review conversation history, tool calls, traces, and errors.