Providers

Freestyle Provider

GitHub Edit page

Freestyle Provider

Read when:

  • choosing provider: freestyle;
  • configuring Freestyle VM size or workdir;
  • changing internal/providers/freestyle.

Freestyle is a delegated run provider. Crabbox uses the Freestyle v1 REST API (https://api.freestyle.sh) for VM lifecycle, archive sync, and command execution through pure Go net/http calls. Freestyle owns VM state and exec transport; Crabbox owns local config, repo claims, sync manifests and guardrails, slugs, timing summaries, and normalized list/status rendering.

#When To Use

Use Freestyle when the remote Linux VM should be owned by Freestyle and commands can run through Freestyle's exec API. Use AWS, Hetzner, Static SSH, or Daytona when you need Crabbox SSH access.

#Commands

crabbox warmup --provider freestyle --keep
crabbox run --provider freestyle -- pnpm test
crabbox run --provider freestyle --sync-only
crabbox run --provider freestyle --id blue-lobster --shell 'pnpm install && pnpm test'
crabbox status --provider freestyle --id blue-lobster
crabbox stop --provider freestyle blue-lobster
crabbox list --provider freestyle
crabbox doctor --provider freestyle

#Live Smoke

Use a live smoke when changing Freestyle lifecycle, sync, or exec code. Keep the API key in FREESTYLE_API_KEY; do not pass it as a command-line argument.

export FREESTYLE_API_KEY=...
go build -trimpath -o bin/crabbox ./cmd/crabbox

bin/crabbox run --provider freestyle --keep 'bash test.sh'
bin/crabbox warmup --provider freestyle --actions-runner   # expect exit 2
bin/crabbox doctor --provider freestyle

Expected results:

  • run prints a Freestyle lease (fsb_...), sync summary, command output, and exit=0.
  • warmup --actions-runner is rejected because Freestyle does not register GitHub Actions runners.
  • doctor reports inventory readiness when auth and list calls succeed.

#Auth

export FREESTYLE_API_KEY=...

CRABBOX_FREESTYLE_API_KEY is also accepted and wins over FREESTYLE_API_KEY.

Freestyle API keys must not be passed as CLI flags. Crabbox reads them from environment variables only.

Provider error diagnostics redact the configured API key before display.

FREESTYLE_API_URL, CRABBOX_FREESTYLE_API_URL, or freestyle.apiUrl in the user config can override the default https://api.freestyle.sh. Repository config cannot override this credential destination. Custom endpoints must use HTTPS, except for loopback development URLs. Crabbox refuses cross-origin redirects so the bearer token cannot be forwarded to another origin.

#Config

provider: freestyle
target: linux
freestyle:
  apiUrl: https://api.freestyle.sh
  workdir: crabbox
  # Optional. Omit both to use the Freestyle plan defaults
  # (4 vCPU / 8 GiB / 20 GB). vcpus and memoryGB must each be a
  # power of two. Setting them on a plan without custom-sizing
  # entitlement fails with CUSTOM_SIZING_NOT_ALLOWED.
  vcpus: 4
  memoryGB: 8

Provider flags:

--freestyle-api-url
--freestyle-workdir
--freestyle-vcpus
--freestyle-memory-gb

When Freestyle is selected, decoded negative vcpus or memoryGB values, including explicit negative sizing flags, fail with exit 2 before fresh sandbox creation instead of silently omitting sizing. Existing lease reuse, inspection, and stop do not consume creation sizing. Zero still omits that sizing field, and positive values are passed through for service-side validation. This check does not change the existing YAML/environment decoding rules; it does not make every raw negative YAML or environment value an error.

--freestyle-workdir / freestyle.workdir is interpreted as a relative directory below /workspace. Crabbox rejects absolute paths and .. escapes before workspace preparation and sync.

#Lifecycle

  1. Validate the workdir and prepare a bounded archive before creating a VM; reused VMs are authorized before local preparation.
  2. Store a local lease ID with the fsb_ prefix and a friendly slug.
  3. Upload the prepared archive and synchronize /workspace/<freestyle.workdir> through Crabbox's shared archive transaction.
  4. Execute commands through Freestyle's exec API in that workdir via bash -lc.
  5. Stop deletes the VM and removes the local lease claim.

run --lease-output records the Freestyle lease, reuse/retention state, and matching crabbox stop --provider freestyle --id ... cleanup command for orchestrators that need to inspect or clean up retained VMs later.

Run retention, cleanup, and timing use Crabbox's shared sandbox lifecycle. An automatic VM deletion failure after a successful command returns exit 1, reports a provider failure, and leaves the session and claim available for recovery; it is no longer a warning attached to a successful run. A prior command failure keeps its exit code even when deletion or timing output also fails. Transport and cancellation causes remain inspectable by callers. Setup failures honor --keep-on-failure, reused VMs remain kept, and cleanup uses an uncanceled 30-second budget. Freestyle still owns its HTTP transport, command encoding, and existing claim/reclaim rules.

#Sync

Freestyle advertises archive sync (FeatureArchiveSync). Crabbox supports --sync-only, --force-sync-large, and --no-sync.

Crabbox creates Freestyle VMs with an explicit empty external-port list. No guest service is publicly exposed by default.

When sync.delete is enabled, Crabbox extracts into a staging directory and replaces the retained workspace only after extraction succeeds. Failed uploads leave the prior workspace intact. sync.timeout bounds archive creation, upload, extraction, and replacement. Local manifest planning and VM provisioning are outside that budget; archive creation consumes part of the remaining transfer budget. Fresh runs upload the snapshot prepared before VM creation, even if the checkout changes during provisioning. Timing reports preparation once and separates upload, extraction and cleanup.

File and byte guardrails apply to the complete archive, not only changed files. sync-plan --json previews those same full-archive limits before allocation. The provider also limits compressed archives to 64 MiB, checked before allocation and again by a bounded upload read. --force-sync-large overrides the normal sync guardrails but not this compressed transport limit.

Archive upload tries Freestyle's file API first. When that endpoint is unavailable, Crabbox falls back to chunked base64 upload through exec. Sync still completes through the fallback path. The two attempts use separate temporary paths and publish only after acknowledged upload or successful decoding; shared sync owns extraction and workspace replacement. Failed publication is reported, and bounded cleanup preserves the primary error. An unknown remote write completing after cleanup can still leave its isolated attempt file; it cannot overwrite the archive consumed by the fallback.

Freestyle does not report an instance type. Status leaves serverType empty, matching the inventory type; the VM name remains available in crabbox list.

The raw VM ID, Crabbox VM name, and generated slug shown by crabbox list can identify a VM after local claim state is lost. Read-only status recovery still requires the provider VM name to match Crabbox's canonical crabbox-... form. Reuse and deletion additionally require an exact local claim. To intentionally adopt a canonical VM, persist that claim before stopping it:

crabbox run --provider freestyle --id fsb_vm123 --reclaim --no-sync -- true
crabbox stop --provider freestyle --id fsb_vm123

--reclaim is the explicit operator authorization: canonical name shape alone never reaches Freestyle command or delete operations.

--checksum is not supported because Freestyle uses archive sync rather than Crabbox rsync checksum mode.

#Limitations

  • --actions-runner is not supported for warmup or run.
  • --checksum is not supported.
  • No SSH lease path; this is delegated run only.
  • API keys are env-only; there is no --freestyle-api-key flag.

#Doctor

crabbox doctor --provider freestyle checks auth and lists Crabbox-owned VMs in the Freestyle account. It does not create a VM during the check.