Manage long-lived Linux VMs for AI agents from Convex actions with reactive state, idempotent creation, and full lifecycle control via @freestyle-sh/convex.
npm install @freestyle-sh/convexFreestyle VMs are full Linux virtual machines designed for long running, complex tasks.
## Key Features
- **Instant Startup**: Freestyle VMs provision in milliseconds, with p99s under 400ms.
- **Persistence**: Freestyle VMs can run forever, they can be hibernated with their exact memory in place and come back to life weeks later instantly, in that exact state.
- **Powerful**: Freestyle VMs go up to 64GB of RAM for public tiers and much further for enterprise. Freestyle does high quality hardware virtualization supporting nested virtualization, FUSE, eBPF, full Linux networking and more. If it can run in an EC2, it can run in a Freestyle VM.
- **Cheaply Snapshottable and Branchable**: Freestyle VMs are instantly and cheaply snapshottable (sub 1ms interruption, sub 50ms to snapshot ready). These snapshots can be used to create new VMs in the exact state of the original VM (memory and disk). This enables powerful workflows like branching, cloning, and rapid recovery from failures.
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.
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.
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.
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.
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.
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.
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.
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.
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.