Fystash
Fystash Bijection component — Sandbox → Revision → Branch → Run → Evidence from Bijection actions.
git clone https://github.com/bijectionhq/fystash.git
cd fystash
git checkout d7344138c1b1b8173d55a3ca6f247d2a0c5f0041Bijection repository access is required. Request access.
Description
Fystash Bijection component — Sandbox → Revision → Branch → Run → Evidence from Bijection actions.
Explore the package README for API concepts, configuration, and examples. Check the Bijection source for adaptation-specific setup.
Review the source and its dependencies before adopting this package. Source availability does not establish npm publication or runtime qualification.
Getting started
- Get the source at the revision above and read its package documentation.
- Check the required Bijection SDK version, dependencies, and external service credentials.
- Follow the package setup instructions and the guide to using components.
- Exercise the component in your deployment according to your project’s verification rules.
Open source
Maintained source: bijectionhq/fystash. Based on fystash/convex-component. License: Apache-2.0. Consult the repository for license terms, notices, and contributor attribution.
From the upstream publisher
Fystash Convex component — Sandbox → Revision → Branch → Run → Evidence from Convex actions.
Explore the demo ↗Upstream overview
From the upstream package documentation.
The 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.
Use cases
From the upstream package documentation.
- Running automated test suites (e.g., pytest) inside an isolated Fystash sandbox triggered by a Convex action, then collecting pass/fail evidence
- Orchestrating infrastructure plan approval workflows where a sandbox must be started, a plan generated and approved, and the result recorded before teardown
- Integrating Fystash sandbox execution into Convex mutation pipelines where the sandbox result feeds downstream database writes or queries
- Listing previously recorded sandboxes from a Convex query for audit or status display in an application UI
- Using the granular catalog step API (compile, createBranch, plan, approvePlan, apply, waitReady) when finer control over the sandbox lifecycle is required than startSandbox provides
How it works
From the upstream package documentation.
The component is registered in convex/convex.config.ts using app.use(fystash, { env: { ... } }), which explicitly threads FYSTASH_API_URL, FYSTASH_ACCESS_TOKEN, and FYSTASH_PROJECT_ID from the host app's environment into the component's isolated scope. Because Convex components cannot read the host app's environment variables directly, this explicit forwarding is required.
The primary client is instantiated with new Fystash(components.fystash) and used inside Convex actions. The high-level path is startSandbox (requires an approver argument, no silent plan approval) followed by exec, listEvidence, and stop with an outcome value. All sandbox interaction methods are actions because they make outbound HTTP calls to the Fystash public API via @fystash/sdk.
A lower-level catalog API is also available for cases requiring step-by-step control: compile, createBranch, plan, approvePlan, apply, waitReady, exec, listEvidence, and stop. This gives developers explicit control at each stage of the Fystash lifecycle. Listing recorded sandboxes uses fystash.listSandboxes(ctx), which is a Convex query rather than an action since it reads from local state rather than calling the external API.
Upstream package FAQ
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.
Use with agents and CLI
Give your coding agent the component’s source identity and setup guidance.
Help me integrate Fystash with Bijection.
Read: https://bijection.com/components/fystash/SKILL.md
Check SDK compatibility and dependency availability.
Follow this project's execution and verification rules.Upstream README.md
View repository ↗Documentation from fystash/convex-component, recorded October 23, 2026. APIs and setup may differ in the Bijection adaptation.
@fystash/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/convex@0.1.x is deprecated.
Uses @fystash/sdk.
Install
npm i @fystash/convex@^0.2.0 @fystash/sdk
// convex/convex.config.ts
import { defineApp } from "convex/server";
import { v } from "convex/values";
import fystash from "@fystash/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/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/.