> ## Documentation Index
> Fetch the complete documentation index at: https://docs.runloop.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Transition from Runloop to Freestyle

> Plan and validate a migration from Runloop devboxes to Freestyle VMs

<Warning>
  This guide maps published APIs and includes a bounded SDK comparison, not a certified migration. Pin versions, run the [Freestyle validation plan](/docs/transitions/runloop-to-freestyle-validation) for your workload, and record evidence before cutover.
</Warning>

Freestyle provides persistent Linux VMs. Runloop IDs, blueprint definitions, snapshot state, and Axon data do not transfer automatically. Plan application-data export and replacement coordination infrastructure alongside VM provisioning.

| Runloop | Freestyle | Required work |
| - | - | - |
| [Devboxes](/docs/devboxes/overview) | [VMs](https://www.freestyle.sh/docs/vms) | Replace provisioning, commands, files, access controls, and lifecycle calls. |
| [Axons](/docs/axons/overview) | Application-owned journal, database, and workers | Implement durable events, replay, subscriptions, turn delivery, and SQL serialization. |
| [Blueprints](/docs/devboxes/blueprints) | [Configured VM snapshots](https://www.freestyle.sh/docs/vms/base-snapshots) | Rebuild an environment in a VM, snapshot it, and reapply runtime policies. |
| [Snapshots](/docs/devboxes/snapshots) | [VM snapshots](https://www.freestyle.sh/docs/vms/base-snapshots) | Export application state, restore it in a new VM, then capture a Freestyle snapshot. |
| Benchmarks (discontinued) | Harbor or your chosen evaluation harness | Confirm a supported provider or implement and validate an adapter. |

## Runloop customer offer

[Redeem the Runloop offer](https://dash.freestyle.sh/redeem/THANKSRUNLOOP) in your Freestyle workspace to receive **\$1,000 in credits plus one month of Hobby**. Credits expire **12 months after redemption**. Review the redemption page and [current plan limits](https://www.freestyle.sh/docs/vms/pricing-and-limits) before choosing your migration resources.

## Prepare the transition

1. Follow the [Freestyle quickstart](https://www.freestyle.sh/docs/quickstart), install the `freestyle` JavaScript SDK, and set `FREESTYLE_API_KEY` for SDK processes. Pin SDK and CLI versions.
2. Inventory devboxes, blueprints, snapshots, mounted and external data, Axon events and [SQL](/docs/axons/sql), Broker integrations, pending work, and evaluation fixtures.
3. Name an owner and agree recovery objectives. Keep only one authoritative writer at each stage, and retain the source integration during validation.
4. Run the [Runloop and Freestyle comparison starter](https://github.com/runloopai/runloop-examples/blob/a7c53b40554ed5e47ae88e313db08a81fecf19e3/transitions/runloop-to-freestyle/compare_core_public.mjs). Its extended mode exercises filesystem fixtures, pause/resume, and snapshot restoration; the [validation plan](/docs/transitions/runloop-to-freestyle-validation) specifies further acceptance checks.

## Devboxes to VMs

Provision with `freestyle.vms.create()` and choose a base `snapshotId`. Record effective resource sizes and policies rather than translating devbox size names. Replace command execution with `vm.exec()` and file operations with `vm.fs`. See [VM operations](https://www.freestyle.sh/docs/vms) and [files](https://www.freestyle.sh/docs/vms/files).

[Runloop named shells](/docs/devboxes/named-shells) preserve context and serialize calls. Do not assume independent Freestyle command calls do the same. Pass working directory and environment explicitly, serialize dependent commands, or validate a persistent [PTY session](https://www.freestyle.sh/docs/vms/pty). Test detachment, reattachment, cancellation, and output framing for interactive workloads.

Freestyle `pause()` saves memory; `start()` resumes existing processes. Runloop [suspend/resume](/docs/devboxes/lifecycle) preserves disk and requires process restart. Remove unconditional startup on Freestyle resume or guard against duplicates. Stopping a persistent Freestyle VM keeps disk but discards memory; deleting destroys the VM. Verify effective idle and deletion policies separately. See [lifecycle](https://www.freestyle.sh/docs/vms/lifecycle).

Recreate networking deliberately: Freestyle requires explicit [firewall allow rules](https://www.freestyle.sh/docs/vms/network/firewall). Use narrow rules for required destinations, including DNS resolution where needed. Public service routing uses [inbound TLS](https://www.freestyle.sh/docs/vms/network/tls-inbound); configure [forward auth](https://www.freestyle.sh/docs/vms/forward-auth) if requests need authorization. Test permitted and denied outbound traffic and anonymous inbound requests before exposing customer services.

**Validate:** Compare exit codes, stdout/stderr, binary and UTF-8 bytes, file modes, symlinks, and representative tasks. Check shell context, cancellation, background processes, process survival, timeout policies, and both sides of each network rule.

## Axons to coordination and event infrastructure

There is no documented like-for-like Freestyle substitute for [Axons](/docs/axons/overview). A persistent VM does not supply durable event ordering, replay, subscriptions, or transactional [Axon SQL](/docs/axons/sql). Choose an append-only journal and your own SQL database; use VM workers for processing and design durable dispatch separately.

Inventory event cursors, SQL schemas, constraints, atomic batches, turn serialization, and [Broker](/docs/axons/broker) wake-up behavior. Persist accepted work before dispatch, deduplicate side effects, and reconcile pending work after worker failure. Replace Broker delivery explicitly; VM network wake-up alone does not implement the Axon protocol. For the final export, freeze publishes and SQL writes and drain or record Broker work. Preserve event sequence and payloads, page every SQL table under its query limit, and verify row counts and content hashes before enabling the target writer. Runloop events and SQL do not share a documented atomic export boundary. Follow the provider-neutral [Axon export procedure](/docs/transitions/runloop-to-tensorlake#axons-to-coordination-and-event-infrastructure), including event pagination and SQL limit checks, and rehearse it on a disposable Axon.

**Validate:** Disconnect and replay ordered events, retry delivery, crash after accepting work, cancel turns, submit concurrent messages, and fail a SQL batch. Require no lost accepted work, no duplicate external effects, and atomic rollback.

## Blueprints to configured snapshots

Start from a [Freestyle base snapshot](https://www.freestyle.sh/docs/vms/base-snapshots), install pinned dependencies, and apply setup commands, files, user, and working directory. Capture a reusable configured snapshot and map each blueprint ID to its Freestyle snapshot ID. This is an environment rebuild; direct blueprint or Dockerfile import is not established by this guide.

Keep runtime secrets out of reusable state. Because Freestyle snapshots include memory as well as disk, inspect running processes and in-memory credentials before capture. Reapply firewall rules, public routes, access grants, resource and lifetime policies when provisioning from the snapshot.

**Validate:** Boot a fresh VM and compare packages, effective user, permissions, startup behavior, and agent versions. Verify required kernel-dependent tools and that reusable state contains no unintended credentials.

## Snapshots to VM snapshots

Direct Runloop snapshot import into Freestyle is unverified. Drain writers, flush filesystem and database writes, record the final event cursor and pending work, then complete a [Runloop disk snapshot](/docs/devboxes/snapshots), restore it into a temporary devbox, and export application directories and a consistent database backup. Preserve checksums, modes, symlinks, and ownership. Verify that no accepted writes occurred after that boundary; reconcile any final delta before enabling the target writer. Transfer through authenticated file workflows and handle mounted and external data separately.

Restore into the rebuilt Freestyle environment and verify application invariants before calling `vm.snapshot()`. Freestyle captures memory and disk from a running or paused VM and returns a ready-to-boot snapshot. Store its ID, event cursor, and pending-work metadata outside the VM; check retention and account limits. See [custom snapshots](https://www.freestyle.sh/docs/vms/base-snapshots).

**Validate:** Restore after source shutdown, compare manifests and database integrity, and verify process behavior. Test failure recovery and retention. A VM snapshot does not make external database writes or side effects atomic.

## Benchmarks to an evaluation harness

The Runloop Benchmark product has been discontinued. Use [Harbor](https://docs.harborframework.com) or your chosen harness, preserving fixtures, scoring, and result artifacts. Check Harbor's [provider list](https://docs.harborframework.com/core-concepts/sandboxes/pre-integrated-sandboxes) for current integration support. This guide does not establish a built-in Freestyle adapter; validate an available adapter or implement one before selecting Freestyle for evaluations.

## Cutover and recovery

Run the [validation matrix](/docs/transitions/runloop-to-freestyle-validation) for every primitive in use. Require explained manifest differences, required access checks passing, durable event and SQL recovery, scoring agreement, and recovery within agreed objectives. Record SDK versions, owners, evidence, and accepted exceptions.

Rehearse a final drain, consistent export, target restore, routing change, and acceptance run. To roll back after target writes, stop target writers, transfer new state and pending work back, reconcile external effects, then restore source routing. Republished Axon events receive new sequence numbers; map IDs and cursors using stable application-level identifiers. Without a tested reverse-transfer path, recovery is limited to the pre-cutover state with an accepted data-loss window.

Runloop is winding down its services. Transition support for existing customers continues through November 13, 2026 at 11:59 PM PT; contact [Runloop support](mailto:support@runloop.ai) for help.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.