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:

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

Team selection for Stack login is:

1. --team <name-or-id>
2. FREESTYLE_TEAM
3. The team set by freestyle team use
4. 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 your domains; .verifications, .mappings, and .certificates sub-namespaces for domain ownership, routing a domain to a VM port, and TLS.
• 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 domain <action>    Point your own domains at a VM, with TLS
  freestyle identity <action>  Scoped access for your end users

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 domain, and freestyle identity mirror their SDK namespaces the same way — run --help on any of them (or any subcommand) to see its options.