--- name: bijection-fystash description: "Evaluate and integrate the Fystash component with Bijection." --- # Fystash Fystash Bijection component — Sandbox → Revision → Branch → Run → Evidence from Bijection actions. - Package: @bijectionhq/fystash - Category: AI & Agents - Status: Preview - License: Apache-2.0 - Bijection source (repository access required): https://github.com/bijectionhq/fystash/tree/d7344138c1b1b8173d55a3ca6f247d2a0c5f0041 - Upstream: https://github.com/fystash/convex-component/tree/5c54a99856b3dc6adda379981113a9c4ef4837a9 - Documentation: https://docs.bijection.com/components/using - Directory: https://bijection.com/components/fystash ## Get the source Bijection repository access is required. Request access at https://bijection.com/contact. ```sh git clone https://github.com/bijectionhq/fystash.git cd fystash git checkout d7344138c1b1b8173d55a3ca6f247d2a0c5f0041 ``` ## Before using this component Read the package README at the recorded revision for setup, dependencies, and API examples. Upstream documentation describes the original package and may differ from the Bijection adaptation. This is a source candidate for evaluation. Catalog inclusion does not establish npm availability or runtime qualification. Check compatibility with your SDK and deployment before adoption. External providers run their own compute. ## Integration workflow 1. Read the source README and package manifest at the recorded revision. 2. Confirm the required SDK, dependency availability, and runtime compatibility. 3. Follow the component's documented setup and configuration. Never invent an npm install command from a catalog package name. 4. Keep credentials in the project's existing secret store. 5. Follow the project's execution rules for verification and report what was actually checked. ## Original upstream skill The following guidance describes @fystash/convex. Its installation commands and APIs refer to the upstream package. Evaluate compatibility with the Bijection source separately. > Agents: read this skill fully before writing code that uses Fystash. Follow the installation and configuration steps exactly. # Fystash ## Instructions Use Fystash to run fystash ai sandboxes from convex actions: start, exec commands, collect evidence, and stop with a typed typescript client. This Convex component integrates directly with your backend. ### Installation ```bash npm install @fystash/convex ``` Current npm version: `@fystash/convex@0.2.2` ### Capabilities - Manage the full Fystash sandbox lifecycle (Sandbox, Revision, Branch, Run, Evidence) directly from Convex actions without leaving the Convex runtime. - Use either the high-level startSandbox shortcut or granular catalog steps (compile, createBranch, plan, approvePlan, apply, waitReady) depending on control requirements. - Query recorded sandbox history with fystash.listSandboxes without needing a separate data store or external API call. - Pass API credentials through Convex component environment isolation so secrets never leak into app-level environment variables or local credential files. ## Examples ### how to run a Fystash sandbox from a Convex action 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. ### how to execute commands inside a Fystash sandbox from Convex 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. ### how to collect AI evidence from a Fystash run in Convex 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. ### how to use Convex component environment variables with a third-party API 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. ## When NOT to use - When a simpler built-in solution exists for your specific use case - If you are not using Convex as your backend - When the functionality provided by Fystash is not needed ## Troubleshooting **What is the canonical Fystash lifecycle in the Convex component?** 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. **Does startSandbox auto-approve plans?** 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. **Are deprecated API methods from version 0.1.x still available?** 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. **How are Fystash API credentials scoped to avoid leaking into app code?** 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. **Can Fystash sandbox data be queried from Convex without hitting the external API?** 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. ## Resources - [npm package](https://www.npmjs.com/package/%40fystash%2Fconvex) - [GitHub repository](https://github.com/fystash/convex-component) - [Live demo](https://fystash-convex-component.vercel.app) - [Convex Components Directory](https://www.convex.dev/components/fystash/convex) - [Convex documentation](https://docs.convex.dev)