@fystash_ai/convex

Convex component for Fystash — start a Sandbox from a Convex action, then exec, list Evidence, and stop.

Canonical lifecycle: Sandbox → Revision → Branch → Run → Evidence.

0.2.0 replaces the scrapped rooms/spawn API. Do not call createRoom, spawn, runFleet, or destroy. @fystash_ai/[email protected] is deprecated.

On npm this package is still @fystash_ai/convex (the Convex directory name). @fystash/convex is the intended rename once the npm org can create a new package.

Uses @fystash/sdk.

Install

npm i @fystash_ai/convex@^0.2.0 @fystash/sdk

// convex/convex.config.ts
import { defineApp } from "convex/server";
import { v } from "convex/values";
import fystash from "@fystash_ai/convex/convex.config.js";

const app = defineApp({
  env: {
    FYSTASH_API_URL: v.optional(v.string()),
    FYSTASH_ACCESS_TOKEN: v.optional(v.string()),
    FYSTASH_PROJECT_ID: v.optional(v.string()),
  },
});
app.use(fystash, {
  env: {
    FYSTASH_API_URL: app.env.FYSTASH_API_URL,
    FYSTASH_ACCESS_TOKEN: app.env.FYSTASH_ACCESS_TOKEN,
    FYSTASH_PROJECT_ID: app.env.FYSTASH_PROJECT_ID,
  },
});
export default app;

Set on the Convex deployment (or .env.local for convex dev):

FYSTASH_API_URL=https://api.fystash.ai/v1
FYSTASH_ACCESS_TOKEN=…
FYSTASH_PROJECT_ID=proj_…

Components are isolated from app env — pass FYSTASH_* through app.use. The component never reads ~/.fystash/credentials.json.

Use

// convex/sandboxes.ts
import { action } from "./_generated/server";
import { components } from "./_generated/api";
import { Fystash } from "@fystash_ai/convex";
import { v } from "convex/values";

const fystash = new Fystash(components.fystash);

export const hello = action({
  args: { manifest: v.string(), approver: v.string() },
  handler: async (ctx, { manifest, approver }) => {
    const sandbox = await fystash.startSandbox(ctx, { manifest, approver });
    const exec = await fystash.exec(ctx, {
      runId: sandbox.runId,
      argv: ["pytest", "-q"],
    });
    const evidence = await fystash.listEvidence(ctx, { runId: sandbox.runId });
    await fystash.stop(ctx, { runId: sandbox.runId, outcome: "succeeded" });
    return { sandbox, exec, evidence };
  },
});

startSandbox requires approver. It will not silently approve a Plan.

Or call the catalog steps: compile → createBranch → plan → approvePlan → apply → waitReady → exec → listEvidence → stop.

Fystash calls are Convex actions (they hit the public API). Listing recorded sandboxes is a query: fystash.listSandboxes(ctx).

Develop (this repo)

npm i
npm run build:codegen

Example app: example/.