experimental-ash weekly downloads statistics

Ash

Ash is a filesystem-first framework for durable backend agents on Vercel.

You author an agent as a directory on disk. The directory is the contract — markdown for the parts a human should read like a spec, TypeScript for the parts that benefit from real types and runtime behavior.

The framework is called Ash. The published npm package is experimental-ash. The CLI binary is ash.

What Ash Prioritizes

• Markdown-first authoring for instructions and procedures • TypeScript where typed runtime behavior matters • Durable message runs and follow-up turns • Inspectable compiled artifacts under .ash/ • Per-agent sandbox with optional authored overrides • A stable HTTP protocol with explicit continuationToken and runId contracts • A runtime model that keeps channels, harnesses, and workflow execution separate

Authored Directory

Authoring Helpers

Every authored directory has a typed helper. Import each from the matching subpath:

| Helper | Subpath | Authored Location |

| defineAgent(...) | experimental-ash | agent.ts, subagents//agent.ts | | defineInstructions(...) | experimental-ash/instructions | instructions.ts (or instructions.md) | | defineTool(...), defineBashTool(...), defineReadFileTool(...), defineWriteFileTool(...), disableTool(...) | experimental-ash/tools | tools/.ts | | defineSkill(...), getSkill(...) | experimental-ash/skills | skills/.ts (or skills/.md) | | defineHook(...) | experimental-ash/hooks | hooks/.ts | | defineChannel(...), POST, GET | experimental-ash/channels | channels/.ts | | ashChannel(...), slackChannel(...), vercelOidc(...) | experimental-ash/channels/ash, /slack, /auth | reused from channels/.ts | | defineSandbox(...) | experimental-ash/sandbox | sandbox.ts (or sandbox/sandbox.ts) | | defineSchedule(...) | experimental-ash/schedules | schedules/.ts (or schedules/.md) | | defineEvalSuite(...) | experimental-ash/evals | evals/.eval.ts |

Runtime accessors live on the subpath that owns the concern:

• getSession() — current session, turn, auth, parent lineage (experimental-ash/context) • getSandbox() — live sandbox handle for the current agent (experimental-ash/sandbox) • getSkill(identifier) — handle for a named skill visible to the current agent (experimental-ash/skills) • getContext(key), requireContext(key), hasContext(key), setContext(key), ensureContext(key, factory) — unified context helpers (experimental-ash/context)

The complete API reference, including types and lower-level runtime primitives, is in ./dist/docs/public/advanced/typescript-api.md.

Tiny Example

agent/instructions.md

agent/tools/get_weather.ts

agent/agent.ts

Quick Start

The wizard scaffolds the project, picks a model, and (for the REPL channel) installs dependencies and starts the dev server for you. To scaffold into the current empty directory, run pnpm create experimental-ash-agent ..

CLI commands:

• ash info — discovery results and compiled artifacts • ash build — compile .ash/ and build the host output • ash start — serve the built .output/ app • ash dev — start the local runtime and REPL

Deploying

Ash is built for Vercel. The runtime is Nitro + Vercel Workflows. Read ./dist/docs/public/advanced/vercel-deployment.md for the deployment path, environment variables, and Vercel-specific configuration.

Read Next

These files ship inside the installed package at node_modules/experimental-ash/dist/docs/public/:

• Full docs index — recommended entry point • Getting Started — install, scaffold, and run locally • Project Layout — every authored directory in depth • agent.ts — agent config reference • TypeScript API — complete define* and runtime helper reference • Vercel Deployment — deploy to production

By authoring concern: Tools · Channels · Hooks · Skills · Sandbox · Workspace · Connections · Subagents · Schedules · Human In The Loop · Evals

By runtime concern: Sessions and Streaming · Session Context · Context Control · Auth and Route Protection · CLI, Build, and Debugging · Instrumentation

Architecture (Internals)

You do not need this section to author an Ash agent — it documents the public HTTP protocol contracts so Ash composes predictably with other systems.

Ash's internal split is:

• the channel normalizes inbound transport, applies auth and delivery policy, and owns continuationToken • the harness does one unit of AI work and returns { session, next } • the runtime persists state, follows next, streams events, and owns workflow primitives (start(), resumeHook(), createHook(), getWritable())

That split is why the public HTTP protocol separates two distinct identifiers:

• continuationToken — channel-owned handle the caller uses to start the next user turn • runId — runtime-owned handle for streaming and inspection

Changelog

See ./CHANGELOG.md for the release history. The changelog ships inside the published package so agents can read it directly from node_modules/experimental-ash/CHANGELOG.md to evaluate upgrades.