--- name: bijection-freestyle description: "Evaluate and integrate the Freestyle component with Bijection." --- # Freestyle Sandbox execution - Package: @bijectionhq/freestyle - Category: Sandboxes - Status: Preview - License: MIT - Bijection source (repository access required): https://github.com/bijectionhq/freestyle/tree/635839f04d41b7093b3dc13d30f94d773ff070d3 - Upstream: https://github.com/freestyle-sh/convex/tree/9977e7d052d8127db89832b02c7d541caa2b584f - Documentation: https://docs.bijection.com/components/using - Directory: https://bijection.com/components/freestyle ## Get the source Bijection repository access is required. Request access at https://bijection.com/contact. ```sh git clone https://github.com/bijectionhq/freestyle.git cd freestyle git checkout 635839f04d41b7093b3dc13d30f94d773ff070d3 ``` ## 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 @freestyle-sh/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 Freestyle. Follow the installation and configuration steps exactly. # Freestyle ## Instructions Use Freestyle to manage long-lived linux vms for ai agents from convex actions with reactive state, idempotent creation, and full lifecycle control via @freestyle-sh/convex. This Convex component integrates directly with your backend. ### Installation ```bash npm install @freestyle-sh/convex ``` Current npm version: `@freestyle-sh/convex@0.1.0` ### Capabilities - Provision full Linux VMs with Docker, systemd, and nested virtualization from Convex actions in milliseconds - Keep reactive Convex records of VM state so queries reflect lifecycle changes without manual polling - Recover safely from retried actions using idempotent VM creation with ownership markers tied to your Convex records - Enforce tenant isolation by deriving ownerId from server-side auth, preventing cross-tenant VM access ## Examples ### how to run long-lived AI agent tasks in Convex The @freestyle-sh/convex component lets you provision persistent Linux VMs from Convex actions using freestyle.create(), then exec commands with freestyle.exec(). VMs can be paused and resumed with their memory intact, making them suitable for multi-step agent workflows that exceed Convex action time limits. ### how to manage VM lifecycle state reactively in Convex The Freestyle component caches VM lifecycle and resource state in Convex tables, so freestyle.get() and freestyle.list() work in reactive queries. Call freestyle.refresh() from an action when you need the current remote state synchronized back to Convex. ### how to snapshot and branch VMs for AI agent workflows in Convex The freestyle.snapshot() helper creates a point-in-time copy of a running VM including its memory and disk state. You can then use that snapshot ID when calling freestyle.create() to branch new VMs from a known configured state, enabling workflows like parallel agent runs or rapid failure recovery. ### multi-tenant VM management with Convex components The Freestyle component requires an explicit ownerId on every operation. Derive this value from ctx.auth.getUserIdentity() inside your Convex action or query wrapper rather than accepting it as a client argument. For multi-tenant apps, prefix or hash tenant identifiers into VM slugs because Freestyle slugs are unique account-wide. ## 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 Freestyle is not needed ## Troubleshooting **What kind of Linux capabilities do Freestyle VMs support?** Freestyle VMs are full Linux machines with root access and support for Docker, systemd, nested virtualization, FUSE, eBPF, and full Linux networking. If a workload can run on an EC2 instance, it can run in a Freestyle VM managed through @freestyle-sh/convex. **How does @freestyle-sh/convex handle retried Convex actions during VM creation?** The Freestyle component uses idempotent VM creation by reserving a Convex record first and embedding a random ownership marker in the VM's Freestyle metadata. If a Convex action is retried after the remote VM was created but before the record was linked, the component finds the VM by slug and verifies the marker before linking. A VM with the same slug but a different marker is rejected to prevent accidental adoption. **Do Freestyle VMs persist state when paused?** Yes. Freestyle VMs can be hibernated with their exact memory state preserved and resumed weeks later in that same state. Snapshots also capture both memory and disk, and creating a new VM from a snapshot restores it to the exact state of the original. **Which Freestyle operations must run in Convex actions versus queries?** Mutating operations that make external requests, including create, start, pause, exec, resize, snapshot, refresh, and delete, must run in Convex actions because they call the Freestyle API. The get and list methods read from cached Convex records and can run in reactive queries. **How do you configure the Freestyle API key for @freestyle-sh/convex?** Set the FREESTYLE_API_KEY environment variable on your Convex deployment using npx convex env set FREESTYLE_API_KEY your-api-key. The Freestyle client reads this key by default. You can also pass an explicit apiKey option to the Freestyle constructor to support multiple Freestyle accounts within the same Convex app. ## Resources - [npm package](https://www.npmjs.com/package/%40freestyle-sh%2Fconvex) - [GitHub repository](https://github.com/freestyle-sh/convex) - [Live demo](https://convexstyle.swerdlow.dev) - [Convex Components Directory](https://www.convex.dev/components/freestyle-sh/convex) - [Convex documentation](https://docs.convex.dev)