Build agents

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.

Define the agent

An agent needs a slug, name, description, systemPrompt, and model. Create a file in src/agents/ that default-exports the definition.

src/agents/support.ts

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.

Deploy it

Ship the project to the platform so the agent runs in the cloud.

keystroke deploy --project <project-slug>

Deploy builds and uploads your project, and the CLI now targets it automatically. See deploy a project for project setup.

Use it

Prompt the deployed agent by its slug, or open Agents in the web app.

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 that prompts the agent or asserts its definition. You can also use the agent directly from Slack (see 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`
Web access	`web_search` and `web_fetch` tools when a web provider is configured	Web search
Memory	Session history plus persistent memory, enabled by default	`memory`
Ephemeral triggers	`set_trigger` and `list_triggers` tools so the agent can schedule its own runs	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 in `vendor/model-id` format. See Models.
`thinkingLevel`	No	Reasoning setting. See Models.
`maxSteps`	No	Maximum tool-loop steps per prompt. Defaults to `100`.
`tools`	No	Actions, subagents, workflows, or MCP tools. See Tools.
`skills`	No	Project skill folders. See Skills and files.
`sandbox`	No	Workspace file layout and execution mode (`defineSandbox({ files, mode })`). See Sandboxes.
`memory`	No	Memory options, or `false` to disable. See 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`

Actions as tools

The most common tool is an action. The same action works as an agent tool or a workflow step; you just add it to tools.

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.

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 for deterministic single-step capabilities, workflows for durable multi-step sequences, subagents for open-ended delegation, and 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.

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.

Workflows as tools

A workflow 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.

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. Choose a workflow tool when the work is a known sequence that should run reliably, and a subagent when the work needs open-ended reasoning.

MCP tools

Model Context Protocol (MCP) 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.

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

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.

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.

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.

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.

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" }),
});

sandbox: defineSandbox({
  files: ["planetscale", "support/product-guide.md"],
}),

See project skills and files 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:

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 or in files instead. The agent then records what it learns into memory over time. You can pass an options object to tune memory’s limits:

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 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.

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 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. 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 — 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.

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, action, 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:

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:

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

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:

keystroke agents workflows list <agent-slug>

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 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 and the triggers 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 or a workflow 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, skills, 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), 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:

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:

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

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.

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 <sha> 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.

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 <slug> 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

Run agents

Prompt agents from the CLI and inspect sessions.

Test agents

Add tests and local prompts before deploying agent changes.

External channels

Route Slack messages to an agent.

Agent runs

Review conversation history, tool calls, traces, and errors.

Get started

Learn

Build with AI

Resources

Build a simple agent

Configuration reference

Tools

Actions as tools

Subagents as tools

Workflows as tools

MCP tools

Skills and files

Memory

Models

Model selection guide

Structured output

Schema design: model the shape precisely

Structured output with tools

Web search

Workflow visibility

Ephemeral triggers

Browser use

Sandboxes

Code mode

Hosted VM resources

VM credentials and GitHub

Env setup (`setup`)

Next steps

Run agents

Test agents

External channels

Agent runs

​Build a simple agent

​Configuration reference

​Tools

​Actions as tools

​Subagents as tools

​Workflows as tools

​MCP tools

​Skills and files

​Memory

​Models

​Model selection guide

​Structured output

​Schema design: model the shape precisely

​Structured output with tools

​Web search

​Workflow visibility

​Ephemeral triggers

​Browser use

​Sandboxes

​Code mode

​Hosted VM resources

​VM credentials and GitHub

​Env setup (setup)

​Next steps

Run agents

Test agents

External channels

Agent runs

Build a simple agent

Configuration reference

Tools

Actions as tools

Subagents as tools

Workflows as tools

MCP tools

Skills and files

Memory

Models

Model selection guide

Structured output

Schema design: model the shape precisely

Structured output with tools

Web search

Workflow visibility

Ephemeral triggers

Browser use

Sandboxes

Code mode

Hosted VM resources

VM credentials and GitHub

Env setup (`setup`)

Next steps