Run Fystash AI sandboxes from Convex actions: start, exec commands, collect evidence, and stop with a typed TypeScript client.
npm install @fystash/convexThe Fystash component wraps the Fystash AI sandbox API for use inside Convex actions, exposing a typed client that manages the full sandbox lifecycle: start, exec, evidence collection, and stop. It handles authentication and API configuration through Convex's component environment system, keeping credentials isolated from the host app. Developers get a structured interface over Fystash's Sandbox, Revision, Branch, Run, and Evidence model without writing raw HTTP calls.
Install @fystash/convex and @fystash/sdk, register the component in convex.config.ts with your FYSTASH_API_URL, FYSTASH_ACCESS_TOKEN, and FYSTASH_PROJECT_ID env vars, then instantiate Fystash with components.fystash. Call fystash.startSandbox(ctx, { manifest, approver }) in any Convex action to provision a sandbox and get back a runId you can use for exec and listEvidence calls.
After startSandbox returns a runId, call fystash.exec(ctx, { runId, argv: ['pytest', '-q'] }) inside the same Convex action. The exec call hits the Fystash public API and returns output you can return from the action or store in Convex tables.
Call fystash.listEvidence(ctx, { runId }) after exec completes to retrieve the Evidence records associated with that Run. When finished, call fystash.stop(ctx, { runId, outcome: 'succeeded' }) to terminate the sandbox and record the outcome.
Convex components are isolated from the app environment, so credentials must be explicitly forwarded through app.use in convex.config.ts. The @fystash/convex component demonstrates this pattern: FYSTASH_API_URL, FYSTASH_ACCESS_TOKEN, and FYSTASH_PROJECT_ID are declared in defineApp and passed into the component via app.use(fystash, { env: { ... } }) so the component can read them without accessing global process.env or local credential files.
The @fystash/convex component follows the lifecycle: Sandbox, Revision, Branch, Run, Evidence. The high-level API compresses this into startSandbox, exec, listEvidence, and stop. For finer control you can call the individual catalog steps: compile, createBranch, plan, approvePlan, apply, waitReady, exec, listEvidence, and stop in sequence.
No. The startSandbox method in @fystash/convex requires an explicit approver argument and will not silently approve a Plan. This is an intentional design constraint to prevent unreviewed infrastructure changes from being applied automatically.
No. Version 0.2.0 of @fystash/convex removes the rooms and spawn API. Calling createRoom, spawn, runFleet, or destroy will fail. The @fystash_ai/convex@0.1.x package is deprecated and should be replaced with @fystash/convex@^0.2.0.
Convex components run in an isolated environment and cannot read from the parent app's environment variables directly. The @fystash/convex component requires you to declare FYSTASH_API_URL, FYSTASH_ACCESS_TOKEN, and FYSTASH_PROJECT_ID in defineApp and forward them explicitly through app.use. The component never reads from ~/.fystash/credentials.json or any global credential store.
Yes. The @fystash/convex component exposes fystash.listSandboxes(ctx) as a Convex query, meaning it reads from Convex's database rather than making an external HTTP call. Exec and listEvidence calls are Convex actions because they contact the Fystash public API.