Fystash

Fystash lets you create multi-agent sandbox rooms from Convex actions: spawn agents, write a shared drive, exec commands, and destroy rooms programmatically.

Installation

npm install @fystash_ai/convex

Benefits

Orchestrate multi-agent workflows directly from Convex actions without managing external infrastructure
Run fleet operations in a single call using runFleet, or compose granular steps like createRoom, spawn, driveWrite, exec, and destroy
Share a common drive across agents in the same room, enabling agents to read and write shared state during execution
Isolate Fystash API credentials from your app environment by passing them through the component config

Use cases

how to run multiple AI agents from a Convex action

Fystash provides a Convex component that lets you call fystash.runFleet from a Convex action, spawning named agents like 'scout' and 'drafter' into an isolated room. You pass agentIds, a shared drive path and content, an exec command, and optionally set destroyAfter to clean up automatically. The entire multi-agent lifecycle is handled from within the action handler.

how to use a shared file system across AI agents in Convex

The Fystash Convex component includes a driveWrite step that writes content to a path on the room's shared drive before agents execute. All agents spawned into the same room can access this shared drive, so you can pre-populate files like configuration or prompts that multiple agents read during exec.

how to install a Convex component for AI agent sandboxes

Install @fystash_ai/convex and @fystash_ai/sdk, then register the component in convex/convex.config.ts using app.use(fystash, { env: { FYSTASH_API, FYSTASH_API_KEY } }). Set FYSTASH_API and FYSTASH_API_KEY in the Convex dashboard or .env.local, and pass them explicitly through app.use because Convex components are isolated from the app environment.

how to destroy an AI agent room after execution in Convex

When using fystash.runFleet from the Fystash Convex component, you can pass destroyAfter: true to automatically tear down the room after the exec step completes. If you are composing steps manually, call fystash.destroy at the end of your action handler after exec returns.

Frequently asked questions

What does the Fystash Convex component actually do?

The @fystash_ai/convex component wraps the Fystash multi-agent sandbox API and exposes it as a Convex component callable from Convex actions. It lets you create isolated rooms, spawn one or more named agents, write files to a shared drive, execute commands inside the room, and destroy the room when done. All of this happens inside a Convex action handler using the Fystash class.

How do I pass API credentials to the Fystash component?

Convex components are isolated from the parent app's environment, so you cannot rely on process.env directly inside the component. You must pass FYSTASH_API and FYSTASH_API_KEY through the app.use call in convex.config.ts using app.env references. Set the actual values in the Convex dashboard under environment variables, or in .env.local when running convex dev locally.

Can I call individual steps instead of using runFleet?

Yes. The Fystash Convex component exposes individual methods: createRoom, spawn, spawnMany, driveWrite, exec, and destroy. You can call these in sequence from a Convex action if you need finer control over the agent lifecycle, such as conditionally spawning agents or handling exec results before deciding whether to destroy the room.

What packages do I need to install to use Fystash with Convex?

You need both @fystash_ai/convex and @fystash_ai/sdk. The SDK provides the shared FystashSession used internally by the component. Install both with npm i @fystash_ai/convex @fystash_ai/sdk, then register the component in convex/convex.config.ts.

Does Fystash work with Convex queries and mutations or only actions?

Fystash operations involve calling the external Fystash API, which requires network access. In Convex, only actions can call third-party services and external APIs. Fystash component methods must be called from within a Convex action handler, not from queries or mutations.