freestyle

freestyle

TypeScript SDK and CLI for the Freestyle API: create and manage VMs, snapshots, private networks (VPCs), domains, and identities.

Both the SDK and the freestyle CLI ship from this one package and talk to the same public API — everything under https://api.freestyle.sh/v5 (see /openapi.json for the underlying HTTP contract). The /v5 prefix is added for you; resource paths stay unversioned throughout the SDK.

Install

Install the CLI, which targets https://beta-api.freestyle.sh:

npm install --global freestyle@latest

Or run it without installing:

npx freestyle@latest vm list

As of 0.2.0 this package is the latest dist-tag — freestyle@beta is now only the prerelease channel (see "Publishing a beta" below).

For SDK use within a project:

npm install freestyle@latest

Publishing a beta

After authenticating to npm as a maintainer of the freestyle package:

npm run publish:beta

The release script typechecks and builds the package, then publishes the prerelease under the beta dist-tag. It does not change latest.

For local, interactive use, authenticate through Stack Auth:

freestyle login                  # opens the Stack CLI authorization page
freestyle login --no-browser     # prints the URL without opening a browser
freestyle whoami              # shows the user and effective team
freestyle team list           # refresh and list accessible teams
freestyle team current        # show the effective active team
freestyle team use dev        # switch by unique team name or ID
freestyle vm list --team prod # override for one command
freestyle logout                 # remove the stored Stack login

The CLI stores the Stack refresh token and team preference in ~/.freestyle/config.json (mode 0600). Commands refresh a short-lived Stack access token; the v2 gateway resolves the selected Freestyle team during HTTP requests and WebSocket handshakes. Login does not create a permanent API key.

Use a permanent API key from the dashboard for CI and other non-interactive automation. Credential precedence is:

• --api-key <key> on the command line
• FREESTYLE_API_KEY in the real environment
• FREESTYLE_API_KEY in a .env file in the current directory
• The stored Stack login

Team selection for Stack login is:

• --team <name-or-id>
• FREESTYLE_TEAM
• The team set by freestyle team use
• The server default selected during browser authorization

When more than one team remains and no default is available, interactive login prompts; non-interactive commands fail and require --team.

--proxy (to point at a non-default API base URL) works the same way via FREESTYLE_PROXY. The SDK's Freestyle constructor only honors apiKey/ FREESTYLE_API_KEY from the real environment — it doesn't read .env files; that's a CLI-only convenience, so load one yourself (e.g. with dotenv) if you want it in your own code.

SDK

import { Freestyle } from "freestyle";

const freestyle = new Freestyle({ apiKey: process.env.FREESTYLE_API_KEY });

const { vm, vmId } = await freestyle.vms.create();
const { stdout } = await vm.exec("echo hello from the VM");
console.log(stdout);

await vm.fs.writeTextFile("/root/hello.txt", "hi");
console.log(await vm.fs.readTextFile("/root/hello.txt"));

const session = await vm.pty.open({
  onData: (bytes) => process.stdout.write(Buffer.from(bytes)),
  onExit: (code) => console.log("shell exited", code),
});
session.write("ls -la\n");

await vm.delete();

Namespaces

• freestyle.vms — create/list/get/delete VMs; freestyle.vms.snapshots for snapshot management. vms.ref(id) returns a Vm handle with start/pause/resize/update/delete/exec/snapshot, plus .fs (guest filesystem) and .pty (interactive terminal WebSockets).
• freestyle.vpc — create/list/get/delete private networks. vpc.ref(id) returns a Vpc handle with .wireguard for ephemeral or public-key WireGuard tunnels into the network.
• freestyle.domains — list the domains you hold; .verifications and .certificates sub-namespaces for proving ownership of a domain and for its TLS certificates.
• freestyle.tls — TLS rules: publish a domain to a VM port, inject a secret into a VM's outbound calls, reach another VM by name. Any unused subdomain of style.dev is free to take and needs no verification.
• freestyle.identities — scoped access for your end users. identities.ref(id) returns an Identity handle with .tokens and .permissions.vm for per-VM access grants.

Every namespace method and Vm/Vpc/Identity handle method returns a plain typed object (or void for deletes) — nothing is wrapped in an envelope. Errors are thrown as FreestyleApiError (.code, .message, .status).

An identity access token (rather than an API key) can also authenticate, scoped to one VM's exec/PTY routes:

const freestyle = new Freestyle({ identityAccessToken: token });

CLI

freestyle <command>

Commands:
  freestyle vm <action>        Manage Virtual Machines
  freestyle snapshot <action>  Create and manage snapshots
  freestyle vpc <action>       Manage private networks
  freestyle tunnels <action>   Manage tunnels into private networks
  freestyle firewall <action>  Manage firewall rules
  freestyle tls <action>       Manage TLS rules — publish domains to VMs, inject secrets, connect VMs by name
  freestyle domain <action>    Verify domains and manage their TLS certificates
  freestyle identity <action>  Scoped access for your end users
  freestyle skill <action>     Install the Freestyle docs as an agent skill (freestyle-docs)

Options:
      --api-key  Freestyle API key (defaults to $FREESTYLE_API_KEY)  [string]
      --team     team name or ID (defaults to $FREESTYLE_TEAM)       [string]
      --proxy    override the base url for the freestyle api        [string]
  -h, --help     Show help                                         [boolean]
  -v, --version  Show version number                               [boolean]

freestyle vm <action>

Commands:
  freestyle vm create                      Create a new VM (or just `freestyle vm`)
  freestyle vm list                        List all VMs
  freestyle vm get <vmId>                  Fetch a VM
  freestyle vm update <vmId>               Rename a VM, change its slug or idle timeout, or merge in metadata
  freestyle vm start <vmId>                Boot a stopped VM, or resume a paused one
  freestyle vm pause <vmId>                Freeze a running VM, keeping its memory
  freestyle vm resize <vmId>               Change a VM's vCPU, memory, or disk (grow-only)
  freestyle vm delete <vmId>               Delete a VM
  freestyle vm exec <vmId> <command..>     Execute a command on a VM
  freestyle vm ssh <vmId>                  SSH into a VM
  freestyle vm scp <source> <destination>  Copy files or directories to or from
                                            a VM (use '<vmId>:<path>' for the
                                            remote side)
  freestyle vm snapshot <action>           Manage snapshots
  freestyle vm fs <action>                 Read and write files inside a VM

At a terminal, vm create opens a shell in the new VM; --no-ssh prints the record instead. Scripts, CI, and coding agents get the record.

freestyle snapshot <action>

Commands:
  freestyle snapshot create [vmId]         Build a snapshot: set up a fresh VM by hand
                                            or with a script, then capture it
  freestyle snapshot list                  List your snapshots
  freestyle snapshot get <snapshotId>      Fetch a snapshot
  freestyle snapshot update <snapshotId>   Rename a snapshot or change its slug
  freestyle snapshot delete <snapshotId>   Delete a snapshot permanently

Without a vmId, snapshot create boots a VM, opens a shell in it (or runs --script ./setup.sh, streamed to your terminal), captures it, and deletes the VM. Ctrl-C, or a script that exits non-zero, deletes the VM and takes no snapshot.

Every command prints the API's JSON response to stdout (pretty-printed) so it composes with jq; delete-type commands print a one-line confirmation instead. vm exec streams stdout/stderr directly and exits with the guest's own status code.

freestyle vpc, freestyle tls, freestyle domain, and freestyle identity mirror their SDK namespaces the same way — run --help on any of them (or any subcommand) to see its options.

freestyle skill install needs no login. It takes the skill published in onboard.md and writes it into the skills directory of every coding agent it detects on the machine (Claude Code, Codex, GitHub Copilot; --agent picks, --project installs into the current repository instead of your home directory).