@decocms/sandbox-controller 0.6.0 → 0.7.0

package/dist/index.d.ts

@@ -60,6 +60,15 @@ interface Sandbox {
     warmPoolAdopted: boolean;
     /** Where the sandbox runs. */
     provider: SandboxProviderKind;
+    /** Why it runs there, when `SandboxProviderRouter` had a choice to make. */
+    placement?: SandboxPlacement;
+}
+declare const SANDBOX_PLACEMENT_REASONS: readonly ["existing", "requested", "split", "capacity", "fallback", "image", "warm-pool", "freestyle-unavailable"];
+type SandboxPlacementReason = (typeof SANDBOX_PLACEMENT_REASONS)[number];
+interface SandboxPlacement {
+    reason: SandboxPlacementReason;
+    /** The provider whose ensure failed, when `reason` is `fallback`. */
+    fallbackFrom?: SandboxProviderKind;
 }
 /** When omitted, no dev server is started; the default tool image is used. */
 interface Workload {
@@ -490,6 +499,22 @@ declare const ensureOutputSchema: z.ZodObject<{
         kubernetes: "kubernetes";
         freestyle: "freestyle";
     }>>;
+    placement: z.ZodCatch<z.ZodOptional<z.ZodObject<{
+        reason: z.ZodEnum<{
+            existing: "existing";
+            requested: "requested";
+            split: "split";
+            capacity: "capacity";
+            fallback: "fallback";
+            image: "image";
+            "warm-pool": "warm-pool";
+            "freestyle-unavailable": "freestyle-unavailable";
+        }>;
+        fallbackFrom: z.ZodOptional<z.ZodEnum<{
+            kubernetes: "kubernetes";
+            freestyle: "freestyle";
+        }>>;
+    }, z.core.$strip>>>;
     daemon: z.ZodObject<{
         url: z.ZodURL;
         token: z.ZodString;
@@ -1310,6 +1335,2364 @@ interface TenantPoolReader {
 /** A cached pool list for `AgentSandboxProvider`'s `tenantPools`; a failed load keeps the last one. */
 declare function tenantPoolReader(store: Pick<TenantPoolStore, "list">, cluster: string, { refreshMs }?: TenantPoolReaderOptions): TenantPoolReader;
 
+/** Options every credential mode shares. */
+interface TransportOptions {
+    baseUrl?: string;
+    /**
+     * Transport to use instead of the built-in one, which speaks HTTP/2 on Node
+     * and defers to the runtime's `fetch` everywhere else. Pass one to route
+     * through a proxy, size the connection pool yourself, or add retries.
+     */
+    fetch?: typeof fetch;
+}
+type FreestyleOptions = ({
+    apiKey?: string;
+    identityAccessToken?: never;
+} & TransportOptions) | ({
+    identityAccessToken: string;
+    apiKey?: never;
+} & TransportOptions) | ({
+    /** Stack access token used by the CLI; resolved to `teamId` at the gateway. */
+    stackAccessToken: string;
+    teamId: string;
+    apiKey?: never;
+    identityAccessToken?: never;
+} & TransportOptions);
+/** `undefined`/`null` query values are dropped; everything else is stringified. */
+type QueryValue = string | number | boolean | undefined | null;
+/**
+ * Thin HTTP client for the Freestyle public API: attaches the configured
+ * credential, resolves the base URL, and turns non-2xx responses into
+ * {@link FreestyleApiError}.
+ *
+ * Every request runs as a background request: the API detaches the work from
+ * the HTTP connection, so a call that outlives the connection (a long
+ * snapshot materialization, a cold VM boot — including one triggered by a
+ * read that wakes the VM, a client/proxy timeout) still runs to completion.
+ * Calls that finish within a few seconds return inline exactly as usual;
+ * longer ones answer `202 Accepted` and the client transparently polls
+ * `GET /v5/background-requests/{id}` until the result — same value, same
+ * errors — is ready. If a finished result was too large to store (the API
+ * caps stored bodies), idempotent GETs are re-fetched once directly: by then
+ * the slow part (e.g. waking the VM) has already happened. Identity-token
+ * clients are the one exception: their scope cannot reach the poll route,
+ * so none of their requests are backgrounded.
+ */
+declare class FreestyleClient {
+    readonly baseUrl: string;
+    private readonly authenticationHeaders;
+    private readonly fetchImpl;
+    /** Identity-token callers cannot poll `/v5/background-requests`, so their requests are never backgrounded. */
+    private readonly backgroundEligible;
+    constructor(options?: FreestyleOptions);
+    /** Headers this client authenticates every request with, e.g. for a raw WebSocket handshake. */
+    authHeaders(): Record<string, string>;
+    /** Absolute URL for an API path, e.g. `/v5/vms/{id}` → `https://.../v5/vms/{id}`. */
+    url(path: string, query?: Record<string, QueryValue>): string;
+    /**
+     * Low-level escape hatch: an authenticated `fetch` against the API, relative
+     * to `baseUrl`. Pass the whole path, `/v5` included — the same paths the
+     * methods above use, and the same ones the API declares. It is also how the
+     * client follows a server-supplied URL (a 202's `resultUrl`), and the only
+     * way to reach the unversioned `/status` and `/openapi.json`.
+     */
+    fetch(path: string, init?: RequestInit): Promise<Response>;
+    /** A path or URL as this client's `fetch` resolves it: absolute URLs are
+     * followed as given, everything else hangs off `baseUrl` with no version
+     * segment added — the caller already supplied whatever version it wants. */
+    private absoluteUrl;
+    private request;
+    /**
+     * Follow a 202 from a backgrounded request: poll its result URL until the
+     * stored response — success or error, identical to what the inline call
+     * would have produced — is ready.
+     */
+    private pollBackgroundRequest;
+    /** Turn a terminal API response into the call's value, or throw its error. */
+    private finalize;
+    get<T>(path: string, query?: Record<string, QueryValue>): Promise<T>;
+    post<T>(path: string, body?: unknown): Promise<T>;
+    patch<T>(path: string, body?: unknown): Promise<T>;
+    put<T>(path: string, body?: unknown): Promise<T>;
+    putEmpty<T>(path: string): Promise<T>;
+    /** PUT raw bytes as `application/octet-stream`: a whole file, or one chunk of one. */
+    putBytes<T>(path: string, rawBody: Uint8Array | Blob, query?: Record<string, QueryValue>, signal?: AbortSignal): Promise<T>;
+    /**
+     * GET a response whose body is bytes rather than JSON, returned unread so the
+     * caller can stream it. Errors still surface as {@link FreestyleApiError}.
+     */
+    getBytes(path: string, query?: Record<string, QueryValue>, init?: {
+        range?: string;
+        signal?: AbortSignal;
+    }): Promise<Response>;
+    delete<T = void>(path: string, query?: Record<string, QueryValue>): Promise<T>;
+}
+
+type VerificationState = "pending" | "verified";
+interface DomainVerification {
+    id: string;
+    domain: string;
+    verificationCode: string;
+    /** Place `verificationCode` in a TXT record at this name, then verify. */
+    recordName: string;
+    state: VerificationState;
+    /** When this challenge proved control; null while pending. */
+    verifiedAt: string | null;
+    createdAt: string;
+}
+interface DomainOwnership {
+    domain: string;
+    createdAt: string;
+}
+/** A successful verification: ownership, plus which challenge proved it. */
+interface DomainVerified {
+    domain: string;
+    createdAt: string;
+    verifiedBy: string;
+}
+interface CertificateInfo {
+    domain: string;
+    wildcard: boolean;
+    active: boolean;
+    notAfter: string;
+    generation: number;
+}
+/**
+ * What your placeholder pages wear. A placeholder page is the edge's 404 for
+ * a hostname under one of your verified domains that none of your TLS rules
+ * serve; it reloads itself until a route appears.
+ */
+interface PlaceholderBranding {
+    /** An https URL of the logo. The visitor's browser loads it directly. */
+    logoUrl: string;
+    /** Named on the page in place of Freestyle; null = logo only. */
+    productName: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+interface SetPlaceholderBrandingOptions {
+    /** An https URL of the logo, at most 2048 characters. */
+    logoUrl: string;
+    /** Named on the page in place of Freestyle, at most 64 characters. Omit for logo only. */
+    productName?: string;
+}
+interface ListVerificationsOptions {
+    /** Narrow to one state. Omit for every challenge the account holds, verified records included. */
+    state?: VerificationState;
+}
+/** The `freestyle.domains` namespace. */
+declare class DomainsNamespace {
+    private readonly client;
+    readonly verifications: DomainVerificationsNamespace;
+    readonly certificates: DomainCertificatesNamespace;
+    /** The branding on the 404 page for hostnames under your domains that nothing serves. */
+    readonly placeholder: DomainPlaceholderNamespace;
+    constructor(client: FreestyleClient);
+    /**
+     * List the domains you hold: those you verified, and any Freestyle
+     * subdomain you have taken by publishing it.
+     */
+    list(): Promise<DomainOwnership[]>;
+}
+declare class DomainVerificationsNamespace {
+    private readonly client;
+    constructor(client: FreestyleClient);
+    /**
+     * Issue a challenge. Publish the returned `verificationCode` as a TXT
+     * record at `recordName`, then `complete()` it.
+     */
+    create(domain: string): Promise<DomainVerification>;
+    list(options?: ListVerificationsOptions): Promise<DomainVerification[]>;
+    /** Fetch a verification challenge by its id or its domain. */
+    get(domainOrId: string): Promise<DomainVerification>;
+    /**
+     * Check DNS and record ownership. Addressed by id, only that challenge's
+     * own code counts; use this when several people are verifying the same
+     * domain.
+     */
+    complete(domainOrId: string): Promise<DomainVerified>;
+    /**
+     * Withdraw outstanding challenges; by domain this drops all of them. A
+     * challenge that already verified is a permanent record and cannot be
+     * deleted.
+     */
+    delete(domainOrId: string): Promise<void>;
+}
+declare class DomainCertificatesNamespace {
+    private readonly client;
+    constructor(client: FreestyleClient);
+    list(): Promise<CertificateInfo[]>;
+    /**
+     * Request an ongoing `*.domain` certificate. Requires
+     * `_acme-challenge.<domain>` to be NS-delegated to Freestyle's
+     * nameservers, since wildcards can only be proven over DNS.
+     */
+    createWildcard(domain: string): Promise<CertificateInfo>;
+}
+/** The `freestyle.domains.placeholder` namespace. */
+declare class DomainPlaceholderNamespace {
+    private readonly client;
+    constructor(client: FreestyleClient);
+    /** Your placeholder branding, or `null` when pages carry the Freestyle default. */
+    get(): Promise<PlaceholderBranding | null>;
+    /**
+     * Set the branding for every placeholder page under your verified domains,
+     * including domains you verify later. Replaces any earlier setting.
+     */
+    set(options: SetPlaceholderBrandingOptions): Promise<PlaceholderBranding>;
+    /** Remove your branding; pages go back to the Freestyle default. */
+    delete(): Promise<void>;
+}
+
+/** The transport a matcher is restricted to. */
+type FirewallProtocol = "tcp" | "udp" | "icmp";
+/**
+ * What a rule does with the traffic it matches.
+ *
+ * Only `allow` exists today, and every rule states it rather than defaulting:
+ * a default would mean that the day `deny` arrives, every rule written before
+ * it silently acquires an action it never stated — and "what does this rule
+ * do" is the one question a firewall rule must never answer by omission.
+ */
+type FirewallAction = "allow";
+/**
+ * One end of a rule: which traffic this side matches.
+ *
+ * Fields intersect. `{ vpcId: "vpc-db", port: 5432, protocol: "tcp" }` is
+ * "traffic in that network, on 5432, over TCP" — not three alternatives.
+ *
+ * Matchers select two different ways. `vmId`/`vpcId`/`tunnelId` select by
+ * **identity**: they match that resource however it is addressed. `cidr`/
+ * `public` select by **address**: `public: true` is every publicly routable
+ * address, whoever owns it — another Freestyle VM reached at its public address
+ * is reached over the public Internet like any other host. The two overlap, and
+ * allow rules union, so that is simply more traffic allowed.
+ *
+ * The public Internet is `public: true`, never an empty matcher. An empty
+ * matcher is the absence of a statement, and that is what
+ * {@link VmFirewallSpec} uses to mean "the VM being created"; if emptiness
+ * also meant the Internet, the most dangerous rule you can write would be the
+ * one you get by forgetting a field.
+ *
+ * New selectors arrive as new optional fields, so this type only ever grows.
+ */
+interface FirewallEndpoint {
+    /** A single VM, by id or by your slug for it. Answers hold its id. */
+    vmId?: string;
+    /** Everything on one private network, by id or by your slug for it. Answers hold its id. */
+    vpcId?: string;
+    /**
+     * Whatever is on the far side of one tunnel — the client that dials it, and
+     * any remote range routed over it. Tunnels have no slug, so this is a tunnel
+     * id: `tun-…`, or `wg-…` for one carried over from the per-VPC VPN records
+     * tunnels replaced.
+     *
+     * The one selector that names traffic arriving from outside the platform by
+     * identity rather than by address: the peer's addresses are the peer's
+     * business, and can change without the rules admitting it changing too.
+     */
+    tunnelId?: string;
+    /** An address range, IPv4 or IPv6, in canonical `network/prefix` form. */
+    cidr?: string;
+    /**
+     * Every publicly routable address, whoever owns it — including another
+     * Freestyle VM reached at its public address. Only `true` is meaningful —
+     * omit the field otherwise — and it is not combined with `vmId` or `vpcId`.
+     */
+    public?: true;
+    /** A single port, 1–65535. Requires {@link FirewallEndpoint.protocol}. */
+    port?: number;
+    protocol?: FirewallProtocol;
+}
+/**
+ * A resource a rule cannot outlive. Deleting the resource deletes the rule, so
+ * no rule is ever left naming something that no longer exists.
+ */
+interface FirewallDependency {
+    /** `"vm"`, `"vpc"`, or `"tunnel"` today; new selectors add new kinds. */
+    kind: string;
+    id: string;
+    /**
+     * Your handle for the named resource, when it has one — so a rule can say
+     * what it points at without a lookup per id.
+     */
+    slug?: string | null;
+    /** Your label for the named resource, under the same rules as `slug`. */
+    displayName?: string | null;
+}
+/** An allowed path through the network: traffic matching `source` may reach `destination`. */
+interface FirewallRuleData {
+    id: string;
+    action: FirewallAction;
+    source: FirewallEndpoint;
+    destination: FirewallEndpoint;
+    description?: string | null;
+    /** What this rule dies with. See {@link FirewallDependency}. */
+    dependencies: FirewallDependency[];
+    createdAt: string;
+    updatedAt: string;
+}
+interface CreateFirewallRuleOptions {
+    /** Required. `"allow"` is the only accepted value. */
+    action: FirewallAction;
+    source: FirewallEndpoint;
+    destination: FirewallEndpoint;
+    /** A free-form note, up to 1024 characters. */
+    description?: string;
+}
+/**
+ * A rule declared inside a create, where the resource being created has no id
+ * yet.
+ *
+ * Exactly one endpoint may be left without an identity; that one *is* the new
+ * VM. So `{ source: { public: true }, destination: { port: 443, protocol:
+ * "tcp" } }` is inbound HTTPS to it, and `{ source: {}, destination: { public:
+ * true, port: 443, protocol: "tcp" } }` is outbound HTTPS from it.
+ */
+type InlineFirewallRule = CreateFirewallRuleOptions;
+/** The `firewall` block of a create. */
+interface FirewallSpec {
+    rules: InlineFirewallRule[];
+}
+interface ListFirewallRulesOptions {
+    /**
+     * Rules that apply to this VM: those naming it, plus those naming a private
+     * network it is attached to.
+     */
+    vmId?: string;
+    /** Rules naming this private network. */
+    vpcId?: string;
+    /** Rules naming this tunnel, by its id. */
+    tunnelId?: string;
+    limit?: number;
+    offset?: number;
+}
+interface ListFirewallRulesResult {
+    /** Newest first. */
+    rules: FirewallRuleData[];
+    totalCount: number;
+}
+/** One end of a connection to ask about: everything true about the party. */
+interface TrafficParty {
+    /**
+     * Freestyle's own ingress — the web proxy serving a mapped domain, or the
+     * SSH proxy. Always allowed, whatever your rules say.
+     */
+    platform?: boolean;
+    vmId?: string;
+    /** Every private network this party is on; a rule naming one of them matches. */
+    vpcIds?: string[];
+    tunnelId?: string;
+    /** The address in use, when there is one — what `cidr` rules are tested against. */
+    address?: string;
+    /** Whether that address is publicly routable — what `public: true` matches. */
+    public?: boolean;
+    port?: number;
+}
+/** A connection to decide about. */
+interface TrafficDescription {
+    source: TrafficParty;
+    destination: TrafficParty;
+    protocol?: FirewallProtocol;
+}
+/**
+ * Why a connection would be allowed, or that it would not.
+ *
+ * `allowedByPlatform` means Freestyle itself delivered it — a mapped domain,
+ * an SSH session — which no rule can block. `allowedByRule` names the rule.
+ * `deniedByPlatform` runs the other way: platform policy closed the connection
+ * and no rule opens it — today, outbound mail, which goes through an `smtp`
+ * TLS rule instead.
+ */
+type FirewallDecision = {
+    outcome: "allowedByPlatform";
+    side: "source" | "destination" | "both";
+} | {
+    outcome: "allowedByRule";
+    ruleId: string;
+} | {
+    outcome: "deniedByPlatform";
+    reason: "outboundMail";
+} | {
+    outcome: "denied";
+};
+/** Firewall rules: `freestyle.firewall.rules`. */
+declare class FirewallRulesNamespace {
+    private readonly client;
+    constructor(client: FreestyleClient);
+    /**
+     * Allow traffic from one place to another.
+     *
+     * @example
+     * // Public Internet -> a VM, on HTTPS.
+     * await freestyle.firewall.rules.create({
+     *   action: "allow",
+     *   source: { public: true },
+     *   destination: { vmId: "vm-123456", port: 443, protocol: "tcp" },
+     * });
+     *
+     * @example
+     * // One private network -> another, on Postgres.
+     * await freestyle.firewall.rules.create({
+     *   action: "allow",
+     *   source: { vpcId: "vpc-frontend" },
+     *   destination: { vpcId: "vpc-backend", port: 5432, protocol: "tcp" },
+     * });
+     *
+     * @throws {FirewallRuleValidationError} before any request, when the rule
+     * cannot be well formed.
+     */
+    create(options: CreateFirewallRuleOptions): Promise<FirewallRuleData>;
+    /**
+     * List your rules, newest first. Pass `vmId` for the rules that apply to one
+     * VM — those naming it, plus those naming a private network it is on.
+     */
+    list(options?: ListFirewallRulesOptions): Promise<ListFirewallRulesResult>;
+    get(ruleId: string): Promise<FirewallRuleData>;
+    /** Delete a rule. The resources it named are untouched. */
+    delete(ruleId: string): Promise<void>;
+}
+/** The `freestyle.firewall` namespace. */
+declare class FirewallNamespace {
+    private readonly client;
+    readonly rules: FirewallRulesNamespace;
+    constructor(client: FreestyleClient);
+    /**
+     * Ask whether a connection would be allowed, without changing anything.
+     *
+     * Useful for checking a rule set before you rely on it — and for confirming
+     * what you already believe, e.g. that a mapped domain reaches a VM with no
+     * rules at all.
+     *
+     * @example
+     * // A mapped domain: allowed whatever your rules say.
+     * await freestyle.firewall.evaluate({
+     *   source: { platform: true },
+     *   destination: { vmId: "vm-123456", port: 3000 },
+     *   protocol: "tcp",
+     * });
+     * // => { outcome: "allowedByPlatform", side: "source" }
+     */
+    evaluate(traffic: TrafficDescription): Promise<FirewallDecision>;
+}
+
+interface IdentityData {
+    id: string;
+    managed: boolean;
+}
+interface IdentityInfo {
+    id: string;
+    accountId: string;
+    managed: boolean;
+}
+interface CreatedToken {
+    id: string;
+    /** Returned once, in full. */
+    token: string;
+}
+interface AccessTokenInfo {
+    id: string;
+}
+interface ListIdentitiesResult {
+    identities: IdentityData[];
+    total: number;
+}
+interface ListIdentitiesOptions {
+    limit?: number;
+    offset?: number;
+    includeManaged?: boolean;
+}
+interface VmPermission {
+    id: string;
+    identityId: string;
+    vmId: string;
+    allowedLinuxUsers: string[] | null;
+    grantedAt: string;
+    grantedBy: string;
+}
+interface GrantVmPermissionOptions {
+    vmId: string;
+    /** Restrict the grant to these Linux users; omit (or null) for unrestricted access. */
+    allowedLinuxUsers?: string[] | null;
+}
+/** An identity's access tokens: `identity.tokens`. */
+declare class IdentityTokensNamespace {
+    private readonly client;
+    private readonly basePath;
+    constructor(client: FreestyleClient, basePath: string);
+    /** Mint an access token for the identity. */
+    create(): Promise<CreatedToken>;
+    list(): Promise<AccessTokenInfo[]>;
+    revoke(tokenId: string): Promise<void>;
+}
+/** An identity's per-VM permission grants: `identity.permissions.vm`. */
+declare class IdentityVmPermissionsNamespace {
+    private readonly client;
+    private readonly basePath;
+    constructor(client: FreestyleClient, basePath: string);
+    /** List the VMs this identity has been granted access to. */
+    list(): Promise<VmPermission[]>;
+    /** Grant this identity access to a VM. */
+    grant(options: GrantVmPermissionOptions): Promise<VmPermission>;
+    /** Fetch this identity's grant on a VM. */
+    get(vmId: string): Promise<VmPermission>;
+    /** Change which Linux users this identity may act as on a VM. */
+    update(vmId: string, allowedLinuxUsers: string[] | null): Promise<VmPermission>;
+    /** Revoke this identity's access to a VM. */
+    revoke(vmId: string): Promise<void>;
+}
+/** A handle to one identity. */
+declare class Identity {
+    readonly id: string;
+    readonly tokens: IdentityTokensNamespace;
+    readonly permissions: {
+        vm: IdentityVmPermissionsNamespace;
+    };
+    private readonly client;
+    private readonly basePath;
+    constructor(client: FreestyleClient, id: string);
+    data(): Promise<IdentityInfo>;
+    /** Delete the identity, along with its tokens and grants. Managed identities cannot be deleted. */
+    delete(): Promise<void>;
+}
+/** The `freestyle.identities` namespace: scoped access for your end users. */
+declare class IdentitiesNamespace {
+    private readonly client;
+    constructor(client: FreestyleClient);
+    /** Create an identity. */
+    create(options?: {
+        managed?: boolean;
+    }): Promise<{
+        identity: Identity;
+        identityId: string;
+        data: IdentityData;
+    }>;
+    list(options?: ListIdentitiesOptions): Promise<ListIdentitiesResult>;
+    get(identityId: string): Promise<IdentityInfo>;
+    /** A handle to an identity, without a network call. */
+    ref(identityId: string): Identity;
+    delete(identityId: string): Promise<void>;
+}
+
+/**
+ * How the edge treats the session's bytes.
+ *
+ * **`http` is the default.** A rule without a protocol is HTTP; the edge
+ * terminates the session so a {@link TlsTransform} (header injection) can act on
+ * it.
+ *
+ * `postgres` is served on **5432**. Two shapes use it. **Ingress** publishes a
+ * database by name: the edge terminates the TLS your certificate covers and
+ * splices the session to the VM's Postgres port, so your own server still
+ * authenticates the client end to end. **Egress** is the interesting one — with a
+ * {@link PostgresTransform} the guest connects to a vendor's database with *no
+ * password at all*, and the edge completes the real handshake upstream
+ * (SCRAM-SHA-256, MD5, or cleartext) with credentials the guest has never held.
+ * Connect with `sslmode=require` or stricter: an unencrypted session offers no
+ * SNI, and the name is what selects a rule.
+ *
+ * `minecraft` is served on **25565** for Minecraft: Java Edition. The edge reads
+ * the server address out of the client's handshake — the routing key, exactly as
+ * `Host` is over HTTP — and then splices the session through to the VM. Point the
+ * domain's A/AAAA records at the edge as you would for a web domain and players
+ * dial it directly; no SRV record is needed while they use the default port. It
+ * terminates nothing, so it carries no transform and needs no certificate. A
+ * **status ping** (the multiplayer list) never starts a stopped VM — it is
+ * answered with a "sleeping" line instead; a player **joining** is what wakes it.
+ *
+ * `tcp` is opaque passthrough, and it shares **443** with `http` — the client
+ * dials HTTPS either way, and the edge tells them apart by matching the SNI in
+ * the ClientHello against your rules. Where an `http` rule has the edge
+ * terminate the session, a `tcp` rule has it splice: the bytes go to your VM
+ * untouched and **your own certificate** answers the handshake. Ask for it when
+ * the session is yours to end — mutual TLS you verify yourself, a protocol over
+ * TLS that is not HTTP, a certificate you would rather issue than delegate. The
+ * cost is everything the edge could otherwise have done: no transform, no
+ * certificate issued for the name, and no HTTP/3 (there is no TCP to splice).
+ * It is **public ingress only** — `{ public: true } -> { vmId, port }`.
+ *
+ * `imap` and `imaps` are served on **993**, and share it the way `http` and
+ * `tcp` share 443 — one door, one route table, and the rule decides whether the
+ * edge is in the session. `imap` terminates: the edge answers the handshake
+ * with a certificate issued for the name and forwards *plain* IMAP to your
+ * server, so the rule lands on 143 by default and you run an unadorned mail
+ * server. `imaps` splices: your server terminates its own TLS on its own
+ * certificate and the platform holds no key to a byte of the mail, at the price
+ * of your obtaining that certificate and renewing it. Neither carries a
+ * transform — the credential in an IMAP session is your user's own. Both are
+ * public ingress only.
+ *
+ * `smtp` is served on **25** (MX delivery), **587** (submission) and **465**
+ * (implicit TLS). It is the one protocol whose `domain` is not a hostname: mail
+ * is routed by the **envelope recipient**, so a rule's name is a mail route and
+ * may carry a mailbox. `bot@acme.com` serves that one address, `acme.com` serves
+ * every mailbox at the name, `bot@*.acme.com` serves that mailbox at any
+ * subdomain and `*.acme.com` serves every mailbox at any subdomain — most
+ * specific wins. That is what lets a single wildcard MX record at `*.acme.com`
+ * give every subdomain its own VM, and what lets `agent-7@acme.com` land
+ * somewhere different from `sales@acme.com`; no SNI could express either, which
+ * is why the envelope and not the handshake is the routing key. Point an **MX**
+ * record at the edge rather than an A/AAAA one. The edge speaks SMTP as far as
+ * the first `RCPT TO`, then replays the envelope to your VM and splices — your
+ * own server still accepts or refuses the mail itself. **Egress** works like
+ * `postgres`: with an {@link SmtpTransform} the guest submits mail through a
+ * provider with *no password at all*, and the edge completes `AUTH` upstream
+ * with credentials the guest has never held. Your VM sees the edge as the
+ * connecting peer, so a guest that scores senders by IP will score the edge.
+ *
+ * `socks5` (1080) is the mirror image of all of them and the only **egress-only**
+ * protocol. Your VM opens SOCKS5 to the platform edge offering *no
+ * authentication*, names its destination inside the request, and the edge opens
+ * the session onward through your own proxy provider using the credentials a
+ * {@link Socks5Transform} carries — so the workload can use the subscription
+ * without ever being able to read it. Nothing is terminated: after the proxy
+ * answers, the edge copies bytes it cannot decrypt, and your TLS runs end to end
+ * to the real origin. Because the destination rides the SOCKS request rather
+ * than DNS, a `socks5` rule's `domain` is an **allow-list** and not a name
+ * anything resolves — `*` ("everything this VM opens goes through my proxy") is
+ * the shape most people want and is accepted here alone. The destination names
+ * the proxy: `{ vmId } -> { host: "gate.provider.com", port: 1080 }`.
+ *
+ * A **VM-to-VM internal service** (`{ vmId | vpcId } -> { vmId }`) is
+ * edge-brokered like every other shape (the source opens the name at the edge's
+ * front door for its protocol, and the edge forwards to the target VM's port) —
+ * and it cannot carry a transform yet.
+ */
+type TlsProtocol = "tcp" | "http" | "postgres" | "minecraft" | "smtp" | "imap" | "imaps" | "socks5";
+/**
+ * What a rule does with the session it matches.
+ *
+ * Only `allow` exists today, and every rule states it rather than defaulting —
+ * the same discipline the firewall keeps, and for the same reason. A default
+ * would mean that the day `deny` arrives (here it plausibly does: "allow every
+ * domain except this one" is a real thing to want, given the `*` wildcard), every
+ * rule written before it silently acquires an action it never stated.
+ */
+type TlsAction = "allow";
+/**
+ * One end of a rule: which session this side matches.
+ *
+ * The vocabulary is the firewall's — identity (`vmId`/`vpcId`) or address
+ * (`public`) — because a reader who knows the firewall should read this by
+ * reflex. What differs is that the two ends are *not* symmetric, and the
+ * asymmetries fall out of what each side means:
+ *
+ * - **A source never carries a landing coordinate** (`host`/`port`). A source is
+ *   *who opens* the session, not where it goes. The edge authenticates a source
+ *   by identity — its switch port, its anti-spoofed address — never by the name
+ *   it dials, because the name a client offers proves nothing about the client.
+ * - **A destination is never a `vpcId`.** "Which member of a network does this
+ *   land on" has no answer; a landing is one place. A whole network may be a
+ *   *source* — every VM on it may open the session — but not a destination.
+ *
+ * `public` also means different things by side. On a source it is the firewall's
+ * meaning exactly: every publicly routable client. On a destination it is *the
+ * domain's own public origin* — wherever the world's DNS says the name lives — so
+ * egress to a vendor is `{ public: true }`, never a blank matcher. The blank
+ * matcher never means "the Internet" here, for the same reason it never does in
+ * the firewall: the most dangerous statement you can write must not be the one
+ * you get by forgetting a field. Every rule states both ends.
+ *
+ * New selectors arrive as new optional fields, so this type only ever grows.
+ */
+interface TlsEndpoint {
+    /**
+     * A single VM, by id or by your slug for it. On a source, the VM that may open
+     * the session; on a destination, the VM the session lands on. Answers hold its
+     * id.
+     */
+    vmId?: string;
+    /**
+     * Everything on one private network, by id or by your slug for it. **Source
+     * only** — every member may open the session. A landing is one place, so a
+     * network cannot be a destination. Answers hold its id.
+     */
+    vpcId?: string;
+    /**
+     * On a source, every publicly routable client — the open Internet dials the
+     * name. On a destination, the domain's own public origin: wherever the world's
+     * DNS resolves the name. Only `true` is meaningful — omit the field otherwise.
+     */
+    public?: true;
+    /**
+     * **Destination only.** Pin the session to this host instead of resolving the
+     * domain — an alias, or an address reachable over a tunnel — while still
+     * presenting `domain` as the SNI.
+     */
+    host?: string;
+    /**
+     * **Destination only.** The port the session lands on. Required when the
+     * destination is a `vmId` or a `host`; defaults to 443 for a `public` origin.
+     */
+    port?: number;
+}
+/**
+ * Credentials injected into a Postgres startup handshake. The guest connects with
+ * no password (or any); the edge completes the real handshake upstream — so a
+ * compromised guest never holds a credential it could exfiltrate.
+ */
+interface PostgresTransform {
+    /** The upstream role to authenticate as. */
+    username: string;
+    /** The upstream password. Write-only: sealed at rest, read back as `"***"`. */
+    password: string;
+    /** The database to select. Optional: omitted leaves the guest's choice. */
+    database?: string;
+}
+/**
+ * Credentials injected into an SMTP submission handshake. The guest submits mail
+ * with no password; the edge completes `AUTH` upstream on its behalf — so a
+ * compromised guest never holds a submission credential it could exfiltrate, and
+ * cannot be turned into a spam relay by whoever took it.
+ */
+interface SmtpTransform {
+    /** The submission username to authenticate as. */
+    username: string;
+    /** The submission password. Write-only: sealed at rest, read back as `"***"`. */
+    password: string;
+}
+/**
+ * Credentials presented to your upstream SOCKS5 proxy. Your VM connects to the
+ * platform's SOCKS5 front offering *no authentication at all* and the edge
+ * authenticates to the provider on its behalf — so the subscription is never
+ * inside the VM to be read out of its environment, its disk or a snapshot of it.
+ * A guest that is fully compromised can use the proxy; it cannot take it.
+ *
+ * Optional. A provider that allow-lists its customers by source address needs no
+ * pair, and a `socks5` rule with no transform is an ordinary shape.
+ */
+interface Socks5Transform {
+    /** The username to present to the upstream proxy. */
+    username: string;
+    /** The password to present to the upstream proxy. Write-only: sealed at rest, read back as `"***"`. */
+    password: string;
+}
+/**
+ * One rewrite applied to a session in flight — something only the platform can
+ * do, because the whole point is to do what the guest could not do itself.
+ *
+ * Externally tagged: the wire is `{ headers: { … } }`, `{ postgres: { … } }`,
+ * `{ smtp: { … } }`, `{ socks5: { … } }` or `{ s3: { … } }`, exactly one key — `headers` injects
+ * request headers into an `http` session, `postgres` completes a `postgres`
+ * handshake, `smtp` completes a submission `AUTH`, and `socks5` authenticates the
+ * hop to your proxy provider. Each names the protocol it needs, so a rule's
+ * `protocol` is inferred from its transform when you omit it. Credential transforms are
+ * **egress** acts: the platform spends a credential the guest never holds, so a
+ * `postgres` or `smtp` transform on a rule landing on your own VM is refused —
+ * pointed inward the first hands every client a logged-in session and the second
+ * turns your mail server into an open relay. (`socks5` has no inward form at all
+ * to refuse.) Secrets here are
+ * **write-only**: sealed at rest and
+ * read back as `"***"`, with the record marked {@link TlsRuleData.redacted}.
+ * Header *names* survive a read — they are not secret, and seeing which headers a
+ * rule sets is how you audit it.
+ */
+type TlsTransform = {
+    headers: Record<string, string>;
+} | {
+    jsonPatch: JsonPatchOperation[];
+} | {
+    postgres: PostgresTransform;
+} | {
+    smtp: SmtpTransform;
+} | {
+    socks5: Socks5Transform;
+} | {
+    s3: S3Transform;
+};
+/** An S3 operation understood by the edge. Other operations fail closed. */
+type S3Operation = "GetObject" | "HeadObject" | "PutObject" | "DeleteObject" | "ListObjectsV2" | "CreateMultipartUpload" | "UploadPart" | "ListParts" | "CompleteMultipartUpload" | "AbortMultipartUpload" | "ListMultipartUploads";
+/** Credentials are sealed at rest, redacted on reads, and never sent to the VM. */
+interface S3Credentials {
+    accessKeyId: string;
+    secretAccessKey: string;
+    /** Optional temporary session token. Rotate with tls.rules.update before expiry. */
+    sessionToken?: string;
+}
+interface S3Scope {
+    bucket: string;
+    /** Literal key prefix. Use a trailing / for a directory boundary; "" permits all keys. */
+    prefix: string;
+    operations: S3Operation[];
+}
+/** Authorize then SigV4-sign HTTP egress. Must be the sole transform, without match.
+ * Supports virtual-hosted and path-style bucket addressing at a concrete origin.
+ * Listing requires an explicit prefix within scope. Copy, versioned
+ * requests, ACLs, and aws-chunked uploads are rejected. Bodies stream over HTTPS
+ * using UNSIGNED-PAYLOAD; policies requiring signed payload hashes are unsupported.
+ */
+interface S3Transform {
+    region: string;
+    credentials: S3Credentials;
+    scope: S3Scope;
+}
+/** A JSON value. Patch values are write-only and read back as `"***"`. */
+type JsonPatchValue = null | boolean | number | string | JsonPatchValue[] | {
+    [key: string]: JsonPatchValue;
+};
+/** RFC 6902 operation. Paths use RFC 6901 JSON Pointer, including /~0 and /~1
+ * escaping. `add` overwrites object members but inserts array elements; /-
+ * appends to an existing array. Parent containers must already exist.
+ * A rule accepts one patch of up to 128 operations / 64 KiB. All operations must
+ * succeed before forwarding. Applies to every JSON HTTP egress request on the
+ * rule; there is no endpoint filtering, provider translation, or wildcard path.
+ */
+type JsonPatchOperation = {
+    op: "add" | "replace" | "test";
+    path: string;
+    value: JsonPatchValue;
+} | {
+    op: "remove";
+    path: string;
+} | {
+    op: "move" | "copy";
+    from: string;
+    path: string;
+};
+/** A reusable forward-auth configuration attached to one public HTTP ingress rule. */
+interface TlsForwardAuthReference {
+    /** The forward-auth configuration id returned by {@link TlsForwardAuthNamespace.create}. */
+    id: string;
+}
+/** The customer-owned service Freestyle asks before forwarding a request to a VM. */
+interface CreateTlsForwardAuthOptions {
+    /** Absolute HTTPS endpoint that receives the authorization subrequest. */
+    url: string;
+    /** Static headers added to authorization subrequests. Values are write-only. */
+    headers?: Record<string, string>;
+    /** Authorization deadline in milliseconds. Defaults server-side; accepted range is 100-5000. */
+    timeoutMs?: number;
+    /** Cookies withheld from the destination VM and protected from being overwritten by it. */
+    protectedCookies?: string[];
+    /** Headers copied from an allowed authorization response onto the request sent to the VM. */
+    authResponseHeaders?: string[];
+}
+/** A stored forward-auth configuration. Static header values are returned as `"***"`. */
+interface TlsForwardAuthData {
+    id: string;
+    /** The account that owns the configuration. Taken from your credential, never a request body. */
+    accountId: string;
+    url: string;
+    /** Static authorization-request headers, with every value replaced by `"***"`. */
+    headers?: Record<string, string>;
+    timeoutMs: number;
+    protectedCookies?: string[];
+    authResponseHeaders?: string[];
+    /** Whether any static header value was redacted out of `headers`. */
+    redacted: boolean;
+    createdAt: string;
+    updatedAt: string;
+}
+interface ListTlsForwardAuthResult {
+    /** Newest first. */
+    configs: TlsForwardAuthData[];
+    totalCount: number;
+}
+/**
+ * A resource a rule cannot outlive. Deleting the resource deletes the rule, so no
+ * rule is ever left naming something that no longer exists — the same cascade the
+ * firewall uses.
+ */
+interface TlsDependency {
+    /** `"vm"` or `"vpc"` today; new selectors add new kinds. */
+    kind: string;
+    id: string;
+    /**
+     * Your handle for the named resource, when it has one — so a rule can say
+     * what it points at without a lookup per id.
+     */
+    slug?: string | null;
+    /** Your label for the named resource, under the same rules as `slug`. */
+    displayName?: string | null;
+}
+/**
+ * A stored TLS rule: the name a session is addressed to, who may open it, where
+ * it lands, and what the edge does to it in flight.
+ *
+ * `transform` is always redacted here — the sealed secrets live only in storage
+ * and reach only the dataplane. When any secret was redacted out, `redacted` is
+ * `true`, so a caller knows the shape it sees is not the whole story.
+ */
+/**
+ * Method/exact-path subset of Vercel Sandbox matchers.
+ * https://vercel.com/docs/sandbox/concepts/firewall#matchers
+ * Dimensions are ANDed; methods are ORed. Non-matches skip all transforms.
+ */
+interface HttpRequestMatch {
+    /** Case-sensitive HTTP method tokens. Omitted matches any; [] matches none. */
+    method?: string[];
+    /** Exact path, excluding query. No decoding or trailing-slash normalization. */
+    path?: {
+        exact: string;
+    };
+}
+interface TlsRuleData {
+    id: string;
+    /** The account that owns the rule. Taken from your credential, never a request body. */
+    accountId: string;
+    action: TlsAction;
+    /** The name the session is addressed to: exact, `*.suffix`, or `*`. */
+    domain: string;
+    protocol: TlsProtocol;
+    source: TlsEndpoint;
+    destination: TlsEndpoint;
+    /** The rewrites this rule applies, with every secret replaced by `"***"`. */
+    transform?: TlsTransform[];
+    /** Select which HTTP egress requests receive all of this rule's transforms. */
+    match?: HttpRequestMatch;
+    /** Authorization Freestyle performs before forwarding this public HTTP ingress. */
+    forwardAuth?: TlsForwardAuthReference;
+    /** Whether any transform secret was redacted out of `transform`. */
+    redacted?: boolean;
+    /**
+     * Whether the platform owns this rule. Managed rules are Freestyle's own (the
+     * SSH edge's standing grant, say), invisible to and undeletable by the account.
+     */
+    managed?: boolean;
+    /** What this rule dies with. See {@link TlsDependency}. */
+    dependencies: TlsDependency[];
+    createdAt: string;
+    updatedAt: string;
+}
+interface CreateTlsRuleOptions {
+    /** Required. `"allow"` is the only accepted value. */
+    action: TlsAction;
+    /**
+     * The name the session is addressed to: exact (`app.acme.com`), `*.suffix`, or
+     * `*`. For `smtp` this is a mail route instead, and may name a mailbox —
+     * `bot@acme.com`, `acme.com`, `bot@*.acme.com` or `*.acme.com`.
+     */
+    domain: string;
+    /**
+     * How the edge treats the bytes. Optional and usually omitted: it is inferred
+     * from `transform` when one is present, and defaults to `http` otherwise. Set
+     * it to `"imap"` to publish a mailbox on 993 (the edge terminates and forwards
+     * plain IMAP to your server; `"imaps"` splices to a server holding its own
+     * certificate), `"postgres"` to publish a database on 5432, `"minecraft"` to publish a
+     * Minecraft server on 25565, `"smtp"` to receive mail on 25/587/465, or
+     * `"tcp"` to have the edge splice the session on 443 without terminating it,
+     * so your VM's own certificate answers the handshake. See
+     * {@link TlsProtocol}.
+     */
+    protocol?: TlsProtocol;
+    /** Who may open the session. */
+    source: TlsEndpoint;
+    /** Where the session lands. */
+    destination: TlsEndpoint;
+    /** Rewrites applied in flight, in order. Secrets here are write-only. */
+    transform?: TlsTransform[];
+    /** Select which HTTP egress requests receive all of this rule's transforms. */
+    match?: HttpRequestMatch;
+    /** Ask this reusable configuration before forwarding a public HTTP request to the VM. */
+    forwardAuth?: TlsForwardAuthReference;
+}
+/**
+ * A rule declared inside a create, where the resource being created has no id
+ * yet.
+ *
+ * Exactly one endpoint may be left without an identity; that one *is* the new VM.
+ * So `{ source: { public: true }, destination: { port: 8000 } }` is inbound to
+ * it, and `{ source: {}, destination: { public: true } }` is egress from it. The
+ * identity-less destination still owes its `port`: a landing without a port is
+ * not a landing.
+ */
+type InlineTlsRule = CreateTlsRuleOptions;
+/** The `tls` block of a create. */
+interface TlsSpec {
+    rules: InlineTlsRule[];
+}
+interface ListTlsRulesOptions {
+    /** Rules that apply to this VM: those naming it, plus those naming a private network it is on. */
+    vmId?: string;
+    /** Rules naming this private network. */
+    vpcId?: string;
+    limit?: number;
+    offset?: number;
+}
+interface ListTlsRulesResult {
+    /** Newest first. */
+    rules: TlsRuleData[];
+    totalCount: number;
+}
+/** Reusable authorization checks for public HTTP ingress: `freestyle.tls.forwardAuth`. */
+declare class TlsForwardAuthNamespace {
+    private readonly client;
+    constructor(client: FreestyleClient);
+    /** List your forward-auth configurations, newest first. */
+    list(): Promise<ListTlsForwardAuthResult>;
+    /** Create a forward-auth configuration. Static request-header values are write-only. */
+    create(options: CreateTlsForwardAuthOptions): Promise<TlsForwardAuthData>;
+    /** Fetch one forward-auth configuration by id. */
+    get(id: string): Promise<TlsForwardAuthData>;
+    /** Replace a configuration in place, including rotating its static headers. */
+    update(id: string, options: CreateTlsForwardAuthOptions): Promise<TlsForwardAuthData>;
+    /** Delete an unused forward-auth configuration. */
+    delete(id: string): Promise<void>;
+}
+/** TLS rules: `freestyle.tls.rules`. */
+declare class TlsRulesNamespace {
+    private readonly client;
+    constructor(client: FreestyleClient);
+    /**
+     * Allow a named TLS session: `domain`, from `source`, to `destination`.
+     *
+     * An ingress `domain` is a name you have verified, or any unused subdomain
+     * of `style.dev`, which is free and needs no verification or DNS records.
+     *
+     * @example
+     * // Public HTTPS ingress: anyone dialing app.acme.com lands on a VM's port.
+     * await freestyle.tls.rules.create({
+     *   action: "allow",
+     *   domain: "app.acme.com",
+     *   source: { public: true },
+     *   destination: { vmId: "vm-123456", port: 8000 },
+     * });
+     *
+     * @example
+     * // Egress with a secret injected: a VM reaches OpenAI at its real origin,
+     * // and the edge adds the Authorization header the guest never held.
+     * await freestyle.tls.rules.create({
+     *   action: "allow",
+     *   domain: "api.openai.com",
+     *   source: { vmId: "vm-123456" },
+     *   destination: { public: true },
+     *   transform: [{ headers: { authorization: "Bearer sk-…" } }],
+     * });
+     *
+     * @example
+     * // Internal service: one VM reaches another by a name. The source opens
+     * // https://api.internal; the edge terminates it and forwards to the target
+     * // VM's port. Steered at the edge, HTTP-only, no transform.
+     * await freestyle.tls.rules.create({
+     *   action: "allow",
+     *   domain: "api.internal",
+     *   source: { vmId: "vm-123456" },
+     *   destination: { vmId: "vm-654321", port: 8000 },
+     * });
+     *
+     * @throws {TlsRuleValidationError} before any request, when the rule cannot be
+     * well formed.
+     */
+    create(options: CreateTlsRuleOptions): Promise<TlsRuleData>;
+    /**
+     * List your rules, newest first. Pass `vmId` for the rules that apply to one
+     * VM — those naming it, plus those naming a private network it is on.
+     */
+    list(options?: ListTlsRulesOptions): Promise<ListTlsRulesResult>;
+    get(ruleId: string): Promise<TlsRuleData>;
+    /**
+     * Replace a rule in place. The one mutation the firewall does not allow: a
+     * transform carries a rotating secret, and delete-then-create would drop
+     * traffic or trip the account limit mid-swap. The rule keeps its id and
+     * creation time; everything in `options` is replaced.
+     *
+     * @throws {TlsRuleValidationError} before any request, when the replacement
+     * cannot be well formed.
+     */
+    update(ruleId: string, options: CreateTlsRuleOptions): Promise<TlsRuleData>;
+    /** Delete a rule. The resources it named are untouched. */
+    delete(ruleId: string): Promise<void>;
+}
+/** The `freestyle.tls` namespace. */
+declare class TlsNamespace {
+    private readonly client;
+    readonly rules: TlsRulesNamespace;
+    readonly forwardAuth: TlsForwardAuthNamespace;
+    constructor(client: FreestyleClient);
+}
+
+/**
+ * One private network on the far side of a tunnel: the network, your address
+ * inside it, and the `[Peer]` key that carries it.
+ */
+interface TunnelAttachment {
+    vpcId: string;
+    /**
+     * Your IPv4 address inside the private network, absent on a v6-only
+     * attachment. It belongs to this tunnel for as long as the network stays
+     * attached, so you can write it into configs and rules.
+     */
+    ipv4?: string | null;
+    /** Your IPv6 address inside the private network, under the same rules. */
+    ipv6?: string | null;
+    /** @deprecated The primary address, whichever family. Read `ipv4`/`ipv6`. */
+    address: string;
+    /** @deprecated The second-family address. Read `ipv4`/`ipv6`. */
+    secondaryAddress?: string | null;
+    vpcCidr: string;
+    /** The CIDRs the gateway routes to this network. */
+    allowedIps: string[];
+    /**
+     * Ranges behind your client that this network routes through the tunnel (a
+     * site-to-site grant). VMs reach them with an ordinary route via `address`.
+     * Absent when the attachment has none.
+     */
+    remoteCidrs?: string[];
+    /**
+     * Whether this attachment is a network exit: your client forwards for
+     * destinations that are not its own address, and members route through it
+     * with an ordinary route via the attachment's address. Absent when false.
+     */
+    exit?: boolean;
+    createdAt: string;
+}
+/**
+ * A tunnel: your WireGuard identity on the platform. It exists until you
+ * delete it: connect, disconnect and reconnect as often as you like — a
+ * session is set up on the handshake that needs it, so an idle tunnel costs
+ * nothing and never expires. A tunnel routes nowhere until you attach a
+ * private network to it; attach several and one WireGuard interface reaches
+ * them all.
+ */
+interface TunnelData {
+    /** @deprecated The tunnel's id under its old name. Read `tunnelId`. */
+    id: string;
+    /**
+     * The tunnel's id, under the name the rest of the API uses for it — a
+     * firewall rule says `tunnelId`, so the tunnel does too.
+     */
+    tunnelId: string;
+    /**
+     * Your handle for this tunnel, if you gave it one. Usable anywhere the id
+     * is, in place of it.
+     */
+    slug?: string | null;
+    /** Your label for this tunnel, if you gave it one. Shown in place of the slug. */
+    displayName?: string | null;
+    /**
+     * A complete WireGuard config file, fixed for the life of the tunnel:
+     * attaching and detaching networks never changes it, so bring it up once
+     * and manage what it reaches through the API. `PrivateKey` is blank except
+     * on {@link TunnelsNamespace.create} and {@link TunnelsNamespace.rotateKey},
+     * the only two calls that mint a keypair.
+     */
+    clientConfig: string;
+    /** Host to dial. */
+    endpointHost?: string | null;
+    endpointPort: number;
+    clientPublicKey: string;
+    /** The one `[Peer]` public key in your config. */
+    serverPublicKey: string;
+    /**
+     * Your fixed addresses inside the tunnel. Only the gateway ever sees them:
+     * each attached network sees an address inside its own subnet instead
+     * (`attachments[].address`).
+     */
+    clientAddressV4: string;
+    clientAddressV6: string;
+    /**
+     * The ranges your client routes through the tunnel — its `AllowedIPs`,
+     * fixed at create. A network can only be attached if its CIDRs fall inside
+     * these.
+     */
+    routes: string[];
+    /** The private networks on the far side, oldest attachment first. */
+    attachments: TunnelAttachment[];
+    createdAt: string;
+    updatedAt: string;
+}
+/**
+ * A tunnel plus a client private key — returned only by the two calls that
+ * mint a keypair. The key is never stored and cannot be read back. Empty when
+ * you supplied your own public key.
+ */
+interface CreatedTunnel extends TunnelData {
+    /** Returned once. Already embedded in `clientConfig`. */
+    clientPrivateKey: string;
+}
+interface CreateTunnelOptions {
+    /**
+     * A URL-safe handle, unique within your account: lowercase letters, digits
+     * and single hyphens, up to 63 characters. Address the tunnel by it instead
+     * of by id.
+     */
+    slug?: string;
+    /**
+     * A label for a slug that does not read as a name — a tunnel per device id,
+     * per session. Shown in place of the slug.
+     */
+    displayName?: string;
+    /**
+     * The public key of a keypair you already hold. Omit to have one minted for
+     * you; supply it and the platform never sees a private key at all.
+     */
+    clientPublicKey?: string;
+    /**
+     * The ranges your client will route through the tunnel — its `AllowedIPs`,
+     * fixed for the tunnel's life so attaching and detaching networks never
+     * changes your config. Omit for the default (`10.0.0.0/8` and `fd00::/8`),
+     * which covers every network with default addressing. Only networks whose
+     * CIDRs fall inside the routes can be attached.
+     */
+    routes?: string[];
+    /**
+     * Networks to attach in the same call, so one request yields a tunnel that
+     * already routes somewhere. All-or-nothing: if any attachment is refused,
+     * nothing is created.
+     */
+    vpcs?: CreateTunnelVpc[];
+}
+/** One network named at create, with the same address choices as an attach. */
+interface CreateTunnelVpc {
+    /** The network to attach: a VPC id, or your slug for it. */
+    vpcId?: string;
+    /** @deprecated The network to attach, under its old name. Write `vpcId`. */
+    vpc?: string;
+    /** The address you want inside it; omit to be assigned one. */
+    ipv4?: string;
+    /** An explicit IPv6 address instead; only one may be set. */
+    ipv6?: string;
+    /** Ranges behind your client this network may route to; see {@link AttachVpcOptions.remoteCidrs}. */
+    remoteCidrs?: string[];
+    /** See {@link AttachVpcOptions.exit}. */
+    exit?: boolean;
+}
+interface AttachVpcOptions {
+    /**
+     * The address you want inside the private network. Omit to be assigned one.
+     * It must be free: a VM already holding it makes this a conflict, and once
+     * yours, no VM can be given it.
+     */
+    ipv4?: string;
+    /**
+     * An explicit IPv6 address, equivalent to passing one in `ipv4`; only one
+     * may be set.
+     */
+    ipv6?: string;
+    /**
+     * Ranges behind your client that this network routes through the tunnel — a
+     * site-to-site setup where your client machine forwards for other hosts on
+     * its side. Hosts inside these ranges keep their real addresses inside the
+     * network. A range carved out of the network's own CIDR just works: VMs
+     * reach it with no configuration, and the range is excluded from VM address
+     * allocation (it must be free when granted). A range outside the network's
+     * CIDRs is reached by giving VMs a route via the attachment's `address`. A
+     * range may not straddle the network's CIDR boundary, nor overlap a range
+     * another tunnel already grants this network.
+     */
+    remoteCidrs?: string[];
+    /**
+     * Make your client this network's exit — a router members can name as a
+     * next hop. A VM routes through it with an ordinary NIC route via the
+     * attachment's address, and everything it sends the exit — whatever the
+     * destination — is forwarded to your client, which is expected to NAT it
+     * onward. Several attachments per network may be exits: members choose per
+     * route, so two exits and two same-metric routes are a redundant pair, and
+     * a dead exit stops being ARP/NDP-answered so the others take over by
+     * themselves.
+     */
+    exit?: boolean;
+}
+interface UpdateTunnelOptions {
+    /** An empty string clears it. */
+    slug?: string;
+    /** An empty string clears it. See {@link CreateTunnelOptions.displayName}. */
+    displayName?: string;
+}
+interface ListTunnelsResult {
+    tunnels: TunnelData[];
+    totalCount: number;
+}
+declare class TunnelsNamespace {
+    private readonly client;
+    constructor(client: FreestyleClient);
+    /** List your tunnels, newest first. Listings never include a private key. */
+    list(): Promise<ListTunnelsResult>;
+    /**
+     * Create a tunnel, optionally attaching networks in the same call
+     * (`vpcs`, all-or-nothing). This is a one-time setup: the tunnel lives
+     * until you delete it and its config never changes — save it, bring it up
+     * once, and manage which networks it reaches by attaching and detaching
+     * them.
+     */
+    create(options?: CreateTunnelOptions): Promise<CreatedTunnel>;
+    /** Read one tunnel by its id or its slug. Its config comes back with a blank `PrivateKey`. */
+    get(tunnelIdOrSlug: string): Promise<TunnelData>;
+    /**
+     * Rename a tunnel or change its slug. Only the labels move: the keys,
+     * addresses, routes and attached networks are untouched, so a connected
+     * client sees nothing change and the config you saved keeps working.
+     */
+    update(tunnelIdOrSlug: string, options: UpdateTunnelOptions): Promise<TunnelData>;
+    /**
+     * Replace a tunnel's keys, keeping its id and every attached network's
+     * address. Use this if you lost the config or need to revoke one that
+     * leaked.
+     */
+    rotateKey(tunnelIdOrSlug: string, options?: {
+        clientPublicKey?: string;
+    }): Promise<CreatedTunnel>;
+    /** Delete a tunnel, detaching every network as it goes. */
+    delete(tunnelIdOrSlug: string): Promise<void>;
+    /**
+     * Attach a private network to a tunnel. The tunnel gains an address inside
+     * the network — what that network's VMs see as your address — and a
+     * connected client can reach it immediately, with no config change. The
+     * network's CIDRs must fall inside the tunnel's routes and must not
+     * overlap another attached network's.
+     */
+    attachVpc(tunnelIdOrSlug: string, vpcIdOrSlug: string, options?: AttachVpcOptions): Promise<TunnelData>;
+    /**
+     * Detach a private network from a tunnel: it stops being reachable and the
+     * tunnel's address inside it is released. The tunnel — and any connected
+     * client — carries on untouched.
+     */
+    detachVpc(tunnelIdOrSlug: string, vpcIdOrSlug: string): Promise<TunnelData>;
+}
+
+type VmState = "starting" | "running" | "pausing" | "paused" | "stopped";
+/**
+ * The base snapshots the platform publishes — the shared starting points every
+ * account can boot from, qualified `{owner}/{slug}` because they belong to the
+ * `freestyle` account rather than yours. Mirrors `catalog/snapshots.json`.
+ *
+ * A slug is a name, not a pointer: these are reassigned to a freshly built
+ * snapshot on every catalog rebuild, which is the point — booting
+ * `freestyle/ubuntu` gets you the current build. Pin a `sh-…` id instead when
+ * you need the exact image to stay put.
+ */
+type BaseSnapshotId = 
+/** Ubuntu 24.04 LTS · 2 vCPU · 4 GiB · 16 GB. */
+"freestyle/ubuntu-sm"
+/** Ubuntu 24.04 LTS · 4 vCPU · 8 GiB · 32 GB. The platform default. */
+ | "freestyle/ubuntu"
+/** Ubuntu 24.04 LTS · 8 vCPU · 16 GiB · 64 GB. */
+ | "freestyle/ubuntu-lg"
+/** Ubuntu 24.04 LTS · 16 vCPU · 32 GiB · 128 GB. */
+ | "freestyle/ubuntu-xl"
+/** Ubuntu 24.04 LTS · 32 vCPU · 64 GiB · 128 GB. The largest size any plan can actually create. */
+ | "freestyle/ubuntu-2xl"
+/** Ubuntu 24.04 LTS · 64 vCPU · 128 GiB · 256 GB. Above every plan's per-VM cap. */
+ | "freestyle/ubuntu-3xl"
+/** BusyBox · 1 vCPU · 128 MiB · 1 GB. For when Ubuntu is too big to fit. */
+ | "freestyle/busybox";
+/**
+ * Anywhere a snapshot is named: a `sh-…` id, your own slug for one, or a
+ * public `{owner}/{slug}`. The {@link BaseSnapshotId} arm exists purely so
+ * editors suggest the platform's catalog; `(string & {})` keeps every other
+ * snapshot just as valid, and stops TypeScript from collapsing the union back
+ * to a bare `string` and losing those suggestions.
+ */
+type SnapshotIdOrSlug = BaseSnapshotId | (string & {});
+interface VmResources {
+    /** vCPU count. */
+    cpu: number;
+    /** Memory, MiB. */
+    memory: number;
+    /** Disk, MiB. */
+    storage: number;
+}
+/** An in-guest static route: reach `cidr` via the gateway `via`, inside the network's CIDR. */
+interface NetworkRoute {
+    cidr: string;
+    via: string;
+    /**
+     * Route priority, as `ip route`'s `metric`. Omit for the platform default.
+     * Several routes to the same `cidr` at the same metric are installed as one
+     * multipath route — the guest spreads flows across their gateways (turn on
+     * `net.ipv4.fib_multipath_use_neigh` in the guest so a dead gateway drops
+     * out) — while different metrics make a primary and a backup.
+     */
+    metric?: number;
+}
+/** A VM's place on a private network. */
+interface VmNetwork {
+    /** @deprecated The network's id under its old name. Read `vpcId`. */
+    vpc: string;
+    /** The network's id, under the name the rest of the API uses. */
+    vpcId?: string;
+    /** The VM's IPv4 address inside the network; absent unless it asked for one. */
+    ipv4?: string | null;
+    /** The network's CIDR, alongside `ipv4`. */
+    cidr?: string | null;
+    /** The VM's IPv6 address, when the network has an IPv6 CIDR. */
+    ipv6?: string | null;
+    /** The network's IPv6 CIDR, alongside `ipv6`. */
+    cidrV6?: string | null;
+    routes: NetworkRoute[];
+}
+/** A VM as its owning account sees it. */
+interface VmData {
+    id: string;
+    state: VmState;
+    /** URL-safe identifier, unique within the account; usable anywhere an id is. */
+    slug?: string | null;
+    /** The VM's label, if it has one. Shown in place of the slug. */
+    displayName?: string | null;
+    resources: VmResources;
+    /** The snapshot the VM booted from, when it booted from one. */
+    snapshotId?: string | null;
+    /**
+     * What that snapshot was called when the VM was created, qualified
+     * `{owner}/{slug}` when it belongs to another account. Recorded once, so it
+     * still names the origin after the snapshot is renamed or deleted.
+     *
+     * A name, not a pointer. Slugs can be reassigned, so boot from `snapshotId`.
+     */
+    sourceSnapshotSlugAtCreate?: string | null;
+    /**
+     * What that snapshot is called *now*, resolved when the VM is read. Absent
+     * when it has no slug, and when it has been deleted — so against
+     * `sourceSnapshotSlugAtCreate` it is what tells a renamed origin from a gone
+     * one, without a second request.
+     */
+    sourceSnapshotSlug?: string | null;
+    /** The snapshot's display name now, under the same rules. */
+    sourceSnapshotDisplayName?: string | null;
+    idleTimeoutSeconds?: number | null;
+    /**
+     * Delete the VM once it has gone this long without running. Absent means
+     * never; 0 means the VM is ephemeral — deleted the moment it stops. Note
+     * this can be set for you: some plans cap how long an unused VM is kept,
+     * and the cap shows up here.
+     */
+    autoDeleteSeconds?: number | null;
+    /**
+     * Whether {@link Vm.autoDeleteSeconds} is your plan's doing rather than
+     * yours. A window your plan set goes away by itself if you move to a plan
+     * that does not reclaim unused VMs; one you set is yours and stays.
+     */
+    autoDeleteFromPlan?: boolean;
+    /** Delete the VM this long after it was created, whatever it is doing. */
+    ttlSeconds?: number | null;
+    /** Pause the VM once one run has lasted this long, however busy it is. */
+    maxRunSeconds?: number | null;
+    /**
+     * The VM's lifetime runtime budget in seconds. Spending it pauses the VM and
+     * makes every later start a 409 until you raise this.
+     */
+    maxRunTotalSeconds?: number | null;
+    /**
+     * Seconds this VM has spent running, across every run it has ever had —
+     * what {@link Vm.maxRunTotalSeconds} is measured against.
+     */
+    totalRunSeconds?: number;
+    /** Whether the VM is booted again when it stops without being asked to. */
+    automaticRestart?: boolean;
+    /**
+     * The VM's stable public IPv6 address — assigned at create and kept for the
+     * VM's life, across restarts and moves between machines.
+     */
+    publicIpv6?: string | null;
+    /**
+     * The public IPv4 address the VM's outbound traffic is seen as coming from.
+     * It belongs to your account rather than to this VM: every VM you own shares
+     * it, and it survives restarts and moves between machines.
+     *
+     * Optional, and worth reading as optional even though a VM in service has
+     * one: nothing promises an account keeps a single outbound address.
+     */
+    egressIpv4?: string | null;
+    /**
+     * The public IPv6 address the VM's outbound traffic is seen as coming from.
+     * Today it is the VM's own {@link Vm.publicIpv6} — it appears from the
+     * address it answers on — but read it as its own field: where a VM answers
+     * and where it appears from are two questions, and {@link Vm.egressIpv4}
+     * already answers them differently.
+     */
+    egressIpv6?: string | null;
+    metadata: Record<string, string>;
+    /** The placement constraints the VM was created with, when any. */
+    placement?: VmPlacement | null;
+    /** Total CPU time consumed, seconds. */
+    cpuTimeSeconds?: number | null;
+    lastNetworkActivity?: string | null;
+    /** The private networks the VM is on (at most one today). */
+    vpcs: VmNetwork[];
+    /** @deprecated The same list as `vpcs`, kept for old readers. */
+    networks: VmNetwork[];
+    createdAt: string;
+    updatedAt: string;
+}
+/**
+ * Placement constraints for a VM, fixed at create time and honored again
+ * whenever the platform relocates the VM.
+ */
+interface VmPlacement {
+    /**
+     * Hard rules: the VM will not land on a topology domain already hosting a
+     * VM matched by any rule's selector. Creation fails with a 409 when no
+     * domain can satisfy every rule. At most 8 rules.
+     */
+    antiAffinity: VmAntiAffinityRule[];
+}
+/** One anti-affinity rule: "not on the same `topology` domain as any VM matching `selector`". */
+interface VmAntiAffinityRule {
+    /** The domain the rule spreads across. `node` — the only domain today — means "not on the same host machine". */
+    topology: "node";
+    selector: VmLabelSelector;
+}
+/**
+ * Selects VMs by their metadata: a VM matches when its metadata contains
+ * every `matchLabels` entry. 1–8 entries; keys and values are limited to 63
+ * characters, like the metadata they match.
+ */
+interface VmLabelSelector {
+    matchLabels: Record<string, string>;
+}
+/** Attach a VM to one of your private networks. A VM may be on at most one. */
+interface AttachNetwork {
+    /** The network to join, by id or by your slug for it. */
+    vpcId?: string;
+    /** @deprecated The network to join, under its old name. Write `vpcId`. */
+    vpc?: string;
+    /**
+     * The IPv4 address to take inside the network: an explicit address, `true`
+     * to auto-allocate, or `false` to opt out. Omitted = allocate one, since
+     * networks are dual-stack.
+     */
+    ipv4?: string | boolean;
+    /**
+     * The IPv6 address to take: an explicit address, `true` to auto-allocate
+     * (the default), or `false` to opt out.
+     */
+    ipv6?: string | boolean;
+    /** Static routes to install in the guest. */
+    routes?: NetworkRoute[];
+}
+interface CreateVmOptions {
+    /** Boot from this snapshot: its id, your slug for it, or a public `{owner}/{slug}`. Omit for the platform default. */
+    snapshotId?: SnapshotIdOrSlug | null;
+    /**
+     * URL-safe identifier, unique within your account: 1–63 chars of
+     * `[a-z0-9-]`, no leading, trailing, or repeated hyphens.
+     *
+     * How you address the VM everywhere — the API, the CLI, the dashboard.
+     */
+    slug?: string | null;
+    /** Take `slug` from whichever VM currently holds it; the holder keeps running, slugless. Requires `slug`. */
+    reassignSlug?: boolean;
+    /**
+     * A label for a slug that does not read as a name — one minted per run,
+     * per commit or per tenant (`run-7f3a91c2`). Shown in place of the slug.
+     */
+    displayName?: string | null;
+    /**
+     * Pause the VM after this many seconds without network activity. Traffic
+     * over its public address counts, as does anything typed in a terminal
+     * session; -1 (or omitting this) means it is never paused for being idle.
+     */
+    idleTimeoutSeconds?: number | null;
+    /**
+     * Delete the VM once it has gone this many seconds without running. Every
+     * start resets the clock, and a running VM is never deleted for this.
+     * -1 (or omitting this) means never; 0 makes the VM ephemeral — deleted
+     * the moment it stops.
+     *
+     * Some plans cap how long an unused VM is kept. On those, omitting this (or
+     * sending -1) gets you the cap rather than "keep forever", and asking for
+     * longer is a 400.
+     */
+    autoDeleteSeconds?: number | null;
+    /**
+     * Delete the VM this many seconds after it is created, whatever it is doing
+     * at the time. A deadline, not an idle window: nothing resets it. -1 (or
+     * omitting this) means no deadline.
+     */
+    ttlSeconds?: number | null;
+    /**
+     * Pause the VM once a single run has lasted this many seconds, however busy
+     * it is. Starting it again gives it a fresh budget — unlike
+     * {@link CreateVmOptions.maxRunTotalSeconds}, which never resets. -1 (or
+     * omitting this) means no cap.
+     */
+    maxRunSeconds?: number | null;
+    /**
+     * How many seconds this VM may run in total, ever. Spending the budget
+     * pauses the VM, and every later start is a 409 until you raise it. -1 (or
+     * omitting this) means no budget.
+     */
+    maxRunTotalSeconds?: number | null;
+    /**
+     * Boot the VM again if it stops without you asking it to — the VMM crashes,
+     * the guest kernel panics, the machine it runs on loses power. Defaults to
+     * `true`.
+     *
+     * It never fights you: shutting the VM down, pausing it, running `poweroff`
+     * inside it, or hitting an idle timeout all leave it off. This only decides
+     * who gets the last word when a *failure* stops it.
+     */
+    automaticRestart?: boolean;
+    /** Put the VM on your private networks. Omit to leave it off them. At most one is accepted today. */
+    vpcs?: AttachNetwork[];
+    /** @deprecated The same list as `vpcs`; write `vpcs`. */
+    networks?: AttachNetwork[];
+    /** Up to 64 metadata entries; keys and values are limited to 63 characters. */
+    metadata?: Record<string, string>;
+    /**
+     * Placement constraints (anti-affinity), fixed for the VM's life. Selectors
+     * match the metadata of your other VMs.
+     */
+    placement?: VmPlacement | null;
+    /**
+     * Firewall rules created with the VM and deleted with it.
+     *
+     * Inside this block an endpoint with no identity means the VM being created,
+     * which is how a rule names a VM whose id does not exist yet. See
+     * {@link FirewallSpec}.
+     *
+     * @example
+     * firewall: {
+     *   rules: [
+     *     // Inbound HTTPS from anywhere.
+     *     { action: "allow", source: { public: true }, destination: { port: 443, protocol: "tcp" } },
+     *     // Outbound HTTPS to anywhere.
+     *     { action: "allow", source: {}, destination: { public: true, port: 443, protocol: "tcp" } },
+     *   ],
+     * }
+     *
+     * Required. A VM gets nothing implicitly — no outbound Internet, no inbound —
+     * so a VM that wants either says so here. `{ rules: [] }` is a legitimate
+     * answer: a VM reachable only through a mapped domain or SSH.
+     */
+    firewall: FirewallSpec;
+    /**
+     * TLS rules created with the VM and deleted with it — named sessions the VM
+     * may serve or open. Optional, unlike `firewall`: a TLS rule is a grant
+     * layered on top of the firewall's packet decision, never a baseline a VM
+     * must state.
+     *
+     * Inside this block an endpoint with no identity means the VM being created,
+     * exactly as in `firewall`. See {@link TlsSpec}.
+     *
+     * @example
+     * tls: {
+     *   rules: [
+     *     // Publish app.acme.com to port 8000 on this VM.
+     *     { action: "allow", domain: "app.acme.com", source: { public: true }, destination: { port: 8000 } },
+     *   ],
+     * }
+     */
+    tls?: TlsSpec;
+}
+interface UpdateVmOptions {
+    /** Change the slug; an empty string clears it. */
+    slug?: string;
+    /** Take `slug` from whichever VM currently holds it. */
+    reassignSlug?: boolean;
+    /**
+     * Change the display label; an empty string clears it. See
+     * {@link CreateVmOptions.displayName}.
+     */
+    displayName?: string;
+    /** Seconds of network idleness before the VM is paused; -1 removes the timeout. */
+    idleTimeoutSeconds?: number;
+    /**
+     * Seconds of not running before the VM is deleted; -1 removes the window
+     * (on a plan that caps it, -1 puts you back on the cap rather than off it),
+     * and 0 makes the VM ephemeral — deleted the moment it stops, or right away
+     * if it is already stopped.
+     */
+    autoDeleteSeconds?: number;
+    /**
+     * Seconds from creation — not from now — before the VM is deleted; -1
+     * removes the deadline. A value already in the past deletes it shortly.
+     */
+    ttlSeconds?: number;
+    /** Seconds one run may last before the VM is paused; -1 removes the cap. */
+    maxRunSeconds?: number;
+    /**
+     * The lifetime runtime budget in seconds; -1 removes it. Raising this past
+     * `totalRunSeconds` is how you start a VM that has spent its budget.
+     */
+    maxRunTotalSeconds?: number;
+    /**
+     * Turn automatic restart on or off. Applies to the next failure: this neither
+     * boots a stopped VM nor stops a running one.
+     */
+    automaticRestart?: boolean;
+    /** Metadata merged into the VM. Only the keys you send are touched; send an empty value to remove one. */
+    metadata?: Record<string, string>;
+}
+interface ResizeVmOptions {
+    /** vCPU count. Grow-only. Applies live to a running VM. */
+    cpu?: number;
+    /** Memory, MiB. Grow-only. Applies live to a running VM. */
+    memory?: number;
+    /** Disk, MiB. Grow-only, and only while the VM is running. */
+    storage?: number;
+}
+interface ExecOptions {
+    /** The command line, run through the guest's shell. */
+    command: string;
+    /**
+     * Guest Linux user to run as. Omit for the VM's default user: the account
+     * holding uid 1000, or `root` in an image that has no such account. Required
+     * when an identity grant restricts users.
+     */
+    linuxUser?: string;
+    /** Wall-clock limit, milliseconds. 1–300000; defaults to the guest's own. */
+    timeoutMs?: number;
+    /** Extra environment variables. Keys must be valid POSIX names. */
+    env?: Record<string, string>;
+    /** Base64-encoded stdin, up to 1 MiB decoded. */
+    stdin?: string;
+}
+interface ExecResult {
+    stdout?: string | null;
+    stderr?: string | null;
+    /** The command's exit status; null if it was killed by the timeout. */
+    statusCode?: number | null;
+}
+interface ListVmsOptions {
+    /** Only VMs in this state. */
+    state?: VmState;
+    /** Exact slug match. */
+    slug?: string;
+    /** Only VMs booted from this snapshot. */
+    snapshotId?: SnapshotIdOrSlug;
+    /** Comma-separated `key:value` pairs, e.g. `env:prod,region:us-west`. */
+    metadata?: string;
+    limit?: number;
+    offset?: number;
+}
+interface ListVmsResult {
+    vms: VmData[];
+    totalCount: number;
+    runningCount: number;
+    startingCount: number;
+    pausingCount: number;
+    pausedCount: number;
+    stoppedCount: number;
+}
+interface DirEntry {
+    name: string;
+    /** `file`, `directory`, or `symlink`. */
+    kind: string;
+}
+interface FileStat {
+    /** Size in bytes. */
+    size: number;
+    isFile: boolean;
+    isDirectory: boolean;
+    isSymlink: boolean;
+    /** Octal mode, e.g. `0644`. */
+    permissions: string;
+    owner: string;
+    group: string;
+    modified: string;
+}
+
+interface ReadFileOptions {
+    /** First byte to read. Default 0. */
+    offset?: number;
+    /** How many bytes to read. Default: to the end of the file. */
+    length?: number;
+    signal?: AbortSignal;
+}
+/**
+ * How far a transfer has got. An object rather than positional arguments so it
+ * can grow — a phase, a message — without breaking callers, and so progress
+ * reads the same way wherever the SDK reports it.
+ */
+interface TransferProgress {
+    /** Bytes confirmed stored so far. */
+    completedBytes: number;
+    /** Bytes in the whole transfer. */
+    totalBytes: number;
+}
+interface WriteFileOptions {
+    /** Final file mode bits, e.g. 0o755. Defaults to the target's existing mode, or 0o600. */
+    mode?: number;
+    /**
+     * Called as bytes are confirmed stored. A chunked upload reports after each
+     * chunk; a single-request write reports once, on completion.
+     */
+    onProgress?: (progress: TransferProgress) => void;
+    signal?: AbortSignal;
+    /** Bytes per chunk for large files (default 16 MiB; the server caps a chunk at 256 MiB). */
+    chunkSize?: number;
+    /** Attempts per chunk before giving up (default 5). */
+    maxAttempts?: number;
+}
+/**
+ * The guest filesystem of one VM: `GET/PUT /vms/{id}/fs/*`.
+ *
+ * Paths must be absolute, free of `..`, and at most 4096 characters. Files cross
+ * the wire as raw bytes in both directions, so there is no size limit short of
+ * the 16 GiB per-file ceiling and nothing to encode or decode.
+ *
+ * `writeFile` picks its own transport: small files go in one request, large ones
+ * as a resumable chunked upload whose failed chunks are retried individually.
+ * Either way the write is atomic — a reader in the guest sees the old file until
+ * the new one has arrived intact — and verified by sha256 end to end.
+ */
+declare class VmFilesystem {
+    private readonly client;
+    private readonly basePath;
+    constructor(client: FreestyleClient, basePath: string);
+    /**
+     * Read a whole file, or with `offset`/`length` just part of one, into memory.
+     *
+     * The result is a plain `Uint8Array` on every runtime — never a Node
+     * `Buffer`, even on Node. Don't coerce it with `String(bytes)` or
+     * `bytes.toString()`: those go through the typed-array `toString` and
+     * produce the byte values joined by commas ("123,10,32,…"), not the file's
+     * text. For text use {@link readTextFile}, or decode explicitly with
+     * `new TextDecoder().decode(bytes)`.
+     */
+    readFile(path: string, options?: ReadFileOptions): Promise<Uint8Array>;
+    /** Read a file as UTF-8 text. Use this, not `String(await readFile(...))`. */
+    readTextFile(path: string, options?: ReadFileOptions): Promise<string>;
+    /**
+     * Stream a file out of the VM without holding it in memory — pipe it to disk,
+     * to an HTTP response, or through a parser.
+     *
+     * ```ts
+     * const bytes = await vm.fs.readFileStream("/var/log/big.log");
+     * await pipeline(Readable.fromWeb(bytes), createWriteStream("big.log"));
+     * ```
+     */
+    readFileStream(path: string, options?: ReadFileOptions): Promise<ReadableStream<Uint8Array>>;
+    /**
+     * Write a file into the VM, whatever its size.
+     *
+     * ```ts
+     * await vm.fs.writeFile("/etc/app.conf", "debug = true");
+     * await vm.fs.writeFile("/data/model.bin", await openAsBlob("model.bin"), {
+     *   onProgress: ({ completedBytes, totalBytes }) =>
+     *     console.log(`${completedBytes}/${totalBytes}`),
+     * });
+     * ```
+     *
+     * A `Blob` (`node:fs`'s `openAsBlob`, or a browser `File`) is read one chunk at
+     * a time and never held in memory whole.
+     */
+    writeFile(path: string, content: string | Uint8Array | Blob, options?: WriteFileOptions): Promise<void>;
+    /** Write text. Identical to {@link writeFile} with a string. */
+    writeTextFile(path: string, content: string, options?: WriteFileOptions): Promise<void>;
+    readDir(path: string): Promise<DirEntry[]>;
+    mkdir(path: string): Promise<void>;
+    remove(path: string): Promise<void>;
+    exists(path: string): Promise<boolean>;
+    stat(path: string): Promise<FileStat>;
+    private openRead;
+    /**
+     * Send a large file as an upload session: ordered chunks, each retried
+     * independently with backoff, so one dropped connection costs one chunk rather
+     * than the whole transfer. The file appears at `path` only on commit.
+     */
+    private uploadInChunks;
+    /**
+     * PUT one chunk, retrying transient failures. After any failure the session
+     * is re-fetched: the server only counts fully-stored chunks, so its
+     * `receivedBytes` tells us whether this chunk actually landed (return) or
+     * must be resent (retry).
+     */
+    private putChunkWithRetry;
+}
+
+interface PtySessionInfo {
+    /** Per-VM session id, for attaching or closing this session. */
+    sessionId: number;
+    /** `"running"` while the shell is alive, `"exited"` once it has terminated. */
+    state: string;
+    /** Unix timestamp, in seconds, when the session was opened. */
+    createdUnix: number;
+    cols: number;
+    rows: number;
+    /** Exit code, present only once the session has exited. */
+    exitCode?: number | null;
+    /**
+     * Linux user the session runs as, named even when the open left the choice to
+     * the VM's default. Absent only for a session opened by a guest agent that
+     * predates that default, which ran it as root.
+     */
+    linuxUser?: string | null;
+    /**
+     * The name this session was opened with, while it still answers to it.
+     * Released the moment the shell exits, so an exited session reports none and
+     * is addressable only by `sessionId`.
+     */
+    slug?: string | null;
+}
+interface ListPtySessionsResult {
+    sessions: PtySessionInfo[];
+}
+interface ClosePtySessionResult {
+    sessionId: number;
+    /** Exit code if the session had already exited. Absent when it was still running. */
+    exitCode?: number | null;
+}
+interface PtyOpenOptions {
+    /** Command to run; omit for a login shell. */
+    exec?: string;
+    /** Initial width in columns (default 80). */
+    cols?: number;
+    /** Initial height in rows (default 24). */
+    rows?: number;
+    /**
+     * Guest Linux user to run as. Omit for the VM's default user: the account
+     * holding uid 1000, or `root` in an image that has no such account.
+     */
+    linuxUser?: string;
+    /**
+     * Name this session, so you can reattach to it later without storing the id
+     * we mint — `vm.pty.attach({ session: "main" })` from anywhere, any time.
+     *
+     * Get-or-create: if a session already has this name you get *that* one back —
+     * alive, or exited with its final output and exit code still readable — and
+     * `exec` is not run. `session.created` tells you which happened. Starting
+     * over is `close()` then `open()` again, which is deliberate: it destroys the
+     * dead session's output, and that output is usually why you came looking.
+     *
+     * Lowercase letters, digits and hyphens, and not all digits (session ids are
+     * bare integers, so an all-digit name could not be told apart from one).
+     */
+    slug?: string;
+    /**
+     * Respawn the shell in place when it exits, keeping this session's id, name
+     * and scrollback — for a terminal that should outlive whatever runs in it.
+     * A command that dies at startup is not respawned forever: after a few exits
+     * in quick succession the session is left dead so the error stays readable.
+     *
+     * Leave this off if you are waiting on a command's exit code. A session that
+     * comes back to life reports `running` again, and its `exitCode` becomes the
+     * next shell's.
+     */
+    replaceOnExit?: boolean;
+}
+/** A session's id, or the slug it was opened with. */
+type PtySessionSelector = number | string;
+interface PtyAttachOptions {
+    /** The session to reattach to: its id, or the slug it was opened with. */
+    session: PtySessionSelector;
+    /** Guest Linux user that must own the session. */
+    linuxUser?: string;
+}
+interface PtySessionEvents {
+    onData?: (data: Uint8Array) => void;
+    onExit?: (exitCode: number) => void;
+    onClose?: (info: {
+        wasClean: boolean;
+        code: number;
+        reason: string;
+    }) => void;
+    onError?: (err: unknown) => void;
+}
+/** Minimal surface both `ws` (Node) and the browser's native `WebSocket` provide. */
+interface Socket {
+    readonly readyState: number;
+    send(data: string | Uint8Array): void;
+    close(code?: number, reason?: string): void;
+    on?(event: "open" | "message" | "close" | "error", listener: (...args: unknown[]) => void): void;
+    addEventListener?(event: string, listener: (event: unknown) => void): void;
+}
+/**
+ * One interactive terminal session. Sessions are owned by the guest agent and
+ * outlive the connection that opened them: closing this only detaches, so the
+ * shell keeps running and a later `attach()` can pick it back up.
+ */
+/** Internal-only: lets {@link VmPty.open} learn the session id from the very
+ *  same listener that goes on to handle data/exit frames, so there's never a
+ *  gap between a throwaway listener and the real one where a fast command's
+ *  output (or even its exit) could arrive and be dropped. */
+interface InternalPtySessionEvents extends PtySessionEvents {
+    onSessionInfo?: (sessionId: number) => void;
+}
+declare class PtySession {
+    private _sessionId;
+    private _slug;
+    private _created;
+    private readonly socket;
+    constructor(socket: Socket, sessionId: number, events?: InternalPtySessionEvents);
+    /** Send raw bytes (or UTF-8 text) to the guest's stdin. */
+    write(data: Uint8Array | string): void;
+    resize(options: {
+        cols: number;
+        rows: number;
+    }): void;
+    signal(sig: "sigint" | "sigkill"): void;
+    private sendControl;
+    /** Close the connection. The shell keeps running; a later `attach()` can reconnect. */
+    detach(): void;
+    get sessionId(): number;
+    /**
+     * The name this session answers to, from the server's `sessionInfo` frame.
+     * `undefined` for a session opened without a slug — reattach to that one by
+     * `sessionId` instead.
+     */
+    get slug(): string | undefined;
+    /**
+     * Whether `open()` started this shell, or handed back one that was already
+     * running under the same `slug`. `false` means your `exec` never ran — check
+     * it before waiting on output from a command you thought you started.
+     */
+    get created(): boolean;
+    get readyState(): number;
+}
+/** The `vm.pty` surface: open/attach terminal WebSockets, and list/close sessions over REST. */
+declare class VmPty {
+    private readonly client;
+    private readonly basePath;
+    constructor(client: FreestyleClient, basePath: string);
+    /**
+     * Open a new terminal on the VM. The returned session's data/exit
+     * listeners are live from the moment the socket connects — installed
+     * before we even know the session id — so a command that produces output
+     * (or exits) immediately can never race past them.
+     */
+    open(options?: PtyOpenOptions & PtySessionEvents): Promise<PtySession>;
+    /** Reattach to an existing session; retained scrollback replays first. */
+    attach(options: PtyAttachOptions & PtySessionEvents): Promise<PtySession>;
+    /** List the VM's terminal sessions, running and recently exited. */
+    list(options?: {
+        linuxUser?: string;
+    }): Promise<ListPtySessionsResult>;
+    /** Kill a terminal session and remove it. */
+    close(session: PtySessionSelector, options?: {
+        linuxUser?: string;
+    }): Promise<ClosePtySessionResult>;
+}
+/** PTY operations scoped to one existing Linux user by `vm.linuxUser(...)`. */
+declare class VmLinuxUserPty {
+    private readonly pty;
+    private readonly linuxUser;
+    constructor(pty: VmPty, linuxUser: string);
+    open(options?: Omit<PtyOpenOptions, "linuxUser"> & PtySessionEvents): Promise<PtySession>;
+    attach(options: Omit<PtyAttachOptions, "linuxUser"> & PtySessionEvents): Promise<PtySession>;
+    list(): Promise<ListPtySessionsResult>;
+    close(session: PtySessionSelector): Promise<ClosePtySessionResult>;
+}
+
+/** A snapshot as its owner sees it. */
+interface SnapshotData {
+    id: string;
+    sourceVmId?: string | null;
+    /** Your handle for this snapshot; boot from it anywhere an id is taken. */
+    slug?: string | null;
+    /** The snapshot's label, if it has one. Shown in place of the slug. */
+    displayName?: string | null;
+    /** Owning account; public snapshots from other accounts are read-only. */
+    accountId?: string | null;
+    /** Public snapshots are bootable by any account. */
+    public: boolean;
+    /**
+     * Delete the snapshot once this long has passed without a VM being created
+     * from it. Absent means never; some plans cap it and the cap shows up here.
+     */
+    autoDeleteSeconds?: number | null;
+    /**
+     * Whether {@link SnapshotData.autoDeleteSeconds} is your plan's doing rather
+     * than yours; one your plan set goes away by itself if you move to a plan
+     * that does not reclaim unused snapshots.
+     */
+    autoDeleteFromPlan?: boolean;
+    /**
+     * Delete the snapshot this long after it was taken, however recently
+     * anything booted it.
+     */
+    ttlSeconds?: number | null;
+    /**
+     * When a VM was last created from this snapshot. Absent if none ever has
+     * been — which is not the same as untouched, since renaming a snapshot is
+     * not using it.
+     */
+    lastUsedAt?: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+interface CreateSnapshotOptions {
+    /**
+     * A URL-safe handle you can boot from directly, in place of the id.
+     */
+    slug?: string;
+    /**
+     * A label for a slug that does not read as a name — a build id, a commit
+     * sha. Shown in place of the slug.
+     */
+    displayName?: string;
+    /**
+     * Delete the snapshot once this many seconds pass without a VM being created
+     * from it. Every create from it resets the clock. -1 (or omitting this)
+     * means never; some plans cap this, and on those omitting it (or sending
+     * -1) gets you the cap.
+     */
+    autoDeleteSeconds?: number;
+    /**
+     * Delete the snapshot this many seconds after it is taken, whatever has
+     * booted it since.
+     */
+    ttlSeconds?: number;
+}
+interface UpdateSnapshotOptions {
+    /** An empty string clears it. */
+    slug?: string;
+    /** An empty string clears it. See {@link CreateSnapshotOptions.displayName}. */
+    displayName?: string;
+    /**
+     * Seconds of nothing being created from it before the snapshot is deleted;
+     * -1 removes the window. On a plan that caps it, -1 puts you back on the
+     * cap.
+     */
+    autoDeleteSeconds?: number;
+    /**
+     * Seconds from when the snapshot was taken — not from now — before it is
+     * deleted; -1 removes the deadline.
+     */
+    ttlSeconds?: number;
+}
+interface SnapshotCreated {
+    snapshotId: string;
+    sourceVmId: string | null;
+    snapshot: SnapshotData;
+}
+interface ListSnapshotsOptions {
+    /** Only snapshots taken from this VM. */
+    sourceVmId?: string;
+    limit?: number;
+    offset?: number;
+}
+interface ListSnapshotsResult {
+    snapshots: SnapshotData[];
+    totalCount: number;
+}
+/** The `freestyle.vms.snapshots` namespace: `GET /v5/snapshots`, `/v5/snapshots/{id}`. */
+declare class VmSnapshotsNamespace {
+    private readonly client;
+    constructor(client: FreestyleClient);
+    list(options?: ListSnapshotsOptions): Promise<ListSnapshotsResult>;
+    get(snapshotId: string): Promise<SnapshotData>;
+    update(snapshotId: string, options: UpdateSnapshotOptions): Promise<SnapshotData>;
+    delete(snapshotId: string): Promise<void>;
+}
+
+/**
+ * A handle to one VM, keyed by its id or slug. Every method hits the API
+ * fresh (nothing is cached); `data()` re-fetches and returns the current
+ * record.
+ */
+declare class Vm {
+    readonly id: string;
+    readonly fs: VmFilesystem;
+    readonly pty: VmPty;
+    private readonly client;
+    private readonly basePath;
+    constructor(client: FreestyleClient, id: string);
+    /** Fetch the current VM record. */
+    data(): Promise<VmData>;
+    /**
+     * The firewall rules that apply to this VM: those naming it, plus those
+     * naming a private network it is attached to.
+     *
+     * Deleting the VM deletes the rules that name it, so this never reports a
+     * rule over a machine that no longer exists.
+     */
+    firewallRules(): Promise<ListFirewallRulesResult>;
+    /** Rename the VM, change its slug or idle timeout, or merge in metadata. */
+    update(options: UpdateVmOptions): Promise<VmData>;
+    /** Boot a stopped VM, or resume a paused one. */
+    start(): Promise<VmData>;
+    /** Freeze a running VM, keeping its memory so a later start resumes it exactly. */
+    pause(): Promise<VmData>;
+    /**
+     * Change vCPU, memory, or disk. Every axis is grow-only. vCPU and memory
+     * apply live to a running VM, on resume for a paused one, and at the next
+     * boot for a stopped one. Growing the disk needs a running VM.
+     */
+    resize(options: ResizeVmOptions): Promise<VmData>;
+    /** Permanently destroy the VM */
+    delete(): Promise<void>;
+    /**
+     * Run a command in the guest and wait for it to finish. A non-zero exit
+     * status is still a successful call — check `statusCode`, which is null if
+     * the command was killed by its timeout.
+     */
+    exec(options: string | ExecOptions): Promise<ExecResult>;
+    /** Scope process and terminal operations to one existing in-guest Linux user. */
+    linuxUser(linuxUser: string): VmLinuxUser;
+    /**
+     * Capture the VM's exact state, memory and disk. The VM must be running or
+     * paused. The new snapshot is private and fully materialized when this
+     * resolves.
+     */
+    snapshot(options?: CreateSnapshotOptions): Promise<SnapshotCreated>;
+}
+/** A VM handle whose process-spawning operations run as one Linux user. */
+declare class VmLinuxUser {
+    private readonly vm;
+    private readonly linuxUser;
+    readonly pty: VmLinuxUserPty;
+    constructor(vm: Vm, linuxUser: string);
+    exec(options: string | Omit<ExecOptions, "linuxUser">): Promise<ExecResult>;
+}
+/** The `freestyle.vms` namespace: create, list, and manage VMs. */
+declare class VmsNamespace {
+    private readonly client;
+    readonly snapshots: VmSnapshotsNamespace;
+    constructor(client: FreestyleClient);
+    /**
+     * Boot a new VM.
+     *
+     * `firewall` is required: a VM gets nothing implicitly, so state what it may
+     * reach. `{ rules: [] }` is a legitimate answer — a VM reachable only through
+     * a mapped domain or SSH.
+     *
+     * @example
+     * const { vm, vmId } = await freestyle.vms.create({
+     *   firewall: {
+     *     rules: [
+     *       // This VM can reach the Internet. Without it, it cannot.
+     *       { action: "allow", source: {}, destination: { public: true } },
+     *     ],
+     *   },
+     * });
+     * await vm.exec("echo hello");
+     */
+    create(options: CreateVmOptions): Promise<{
+        vm: Vm;
+        vmId: string;
+        data: VmData;
+        firewallRules: FirewallRuleData[];
+        /** The rules the create's `tls` block produced; empty without one. */
+        tlsRules: TlsRuleData[];
+    }>;
+    /**
+     * List your VMs.
+     *
+     * @example
+     * const { vms } = await freestyle.vms.list();
+     */
+    list(options?: ListVmsOptions): Promise<ListVmsResult>;
+    /**
+     * Fetch a VM by its id or its slug.
+     *
+     * @example
+     * const vm = await freestyle.vms.get("vmId");
+     */
+    get(vmIdOrSlug: string): Promise<VmData>;
+    /** A handle to a VM, without a network call. */
+    ref(vmIdOrSlug: string): Vm;
+    delete(vmIdOrSlug: string): Promise<void>;
+}
+
+/** A private network. */
+interface VpcData {
+    id: string;
+    /** The network's IPv4 CIDR block, when it has one. */
+    cidr?: string | null;
+    /** The network's IPv6 CIDR block — always present. */
+    cidrV6: string;
+    /** Your handle for this network; usable anywhere its id is. */
+    slug?: string | null;
+    /** The network's label, if it has one. Shown in place of the slug. */
+    displayName?: string | null;
+    createdAt: string;
+}
+interface CreateVpcOptions {
+    /**
+     * Firewall rules created with the network and deleted with it.
+     *
+     * A bare endpoint means the network being created, so `{ source: {},
+     * destination: {} }` is the most common thing anyone wants to say about a
+     * network: its members can reach each other.
+     *
+     * @example
+     * firewall: {
+     *   rules: [
+     *     // Members reach each other.
+     *     { action: "allow", source: {}, destination: {} },
+     *     // Members reach the Internet.
+     *     { action: "allow", source: {}, destination: { public: true } },
+     *   ],
+     * }
+     */
+    firewall?: FirewallSpec;
+    /**
+     * The network's IPv4 CIDR. Networks are dual-stack; a `/24` out of
+     * `10.0.0.0/8` is derived for you when omitted. Name one to pick the range
+     * yourself — worth doing when the network must not overlap an estate you
+     * reach over a tunnel, or needs more than 254 IPv4 members.
+     */
+    cidr?: string;
+    /** The network's IPv6 CIDR; a unique-local /64 is derived when omitted. */
+    cidrV6?: string;
+    /** A URL-safe handle, unique within your account, usable anywhere its id is. */
+    slug?: string;
+    /**
+     * A label for a slug that does not read as a name — one network per tenant
+     * or per environment id. Shown in place of the slug.
+     */
+    displayName?: string;
+}
+interface UpdateVpcOptions {
+    /** An empty string clears it. */
+    slug?: string;
+    /** An empty string clears it. See {@link CreateVpcOptions.displayName}. */
+    displayName?: string;
+}
+interface ListVpcsResult {
+    vpcs: VpcData[];
+    totalCount: number;
+}
+/** Tunnels attached to one private network: `vpc.tunnels`. */
+declare class VpcTunnelNamespace {
+    private readonly client;
+    private readonly basePath;
+    constructor(client: FreestyleClient, basePath: string);
+    /**
+     * List the tunnels attached to this network, newest first. Listings never
+     * include a private key: one is returned only by
+     * `freestyle.tunnels.create` and `freestyle.tunnels.rotateKey`.
+     */
+    list(): Promise<ListTunnelsResult>;
+}
+/** A handle to one private network. */
+declare class Vpc {
+    readonly id: string;
+    readonly tunnels: VpcTunnelNamespace;
+    private readonly client;
+    private readonly basePath;
+    constructor(client: FreestyleClient, id: string);
+    data(): Promise<VpcData>;
+    update(options: UpdateVpcOptions): Promise<VpcData>;
+    delete(): Promise<void>;
+}
+/** The `freestyle.vpc` namespace: create and manage private networks. */
+declare class VpcNamespace {
+    private readonly client;
+    constructor(client: FreestyleClient);
+    /** List your private networks. */
+    list(): Promise<ListVpcsResult>;
+    /** Create a private network, optionally with the rules that say what it is for. */
+    create(options?: CreateVpcOptions): Promise<{
+        vpc: Vpc;
+        vpcId: string;
+        data: VpcData;
+        firewallRules: FirewallRuleData[];
+    }>;
+    /** Fetch a private network by its id or its slug. */
+    get(vpcIdOrSlug: string): Promise<VpcData>;
+    /** A handle to a private network, without a network call. */
+    ref(vpcIdOrSlug: string): Vpc;
+    delete(vpcIdOrSlug: string): Promise<void>;
+}
+
+/**
+ * The Freestyle API client. See https://freestyle.sh/docs and
+ * https://api.freestyle.sh/openapi.json for the underlying HTTP contract.
+ *
+ * @example
+ * const freestyle = new Freestyle({ apiKey: process.env.FREESTYLE_API_KEY });
+ * const { vm } = await freestyle.vms.create();
+ * const { stdout } = await vm.exec("echo hello");
+ */
+declare class Freestyle {
+    private readonly client;
+    readonly vms: VmsNamespace;
+    readonly vpc: VpcNamespace;
+    readonly tunnels: TunnelsNamespace;
+    /** Allowed network communication, stated as `source -> destination` intent. */
+    readonly firewall: FirewallNamespace;
+    /** Named TLS sessions, stated as `domain, source -> destination` intent. */
+    readonly tls: TlsNamespace;
+    readonly domains: DomainsNamespace;
+    readonly identities: IdentitiesNamespace;
+    constructor(options?: FreestyleOptions);
+    /** Low-level escape hatch: an authenticated `fetch` against the API. Pass the whole path, `/v5` included. */
+    fetch(path: string, init?: RequestInit): Promise<Response>;
+}
+
 interface DaemonAddress {
     url: string;
     token: string;
@@ -1322,24 +3705,37 @@ interface DaemonAddress {
  *
  * The VM is the whole state: its slug is the handle and its metadata holds the
  * daemon bearer, so any Studio replica can find a sandbox without a database.
- * An idle VM is paused, not deleted, and traffic to its domain resumes it.
+ * An idle VM is paused, and traffic to its domain resumes it; one paused for
+ * `autoDeleteSeconds` is deleted.
  */
 
 interface FreestyleSandboxProviderOptions {
     apiKey: string;
     /** The sandbox image. Default: the release built from this package's version. */
     image?: string;
+    /** The org-fs sidecar image. Default: the chart's `orgFs.image`. */
+    orgFsSidecarImage?: string;
     /** Pause a VM after this long without network activity. Default 15 min. */
     idleTimeoutSeconds?: number;
+    /**
+     * Delete a VM after this long without running. Default 3 days. A plan
+     * that caps it lower gets its cap.
+     */
+    autoDeleteSeconds?: number;
     /** Where daemon ports are published. Default `style.dev`, free on every account. */
     domainSuffix?: string;
     /** Records daemon request latency; see `daemonProxyTimer`. */
     meter?: Meter;
+    /** Replaces the API client, for tests. */
+    client?: Freestyle;
 }
 declare class FreestyleSandboxProvider implements SandboxProvider {
     private readonly freestyle;
+    private readonly lookupClient;
     private readonly image;
+    private readonly sidecarImage;
     private readonly idleTimeoutSeconds;
+    private readonly autoDeleteSeconds;
     private readonly domainSuffix;
     private readonly timeDaemonRequest;
     private readonly inflight;
@@ -1353,8 +3749,8 @@ declare class FreestyleSandboxProvider implements SandboxProvider {
     private find;
     private remember;
     /**
-     * A snapshot of a VM with the image already pulled, so a sandbox boots in
-     * seconds instead of pulling ~2GB. One per image; built on first use.
+     * A snapshot of a VM with both images already pulled, so a sandbox boots in
+     * seconds instead of pulling ~2GB. One per image pair; built on first use.
      */
     private baseSnapshot;
     private snapshotExists;
@@ -1362,6 +3758,8 @@ declare class FreestyleSandboxProvider implements SandboxProvider {
     ensure(id: SandboxId, opts?: EnsureOptions): Promise<Sandbox>;
     private resume;
     private create;
+    /** A plan that caps autoDelete lower answers 400; omitting it gets the cap. */
+    private createVm;
     private configPayload;
     private waitForDaemon;
     delete(handle: string): Promise<void>;
@@ -1398,6 +3796,7 @@ declare class FreestyleSandboxProvider implements SandboxProvider {
  * where `EnsureOptions.provider` asks, when that provider is configured and
  * can run it; else `freestyleShare` of new sandboxes go to Freestyle, and the
  * rest to Kubernetes while it has room. An existing one stays where it is.
+ * When the chosen provider's ensure fails, the other one gets a try.
  * Handle-only calls go to the provider that owns the handle, because a handle
  * carries no provider tag.
  */
@@ -1420,9 +3819,22 @@ interface SandboxProviderRouterOptions {
      */
     freestyleShare?: number;
 }
+interface Placement {
+    kind: SandboxProviderKind;
+    /** Absent when only one provider could take it. */
+    reason?: SandboxPlacementReason;
+}
 declare class SandboxProviderRouter implements SandboxProvider {
     readonly providers: SandboxProviders;
     private readonly picked;
+    /**
+     * Handles whose sandbox on this provider outlived a fallback because its
+     * delete failed. Retried when `place` next sees the handle.
+     *
+     * ponytail: in-process, lost on restart; Freestyle's autoDeleteSeconds
+     * reclaims a stray paused VM anyway, only later.
+     */
+    private readonly strays;
     private readonly freestyleShare;
     constructor(providers: SandboxProviders, opts?: SandboxProviderRouterOptions);
     private get;
@@ -1430,9 +3842,13 @@ declare class SandboxProviderRouter implements SandboxProvider {
     /** Who serves an existing handle. Kubernetes is the fallback: it has no cheap ownership check. */
     providerOf(handle: string): Promise<SandboxProviderKind>;
     private owner;
-    /** Where `ensure` puts this sandbox. */
-    place(handle: string, opts: EnsureOptions): Promise<SandboxProviderKind>;
+    /** Where `ensure` puts this sandbox, and why. */
+    place(handle: string, opts: EnsureOptions): Promise<Placement>;
+    /** The org has pods already cloned and running for this image. */
+    private hasWarmPool;
     ensure(id: SandboxId, opts?: EnsureOptions): Promise<Sandbox>;
+    /** Delete the sandbox a fallback left behind on `kind`, in the background. */
+    private retire;
     delete(handle: string): Promise<void>;
     lastTermination(handle: string): Promise<PodTermination | null>;
     alive(handle: string): Promise<boolean>;