freestyle-sandboxes 0.1.6 → 0.1.8

package/index.cjs

@@ -4624,6 +4624,36 @@ class VmWith {
   compose(...configs) {
     return composeCreateVmOptions(configs);
   }
+  /**
+   * Helper method to compose multiple VmSpecs together.
+   * Uses the same merging strategy as the main compose function.
+   * Useful in configureSpec and configureSnapshotSpec methods.
+   */
+  composeSpecs(...specs) {
+    return composeVmSpecs(specs);
+  }
+  /**
+   * @deprecated Use composeSpecs instead
+   * Helper method to compose multiple VmTemplates together.
+   * Uses the same merging strategy as the main compose function.
+   * Useful in configureTemplate and configureNestedTemplate methods.
+   */
+  composeTemplates(...templates) {
+    return composeVmTemplates(templates);
+  }
+  /**
+   * @deprecated This method is no longer needed. Use vms.get with allowedSpecs instead.
+   */
+  async configureReturnedVm(vm, template) {
+    if (template.raw) {
+      if (this.configure) {
+        await this.configure(template.raw);
+      }
+      const instance = this.createInstance();
+      instance._init(vm);
+      this.instance = instance;
+    }
+  }
 }
 const VmService = VmWith;
 const VmBuilder = VmWith;
@@ -4875,6 +4905,73 @@ function composeCreateVmOptions(arr) {
   }
   return result;
 }
+function composeVmTemplates(templates) {
+  if (templates.length === 0) {
+    return new VmTemplate({});
+  }
+  if (templates.length === 1) {
+    return templates[0];
+  }
+  const rawConfigs = templates.map((t) => t.raw);
+  const composedRaw = composeCreateVmOptions(
+    rawConfigs
+  );
+  const mergedWith = {};
+  for (const template of templates) {
+    for (const key in template.with) {
+      const builder = template.with[key];
+      if (builder) {
+        mergedWith[key] = builder;
+      }
+    }
+  }
+  const nestedTemplates = templates.map((t) => t.raw.template).filter((t) => t instanceof VmTemplate);
+  let nestedTemplate;
+  if (nestedTemplates.length > 0) {
+    nestedTemplate = composeVmTemplates(nestedTemplates);
+  }
+  const result = new VmTemplate({
+    ...composedRaw,
+    template: nestedTemplate,
+    with: mergedWith
+  });
+  return result;
+}
+function composeVmSpecs(specs) {
+  if (specs.length === 0) {
+    return new VmSpec({});
+  }
+  if (specs.length === 1) {
+    return specs[0];
+  }
+  const rawConfigs = specs.map((s) => {
+    const { snapshot, ...rest } = s.raw;
+    return rest;
+  });
+  const composedRaw = composeCreateVmOptions(
+    rawConfigs
+  );
+  const mergedWith = {};
+  for (const spec of specs) {
+    for (const key in spec.with) {
+      const builder = spec.with[key];
+      if (builder) {
+        mergedWith[key] = builder;
+      }
+    }
+  }
+  const nestedSpecs = specs.map((s) => s.raw.snapshot).filter((s) => s instanceof VmSpec);
+  let nestedSpec;
+  if (nestedSpecs.length > 0) {
+    nestedSpec = composeVmSpecs(nestedSpecs);
+  }
+  const result = new VmSpec({
+    ...composedRaw,
+    snapshot: nestedSpec,
+    with: mergedWith
+  });
+  return result;
+}
 
 class VmTerminals {
   constructor(vmId, client) {
@@ -5054,51 +5151,121 @@ class Vm {
     return this.apiClient.post("/v1/vms/{id}/resize", {
       params: { id: this.vmId },
       body: { memSizeGb, rootfsSizeGb, vcpuCount }
+      // Temporarily cast to any
     });
   }
-}
-class VmSnapshotsNamespace {
-  constructor(apiClient) {
-    this.apiClient = apiClient;
+  /**
+   * Create a VM instance by ID without making an api call.
+   */
+  ref({ vmId }) {
+    return new Vm(vmId, this.apiClient);
   }
-  async ensure(options) {
-    if (options.template.raw.template instanceof VmTemplate) {
-      options.template = await ensureNestedTemplates(options.template, this);
-    }
-    return this.apiClient.post("/v1/vms/snapshots", {
-      body: {
-        ...options,
-        // @ts-ignore
-        template: options.template?.raw
-      }
+  async delete({ vmId }) {
+    return this.apiClient.delete("/v1/vms/{vm_id}", {
+      params: { vm_id: vmId }
     });
   }
 }
-async function ensureNestedTemplates(template, snapshots) {
-  let templates = [template];
-  while (templates.at(-1)?.raw.template instanceof VmTemplate) {
-    let innerTemplate = templates.at(-1).raw.template;
-    templates.at(-1).raw.template = void 0;
-    templates.push(innerTemplate);
+class VmTemplate {
+  raw;
+  with;
+  constructor(template) {
+    const { with: withBuilders, ...rest } = template;
+    this.raw = rest;
+    this.with = withBuilders ?? {};
   }
-  return await layerTemplates(templates, snapshots);
 }
-async function layerTemplates(templates, snapshots) {
-  let lastTemplate = templates.pop();
-  const { snapshotId } = await snapshots.ensure({
-    template: lastTemplate
+class VmSpec {
+  raw;
+  with;
+  constructor(spec) {
+    const { with: withBuilders, ...rest } = spec;
+    this.raw = rest;
+    this.with = withBuilders ?? {};
+  }
+}
+async function convertSpecSnapshotsToTemplates(spec, processBuilders = true) {
+  if (!spec.raw.snapshot) {
+    return void 0;
+  }
+  let innerSpec = spec.raw.snapshot;
+  if (processBuilders) {
+    innerSpec = await processSpecTree(innerSpec);
+  }
+  const { snapshot: nestedSnapshot, ...innerRaw } = innerSpec.raw;
+  let nestedTemplate;
+  if (nestedSnapshot instanceof VmSpec) {
+    nestedTemplate = await convertSpecSnapshotsToTemplates(innerSpec, false);
+  }
+  return new VmTemplate({
+    ...innerRaw,
+    template: nestedTemplate,
+    with: innerSpec.with
   });
-  let lastSnapshotId = snapshotId;
-  while (templates.length > 0) {
-    const template = templates.pop();
-    template.raw.snapshotId = lastSnapshotId;
-    const { snapshotId: snapshotId2 } = await snapshots.ensure({
-      template
-    });
-    lastSnapshotId = snapshotId2;
-    lastTemplate = template;
+}
+async function processOuterSpecBuilders(spec) {
+  for (const key in spec.with) {
+    const builder = spec.with[key];
+    if (builder) {
+      if (builder.configureSpec) {
+        spec = await builder.configureSpec(spec);
+      }
+      if (builder.configureSnapshotSpec) {
+        let snapshotSpec;
+        if (spec.raw.snapshot instanceof VmSpec) {
+          snapshotSpec = spec.raw.snapshot;
+        } else {
+          snapshotSpec = new VmSpec({});
+          spec.raw.snapshot = snapshotSpec;
+        }
+        spec.raw.snapshot = await builder.configureSnapshotSpec(snapshotSpec);
+      }
+    }
   }
-  return lastTemplate;
+  return spec;
+}
+async function processSpecTree(spec) {
+  for (const key in spec.with) {
+    const builder = spec.with[key];
+    if (builder) {
+      if (builder.configureSpec) {
+        spec = await builder.configureSpec(spec);
+      }
+      if (builder.configureSnapshotSpec) {
+        let snapshotSpec;
+        if (spec.raw.snapshot instanceof VmSpec) {
+          snapshotSpec = spec.raw.snapshot;
+        } else {
+          snapshotSpec = new VmSpec({});
+          spec.raw.snapshot = snapshotSpec;
+        }
+        spec.raw.snapshot = await builder.configureSnapshotSpec(snapshotSpec);
+      }
+    }
+  }
+  if (spec.raw.snapshot instanceof VmSpec) {
+    spec.raw.snapshot = await processSpecTree(spec.raw.snapshot);
+  }
+  return spec;
+}
+function collectSpecBuilders(spec) {
+  const builders = {};
+  if (spec.with) {
+    for (const [key, builder] of Object.entries(spec.with)) {
+      if (builder) {
+        builders[key] = builder;
+      }
+    }
+  }
+  if (spec.raw.snapshot instanceof VmSpec) {
+    const nestedBuilders = collectSpecBuilders(spec.raw.snapshot);
+    for (const [key, builder] of Object.entries(nestedBuilders)) {
+      if (!builders[key] && builder) {
+        builders[key] = builder;
+      }
+    }
+  }
+  return builders;
 }
 class VmsNamespace {
   constructor(apiClient) {
@@ -5112,9 +5279,32 @@ class VmsNamespace {
    * @returns A VM instance representing the created VM
    */
   async create(options = {}) {
-    const builders = options.with || {};
+    if (options.spec instanceof VmSpec) {
+      let spec = options.spec;
+      spec = await processOuterSpecBuilders(spec);
+      const { snapshot, ...outerSpecOptions } = spec.raw;
+      const innerTemplate = await convertSpecSnapshotsToTemplates(spec);
+      if (innerTemplate) {
+        options.template = innerTemplate;
+      }
+      const mergedOptions = composeCreateVmOptions([
+        outerSpecOptions,
+        options
+      ]);
+      options = {
+        ...options,
+        ...mergedOptions
+      };
+      if (!options.with && spec.with) {
+        options.with = spec.with;
+      }
+    }
+    const builders = options.with || options.template?.with || {};
     const { with: _, ...baseConfig } = options;
     let config = baseConfig;
+    if (config.template instanceof VmTemplate) {
+      config.template = await processTemplateTree(config.template);
+    }
     if (config.template instanceof VmTemplate) {
       config.template = await ensureNestedTemplates(
         config.template,
@@ -5124,7 +5314,7 @@ class VmsNamespace {
     const keys = Object.keys(builders);
     for (const key of keys) {
       const builder = builders[key];
-      if (builder) {
+      if (builder?.configure) {
         config = await builder.configure(config);
       }
     }
@@ -5140,12 +5330,6 @@ class VmsNamespace {
       const builder = builders[key];
       if (builder) {
         const instance = builder.createInstance();
-        builder.createInstance = () => {
-          throw new Error(
-            `Attempted to create multiple instances from the same VmWith ${key}: ${builder.constructor.name}`
-          );
-        };
-        builder.instance = instance;
         instance._init(vm);
         vm[key] = instance;
       }
@@ -5164,6 +5348,30 @@ class VmsNamespace {
   async list() {
     return this.apiClient.get("/v1/vms", void 0);
   }
+  /**
+   * Get VM by ID.
+   * @param vmId The ID of the VM
+   * @param allowedSpecs Array of allowed specs (currently only 1 supported, always uses the first)
+   * @returns The VM instance configured with builders from the spec
+   */
+  async get({
+    vmId,
+    allowedSpecs
+  }) {
+    const vm = new Vm(vmId, this.apiClient);
+    const spec = allowedSpecs?.[0];
+    if (spec) {
+      const allBuilders = collectSpecBuilders(spec);
+      for (const [key, builder] of Object.entries(allBuilders)) {
+        if (builder) {
+          const instance = builder.createInstance();
+          instance._init(vm);
+          vm[key] = instance;
+        }
+      }
+    }
+    return { vm, spec };
+  }
   /**
    * Create a VM instance by ID without making an api call.
    */
@@ -5176,11 +5384,68 @@ class VmsNamespace {
     });
   }
 }
-class VmTemplate {
-  raw;
-  constructor(template) {
-    this.raw = template;
+class VmSnapshotsNamespace {
+  constructor(apiClient) {
+    this.apiClient = apiClient;
   }
+  async ensure(options) {
+    return this.apiClient.post("/v1/vms/snapshots", {
+      body: {
+        ...options,
+        template: options.template?.raw
+      }
+    });
+  }
+}
+async function processTemplateTree(template) {
+  for (const key in template.with) {
+    const builder = template.with[key];
+    if (builder) {
+      if (builder.configureTemplate) {
+        template = await builder.configureTemplate(template);
+      }
+      if (builder.configureNestedTemplate) {
+        let nestedTemplate;
+        if (template.raw.template instanceof VmTemplate) {
+          nestedTemplate = template.raw.template;
+        } else {
+          nestedTemplate = new VmTemplate({});
+          template.raw.template = nestedTemplate;
+        }
+        template.raw.template = await builder.configureNestedTemplate(nestedTemplate);
+      }
+    }
+  }
+  if (template.raw.template instanceof VmTemplate) {
+    template.raw.template = await processTemplateTree(template.raw.template);
+  }
+  return template;
+}
+async function ensureNestedTemplates(template, snapshots) {
+  let templates = [template];
+  while (templates.at(-1)?.raw.template instanceof VmTemplate) {
+    let innerTemplate = templates.at(-1).raw.template;
+    templates.at(-1).raw.template = void 0;
+    templates.push(innerTemplate);
+  }
+  return await layerTemplates(templates, snapshots);
+}
+async function layerTemplates(templates, snapshots) {
+  let lastTemplate = templates.pop();
+  const { snapshotId } = await snapshots.ensure({
+    template: lastTemplate
+  });
+  let lastSnapshotId = snapshotId;
+  while (templates.length > 0) {
+    const template = templates.pop();
+    template.raw.snapshotId = lastSnapshotId;
+    const { snapshotId: snapshotId2 } = await snapshots.ensure({
+      template
+    });
+    lastSnapshotId = snapshotId2;
+    lastTemplate = template;
+  }
+  return lastTemplate;
 }
 
 class Freestyle {
@@ -5255,6 +5520,7 @@ exports.Identity = Identity;
 exports.Vm = Vm;
 exports.VmBuilder = VmBuilder;
 exports.VmService = VmService;
+exports.VmSpec = VmSpec;
 exports.VmTemplate = VmTemplate;
 exports.VmWith = VmWith;
 exports.VmWithInstance = VmWithInstance;

package/index.d.cts

@@ -10439,7 +10439,9 @@ declare class RunsNamespace {
      */
     create<T = any>({ code, ...config }: {
         code: string;
-    } & PostExecuteV2ScriptRequestBody["config"]): Promise<ResponsePostExecuteV2Script200>;
+    } & PostExecuteV2ScriptRequestBody["config"]): Promise<ResponsePostExecuteV2Script200 & {
+        result: T;
+    }>;
     /**
      * List execution runs.
      */
@@ -10897,13 +10899,50 @@ declare class VmWithInstance {
 declare abstract class VmWith<TInstance extends VmWithInstance = VmWithInstance> {
     instance: TInstance;
     /**
+     * @deprecated Use configureSpec instead.
      * Transform the VM configuration by applying this component's config.
      * Acts as middleware - receives existing config, returns transformed config.
      *
      * @param existingConfig - The current VM configuration
      * @returns The transformed VM configuration with this component's changes applied
      */
-    abstract configure(existingConfig: CreateVmOptions): CreateVmOptions | Promise<CreateVmOptions>;
+    configure?(existingConfig: CreateVmOptions): CreateVmOptions | Promise<CreateVmOptions>;
+    /**
+     * Configure the spec that this VmWith is directly attached to.
+     * Override this to modify the parent spec's configuration.
+     *
+     * @param spec - The VmSpec this VmWith is attached to
+     * @returns The transformed VmSpec with this component's changes applied
+     */
+    configureSpec?(spec: VmSpec): VmSpec | Promise<VmSpec>;
+    /**
+     * Configure the snapshot spec inside the current spec.
+     * If no snapshot spec exists, one will be created.
+     * Override this to modify the inner snapshot layer's configuration.
+     *
+     * @param spec - The snapshot VmSpec (created if it doesn't exist)
+     * @returns The transformed snapshot VmSpec with this component's changes applied
+     */
+    configureSnapshotSpec?(spec: VmSpec): VmSpec | Promise<VmSpec>;
+    /**
+     * @deprecated Use configureSpec instead
+     * Configure the template that this VmWith is directly attached to.
+     * Override this to modify the parent template's configuration.
+     *
+     * @param template - The VmTemplate this VmWith is attached to
+     * @returns The transformed VmTemplate with this component's changes applied
+     */
+    configureTemplate?(template: VmTemplate): VmTemplate | Promise<VmTemplate>;
+    /**
+     * @deprecated Use configureSnapshotSpec instead
+     * Configure the nested template inside the current template.
+     * If no nested template exists, one will be created.
+     * Override this to modify the inner template layer's configuration.
+     *
+     * @param template - The nested VmTemplate (created if it doesn't exist)
+     * @returns The transformed nested VmTemplate with this component's changes applied
+     */
+    configureNestedTemplate?(template: VmTemplate): VmTemplate | Promise<VmTemplate>;
     /**
      * Create an instance of this component that will be attached to the VM.
      * Override this to provide custom interaction methods for your component.
@@ -10916,6 +10955,23 @@ declare abstract class VmWith<TInstance extends VmWithInstance = VmWithInstance>
      * Uses the same merging strategy as the main compose function.
      */
     protected compose(...configs: CreateVmOptions[]): CreateVmOptions;
+    /**
+     * Helper method to compose multiple VmSpecs together.
+     * Uses the same merging strategy as the main compose function.
+     * Useful in configureSpec and configureSnapshotSpec methods.
+     */
+    protected composeSpecs(...specs: VmSpec[]): VmSpec;
+    /**
+     * @deprecated Use composeSpecs instead
+     * Helper method to compose multiple VmTemplates together.
+     * Uses the same merging strategy as the main compose function.
+     * Useful in configureTemplate and configureNestedTemplate methods.
+     */
+    protected composeTemplates(...templates: VmTemplate[]): VmTemplate;
+    /**
+     * @deprecated This method is no longer needed. Use vms.get with allowedSpecs instead.
+     */
+    configureReturnedVm(vm: Vm, template: VmTemplate): Promise<void>;
 }
 declare const VmService: typeof VmWith;
 declare const VmBuilder: typeof VmWith;
@@ -11032,16 +11088,35 @@ declare class Vm {
         rootfsSizeGb: number;
         vcpuCount: number;
     }): Promise<ResponsePostV1VmsIdResize200>;
+    /**
+     * Create a VM instance by ID without making an api call.
+     */
+    ref({ vmId }: {
+        vmId: string;
+    }): Vm;
+    delete({ vmId }: {
+        vmId: string;
+    }): Promise<ResponseDeleteV1VmsVmId200>;
 }
-type CreateVmOptions = Exclude<PostV1VmsRequestBody, "template"> & {
-    template?: VmTemplate | Exclude<PostV1VmsRequestBody, "template">["template"];
+type TemplateOptions = CreateSnapshotRequest["template"] & {
+    template?: VmTemplate<Record<string, VmWith>>;
 };
-declare class VmSnapshotsNamespace {
-    private apiClient;
-    constructor(apiClient: ApiClient);
-    ensure(options: Exclude<PostV1VmsSnapshotsRequestBody, "template"> & {
-        template?: VmTemplate;
-    }): Promise<ResponsePostV1VmsSnapshots200>;
+declare class VmTemplate<T extends Record<string, VmWith> = Record<string, VmWith>> {
+    raw: TemplateOptions;
+    readonly with: T;
+    constructor(template: TemplateOptions & {
+        with?: T;
+    });
+}
+type VmSpecOptions = TemplateOptions & {
+    snapshot?: VmSpec;
+};
+declare class VmSpec<T extends Record<string, VmWith> = Record<string, VmWith>> {
+    raw: VmSpecOptions;
+    readonly with: T;
+    constructor(spec: VmSpecOptions & {
+        with?: T;
+    });
 }
 declare class VmsNamespace {
     private apiClient;
@@ -11054,6 +11129,8 @@ declare class VmsNamespace {
      */
     create<T extends Record<string, VmWith>>(options?: CreateVmOptions & {
         with?: T;
+        template?: VmTemplate<T>;
+        spec?: VmSpec<T>;
     }): Promise<ResponsePostV1Vms200 & {
         vmId: string;
         vm: Vm & {
@@ -11066,6 +11143,21 @@ declare class VmsNamespace {
      * @returns List of VMs with their states and metadata
      */
     list(): Promise<ResponseGetV1Vms200>;
+    /**
+     * Get VM by ID.
+     * @param vmId The ID of the VM
+     * @param allowedSpecs Array of allowed specs (currently only 1 supported, always uses the first)
+     * @returns The VM instance configured with builders from the spec
+     */
+    get<T extends Record<string, VmWith>>({ vmId, allowedSpecs, }: {
+        vmId: string;
+        allowedSpecs?: [VmSpec<T>];
+    }): Promise<{
+        vm: Vm & {
+            [K in keyof T]: ReturnType<T[K]["createInstance"]>;
+        };
+        spec?: VmSpec<T>;
+    }>;
     /**
      * Create a VM instance by ID without making an api call.
      */
@@ -11076,13 +11168,16 @@ declare class VmsNamespace {
         vmId: string;
     }): Promise<ResponseDeleteV1VmsVmId200>;
 }
-type TemplateOptions = CreateSnapshotRequest["template"] & {
-    template?: VmTemplate;
-};
-declare class VmTemplate {
-    raw: TemplateOptions;
-    constructor(template: TemplateOptions);
+declare class VmSnapshotsNamespace {
+    private apiClient;
+    constructor(apiClient: ApiClient);
+    ensure(options: Exclude<PostV1VmsSnapshotsRequestBody, "template"> & {
+        template?: VmTemplate;
+    }): Promise<ResponsePostV1VmsSnapshots200>;
 }
+type CreateVmOptions = Omit<PostV1VmsRequestBody, "template"> & {
+    template?: VmTemplate | Exclude<PostV1VmsRequestBody, "template">["template"];
+};
 
 type FreestyleOptions = ApiClientConfig;
 declare class Freestyle {
@@ -11105,5 +11200,5 @@ declare class Freestyle {
  */
 declare const freestyle: Freestyle;
 
-export { Deployment, errors as Errors, FileSystem, Freestyle, GitRepo, Identity, requests as Requests, responses as Responses, Vm, VmBuilder, VmService, VmTemplate, VmWith, VmWithInstance, freestyle };
+export { Deployment, errors as Errors, FileSystem, Freestyle, GitRepo, Identity, requests as Requests, responses as Responses, Vm, VmBuilder, VmService, VmSpec, VmTemplate, VmWith, VmWithInstance, freestyle };
 export type { CreateVmOptions, FreestyleOptions };

package/index.d.mts

@@ -10439,7 +10439,9 @@ declare class RunsNamespace {
      */
     create<T = any>({ code, ...config }: {
         code: string;
-    } & PostExecuteV2ScriptRequestBody["config"]): Promise<ResponsePostExecuteV2Script200>;
+    } & PostExecuteV2ScriptRequestBody["config"]): Promise<ResponsePostExecuteV2Script200 & {
+        result: T;
+    }>;
     /**
      * List execution runs.
      */
@@ -10897,13 +10899,50 @@ declare class VmWithInstance {
 declare abstract class VmWith<TInstance extends VmWithInstance = VmWithInstance> {
     instance: TInstance;
     /**
+     * @deprecated Use configureSpec instead.
      * Transform the VM configuration by applying this component's config.
      * Acts as middleware - receives existing config, returns transformed config.
      *
      * @param existingConfig - The current VM configuration
      * @returns The transformed VM configuration with this component's changes applied
      */
-    abstract configure(existingConfig: CreateVmOptions): CreateVmOptions | Promise<CreateVmOptions>;
+    configure?(existingConfig: CreateVmOptions): CreateVmOptions | Promise<CreateVmOptions>;
+    /**
+     * Configure the spec that this VmWith is directly attached to.
+     * Override this to modify the parent spec's configuration.
+     *
+     * @param spec - The VmSpec this VmWith is attached to
+     * @returns The transformed VmSpec with this component's changes applied
+     */
+    configureSpec?(spec: VmSpec): VmSpec | Promise<VmSpec>;
+    /**
+     * Configure the snapshot spec inside the current spec.
+     * If no snapshot spec exists, one will be created.
+     * Override this to modify the inner snapshot layer's configuration.
+     *
+     * @param spec - The snapshot VmSpec (created if it doesn't exist)
+     * @returns The transformed snapshot VmSpec with this component's changes applied
+     */
+    configureSnapshotSpec?(spec: VmSpec): VmSpec | Promise<VmSpec>;
+    /**
+     * @deprecated Use configureSpec instead
+     * Configure the template that this VmWith is directly attached to.
+     * Override this to modify the parent template's configuration.
+     *
+     * @param template - The VmTemplate this VmWith is attached to
+     * @returns The transformed VmTemplate with this component's changes applied
+     */
+    configureTemplate?(template: VmTemplate): VmTemplate | Promise<VmTemplate>;
+    /**
+     * @deprecated Use configureSnapshotSpec instead
+     * Configure the nested template inside the current template.
+     * If no nested template exists, one will be created.
+     * Override this to modify the inner template layer's configuration.
+     *
+     * @param template - The nested VmTemplate (created if it doesn't exist)
+     * @returns The transformed nested VmTemplate with this component's changes applied
+     */
+    configureNestedTemplate?(template: VmTemplate): VmTemplate | Promise<VmTemplate>;
     /**
      * Create an instance of this component that will be attached to the VM.
      * Override this to provide custom interaction methods for your component.
@@ -10916,6 +10955,23 @@ declare abstract class VmWith<TInstance extends VmWithInstance = VmWithInstance>
      * Uses the same merging strategy as the main compose function.
      */
     protected compose(...configs: CreateVmOptions[]): CreateVmOptions;
+    /**
+     * Helper method to compose multiple VmSpecs together.
+     * Uses the same merging strategy as the main compose function.
+     * Useful in configureSpec and configureSnapshotSpec methods.
+     */
+    protected composeSpecs(...specs: VmSpec[]): VmSpec;
+    /**
+     * @deprecated Use composeSpecs instead
+     * Helper method to compose multiple VmTemplates together.
+     * Uses the same merging strategy as the main compose function.
+     * Useful in configureTemplate and configureNestedTemplate methods.
+     */
+    protected composeTemplates(...templates: VmTemplate[]): VmTemplate;
+    /**
+     * @deprecated This method is no longer needed. Use vms.get with allowedSpecs instead.
+     */
+    configureReturnedVm(vm: Vm, template: VmTemplate): Promise<void>;
 }
 declare const VmService: typeof VmWith;
 declare const VmBuilder: typeof VmWith;
@@ -11032,16 +11088,35 @@ declare class Vm {
         rootfsSizeGb: number;
         vcpuCount: number;
     }): Promise<ResponsePostV1VmsIdResize200>;
+    /**
+     * Create a VM instance by ID without making an api call.
+     */
+    ref({ vmId }: {
+        vmId: string;
+    }): Vm;
+    delete({ vmId }: {
+        vmId: string;
+    }): Promise<ResponseDeleteV1VmsVmId200>;
 }
-type CreateVmOptions = Exclude<PostV1VmsRequestBody, "template"> & {
-    template?: VmTemplate | Exclude<PostV1VmsRequestBody, "template">["template"];
+type TemplateOptions = CreateSnapshotRequest["template"] & {
+    template?: VmTemplate<Record<string, VmWith>>;
 };
-declare class VmSnapshotsNamespace {
-    private apiClient;
-    constructor(apiClient: ApiClient);
-    ensure(options: Exclude<PostV1VmsSnapshotsRequestBody, "template"> & {
-        template?: VmTemplate;
-    }): Promise<ResponsePostV1VmsSnapshots200>;
+declare class VmTemplate<T extends Record<string, VmWith> = Record<string, VmWith>> {
+    raw: TemplateOptions;
+    readonly with: T;
+    constructor(template: TemplateOptions & {
+        with?: T;
+    });
+}
+type VmSpecOptions = TemplateOptions & {
+    snapshot?: VmSpec;
+};
+declare class VmSpec<T extends Record<string, VmWith> = Record<string, VmWith>> {
+    raw: VmSpecOptions;
+    readonly with: T;
+    constructor(spec: VmSpecOptions & {
+        with?: T;
+    });
 }
 declare class VmsNamespace {
     private apiClient;
@@ -11054,6 +11129,8 @@ declare class VmsNamespace {
      */
     create<T extends Record<string, VmWith>>(options?: CreateVmOptions & {
         with?: T;
+        template?: VmTemplate<T>;
+        spec?: VmSpec<T>;
     }): Promise<ResponsePostV1Vms200 & {
         vmId: string;
         vm: Vm & {
@@ -11066,6 +11143,21 @@ declare class VmsNamespace {
      * @returns List of VMs with their states and metadata
      */
     list(): Promise<ResponseGetV1Vms200>;
+    /**
+     * Get VM by ID.
+     * @param vmId The ID of the VM
+     * @param allowedSpecs Array of allowed specs (currently only 1 supported, always uses the first)
+     * @returns The VM instance configured with builders from the spec
+     */
+    get<T extends Record<string, VmWith>>({ vmId, allowedSpecs, }: {
+        vmId: string;
+        allowedSpecs?: [VmSpec<T>];
+    }): Promise<{
+        vm: Vm & {
+            [K in keyof T]: ReturnType<T[K]["createInstance"]>;
+        };
+        spec?: VmSpec<T>;
+    }>;
     /**
      * Create a VM instance by ID without making an api call.
      */
@@ -11076,13 +11168,16 @@ declare class VmsNamespace {
         vmId: string;
     }): Promise<ResponseDeleteV1VmsVmId200>;
 }
-type TemplateOptions = CreateSnapshotRequest["template"] & {
-    template?: VmTemplate;
-};
-declare class VmTemplate {
-    raw: TemplateOptions;
-    constructor(template: TemplateOptions);
+declare class VmSnapshotsNamespace {
+    private apiClient;
+    constructor(apiClient: ApiClient);
+    ensure(options: Exclude<PostV1VmsSnapshotsRequestBody, "template"> & {
+        template?: VmTemplate;
+    }): Promise<ResponsePostV1VmsSnapshots200>;
 }
+type CreateVmOptions = Omit<PostV1VmsRequestBody, "template"> & {
+    template?: VmTemplate | Exclude<PostV1VmsRequestBody, "template">["template"];
+};
 
 type FreestyleOptions = ApiClientConfig;
 declare class Freestyle {
@@ -11105,5 +11200,5 @@ declare class Freestyle {
  */
 declare const freestyle: Freestyle;
 
-export { Deployment, errors as Errors, FileSystem, Freestyle, GitRepo, Identity, requests as Requests, responses as Responses, Vm, VmBuilder, VmService, VmTemplate, VmWith, VmWithInstance, freestyle };
+export { Deployment, errors as Errors, FileSystem, Freestyle, GitRepo, Identity, requests as Requests, responses as Responses, Vm, VmBuilder, VmService, VmSpec, VmTemplate, VmWith, VmWithInstance, freestyle };
 export type { CreateVmOptions, FreestyleOptions };

package/index.mjs

@@ -4622,6 +4622,36 @@ class VmWith {
   compose(...configs) {
     return composeCreateVmOptions(configs);
   }
+  /**
+   * Helper method to compose multiple VmSpecs together.
+   * Uses the same merging strategy as the main compose function.
+   * Useful in configureSpec and configureSnapshotSpec methods.
+   */
+  composeSpecs(...specs) {
+    return composeVmSpecs(specs);
+  }
+  /**
+   * @deprecated Use composeSpecs instead
+   * Helper method to compose multiple VmTemplates together.
+   * Uses the same merging strategy as the main compose function.
+   * Useful in configureTemplate and configureNestedTemplate methods.
+   */
+  composeTemplates(...templates) {
+    return composeVmTemplates(templates);
+  }
+  /**
+   * @deprecated This method is no longer needed. Use vms.get with allowedSpecs instead.
+   */
+  async configureReturnedVm(vm, template) {
+    if (template.raw) {
+      if (this.configure) {
+        await this.configure(template.raw);
+      }
+      const instance = this.createInstance();
+      instance._init(vm);
+      this.instance = instance;
+    }
+  }
 }
 const VmService = VmWith;
 const VmBuilder = VmWith;
@@ -4873,6 +4903,73 @@ function composeCreateVmOptions(arr) {
   }
   return result;
 }
+function composeVmTemplates(templates) {
+  if (templates.length === 0) {
+    return new VmTemplate({});
+  }
+  if (templates.length === 1) {
+    return templates[0];
+  }
+  const rawConfigs = templates.map((t) => t.raw);
+  const composedRaw = composeCreateVmOptions(
+    rawConfigs
+  );
+  const mergedWith = {};
+  for (const template of templates) {
+    for (const key in template.with) {
+      const builder = template.with[key];
+      if (builder) {
+        mergedWith[key] = builder;
+      }
+    }
+  }
+  const nestedTemplates = templates.map((t) => t.raw.template).filter((t) => t instanceof VmTemplate);
+  let nestedTemplate;
+  if (nestedTemplates.length > 0) {
+    nestedTemplate = composeVmTemplates(nestedTemplates);
+  }
+  const result = new VmTemplate({
+    ...composedRaw,
+    template: nestedTemplate,
+    with: mergedWith
+  });
+  return result;
+}
+function composeVmSpecs(specs) {
+  if (specs.length === 0) {
+    return new VmSpec({});
+  }
+  if (specs.length === 1) {
+    return specs[0];
+  }
+  const rawConfigs = specs.map((s) => {
+    const { snapshot, ...rest } = s.raw;
+    return rest;
+  });
+  const composedRaw = composeCreateVmOptions(
+    rawConfigs
+  );
+  const mergedWith = {};
+  for (const spec of specs) {
+    for (const key in spec.with) {
+      const builder = spec.with[key];
+      if (builder) {
+        mergedWith[key] = builder;
+      }
+    }
+  }
+  const nestedSpecs = specs.map((s) => s.raw.snapshot).filter((s) => s instanceof VmSpec);
+  let nestedSpec;
+  if (nestedSpecs.length > 0) {
+    nestedSpec = composeVmSpecs(nestedSpecs);
+  }
+  const result = new VmSpec({
+    ...composedRaw,
+    snapshot: nestedSpec,
+    with: mergedWith
+  });
+  return result;
+}
 
 class VmTerminals {
   constructor(vmId, client) {
@@ -5052,51 +5149,121 @@ class Vm {
     return this.apiClient.post("/v1/vms/{id}/resize", {
       params: { id: this.vmId },
       body: { memSizeGb, rootfsSizeGb, vcpuCount }
+      // Temporarily cast to any
     });
   }
-}
-class VmSnapshotsNamespace {
-  constructor(apiClient) {
-    this.apiClient = apiClient;
+  /**
+   * Create a VM instance by ID without making an api call.
+   */
+  ref({ vmId }) {
+    return new Vm(vmId, this.apiClient);
   }
-  async ensure(options) {
-    if (options.template.raw.template instanceof VmTemplate) {
-      options.template = await ensureNestedTemplates(options.template, this);
-    }
-    return this.apiClient.post("/v1/vms/snapshots", {
-      body: {
-        ...options,
-        // @ts-ignore
-        template: options.template?.raw
-      }
+  async delete({ vmId }) {
+    return this.apiClient.delete("/v1/vms/{vm_id}", {
+      params: { vm_id: vmId }
     });
   }
 }
-async function ensureNestedTemplates(template, snapshots) {
-  let templates = [template];
-  while (templates.at(-1)?.raw.template instanceof VmTemplate) {
-    let innerTemplate = templates.at(-1).raw.template;
-    templates.at(-1).raw.template = void 0;
-    templates.push(innerTemplate);
+class VmTemplate {
+  raw;
+  with;
+  constructor(template) {
+    const { with: withBuilders, ...rest } = template;
+    this.raw = rest;
+    this.with = withBuilders ?? {};
   }
-  return await layerTemplates(templates, snapshots);
 }
-async function layerTemplates(templates, snapshots) {
-  let lastTemplate = templates.pop();
-  const { snapshotId } = await snapshots.ensure({
-    template: lastTemplate
+class VmSpec {
+  raw;
+  with;
+  constructor(spec) {
+    const { with: withBuilders, ...rest } = spec;
+    this.raw = rest;
+    this.with = withBuilders ?? {};
+  }
+}
+async function convertSpecSnapshotsToTemplates(spec, processBuilders = true) {
+  if (!spec.raw.snapshot) {
+    return void 0;
+  }
+  let innerSpec = spec.raw.snapshot;
+  if (processBuilders) {
+    innerSpec = await processSpecTree(innerSpec);
+  }
+  const { snapshot: nestedSnapshot, ...innerRaw } = innerSpec.raw;
+  let nestedTemplate;
+  if (nestedSnapshot instanceof VmSpec) {
+    nestedTemplate = await convertSpecSnapshotsToTemplates(innerSpec, false);
+  }
+  return new VmTemplate({
+    ...innerRaw,
+    template: nestedTemplate,
+    with: innerSpec.with
   });
-  let lastSnapshotId = snapshotId;
-  while (templates.length > 0) {
-    const template = templates.pop();
-    template.raw.snapshotId = lastSnapshotId;
-    const { snapshotId: snapshotId2 } = await snapshots.ensure({
-      template
-    });
-    lastSnapshotId = snapshotId2;
-    lastTemplate = template;
+}
+async function processOuterSpecBuilders(spec) {
+  for (const key in spec.with) {
+    const builder = spec.with[key];
+    if (builder) {
+      if (builder.configureSpec) {
+        spec = await builder.configureSpec(spec);
+      }
+      if (builder.configureSnapshotSpec) {
+        let snapshotSpec;
+        if (spec.raw.snapshot instanceof VmSpec) {
+          snapshotSpec = spec.raw.snapshot;
+        } else {
+          snapshotSpec = new VmSpec({});
+          spec.raw.snapshot = snapshotSpec;
+        }
+        spec.raw.snapshot = await builder.configureSnapshotSpec(snapshotSpec);
+      }
+    }
   }
-  return lastTemplate;
+  return spec;
+}
+async function processSpecTree(spec) {
+  for (const key in spec.with) {
+    const builder = spec.with[key];
+    if (builder) {
+      if (builder.configureSpec) {
+        spec = await builder.configureSpec(spec);
+      }
+      if (builder.configureSnapshotSpec) {
+        let snapshotSpec;
+        if (spec.raw.snapshot instanceof VmSpec) {
+          snapshotSpec = spec.raw.snapshot;
+        } else {
+          snapshotSpec = new VmSpec({});
+          spec.raw.snapshot = snapshotSpec;
+        }
+        spec.raw.snapshot = await builder.configureSnapshotSpec(snapshotSpec);
+      }
+    }
+  }
+  if (spec.raw.snapshot instanceof VmSpec) {
+    spec.raw.snapshot = await processSpecTree(spec.raw.snapshot);
+  }
+  return spec;
+}
+function collectSpecBuilders(spec) {
+  const builders = {};
+  if (spec.with) {
+    for (const [key, builder] of Object.entries(spec.with)) {
+      if (builder) {
+        builders[key] = builder;
+      }
+    }
+  }
+  if (spec.raw.snapshot instanceof VmSpec) {
+    const nestedBuilders = collectSpecBuilders(spec.raw.snapshot);
+    for (const [key, builder] of Object.entries(nestedBuilders)) {
+      if (!builders[key] && builder) {
+        builders[key] = builder;
+      }
+    }
+  }
+  return builders;
 }
 class VmsNamespace {
   constructor(apiClient) {
@@ -5110,9 +5277,32 @@ class VmsNamespace {
    * @returns A VM instance representing the created VM
    */
   async create(options = {}) {
-    const builders = options.with || {};
+    if (options.spec instanceof VmSpec) {
+      let spec = options.spec;
+      spec = await processOuterSpecBuilders(spec);
+      const { snapshot, ...outerSpecOptions } = spec.raw;
+      const innerTemplate = await convertSpecSnapshotsToTemplates(spec);
+      if (innerTemplate) {
+        options.template = innerTemplate;
+      }
+      const mergedOptions = composeCreateVmOptions([
+        outerSpecOptions,
+        options
+      ]);
+      options = {
+        ...options,
+        ...mergedOptions
+      };
+      if (!options.with && spec.with) {
+        options.with = spec.with;
+      }
+    }
+    const builders = options.with || options.template?.with || {};
     const { with: _, ...baseConfig } = options;
     let config = baseConfig;
+    if (config.template instanceof VmTemplate) {
+      config.template = await processTemplateTree(config.template);
+    }
     if (config.template instanceof VmTemplate) {
       config.template = await ensureNestedTemplates(
         config.template,
@@ -5122,7 +5312,7 @@ class VmsNamespace {
     const keys = Object.keys(builders);
     for (const key of keys) {
       const builder = builders[key];
-      if (builder) {
+      if (builder?.configure) {
         config = await builder.configure(config);
       }
     }
@@ -5138,12 +5328,6 @@ class VmsNamespace {
       const builder = builders[key];
       if (builder) {
         const instance = builder.createInstance();
-        builder.createInstance = () => {
-          throw new Error(
-            `Attempted to create multiple instances from the same VmWith ${key}: ${builder.constructor.name}`
-          );
-        };
-        builder.instance = instance;
         instance._init(vm);
         vm[key] = instance;
       }
@@ -5162,6 +5346,30 @@ class VmsNamespace {
   async list() {
     return this.apiClient.get("/v1/vms", void 0);
   }
+  /**
+   * Get VM by ID.
+   * @param vmId The ID of the VM
+   * @param allowedSpecs Array of allowed specs (currently only 1 supported, always uses the first)
+   * @returns The VM instance configured with builders from the spec
+   */
+  async get({
+    vmId,
+    allowedSpecs
+  }) {
+    const vm = new Vm(vmId, this.apiClient);
+    const spec = allowedSpecs?.[0];
+    if (spec) {
+      const allBuilders = collectSpecBuilders(spec);
+      for (const [key, builder] of Object.entries(allBuilders)) {
+        if (builder) {
+          const instance = builder.createInstance();
+          instance._init(vm);
+          vm[key] = instance;
+        }
+      }
+    }
+    return { vm, spec };
+  }
   /**
    * Create a VM instance by ID without making an api call.
    */
@@ -5174,11 +5382,68 @@ class VmsNamespace {
     });
   }
 }
-class VmTemplate {
-  raw;
-  constructor(template) {
-    this.raw = template;
+class VmSnapshotsNamespace {
+  constructor(apiClient) {
+    this.apiClient = apiClient;
   }
+  async ensure(options) {
+    return this.apiClient.post("/v1/vms/snapshots", {
+      body: {
+        ...options,
+        template: options.template?.raw
+      }
+    });
+  }
+}
+async function processTemplateTree(template) {
+  for (const key in template.with) {
+    const builder = template.with[key];
+    if (builder) {
+      if (builder.configureTemplate) {
+        template = await builder.configureTemplate(template);
+      }
+      if (builder.configureNestedTemplate) {
+        let nestedTemplate;
+        if (template.raw.template instanceof VmTemplate) {
+          nestedTemplate = template.raw.template;
+        } else {
+          nestedTemplate = new VmTemplate({});
+          template.raw.template = nestedTemplate;
+        }
+        template.raw.template = await builder.configureNestedTemplate(nestedTemplate);
+      }
+    }
+  }
+  if (template.raw.template instanceof VmTemplate) {
+    template.raw.template = await processTemplateTree(template.raw.template);
+  }
+  return template;
+}
+async function ensureNestedTemplates(template, snapshots) {
+  let templates = [template];
+  while (templates.at(-1)?.raw.template instanceof VmTemplate) {
+    let innerTemplate = templates.at(-1).raw.template;
+    templates.at(-1).raw.template = void 0;
+    templates.push(innerTemplate);
+  }
+  return await layerTemplates(templates, snapshots);
+}
+async function layerTemplates(templates, snapshots) {
+  let lastTemplate = templates.pop();
+  const { snapshotId } = await snapshots.ensure({
+    template: lastTemplate
+  });
+  let lastSnapshotId = snapshotId;
+  while (templates.length > 0) {
+    const template = templates.pop();
+    template.raw.snapshotId = lastSnapshotId;
+    const { snapshotId: snapshotId2 } = await snapshots.ensure({
+      template
+    });
+    lastSnapshotId = snapshotId2;
+    lastTemplate = template;
+  }
+  return lastTemplate;
 }
 
 class Freestyle {
@@ -5244,4 +5509,4 @@ function createLazyFreestyle(options = {}) {
 }
 const freestyle = createLazyFreestyle();
 
-export { Deployment, errors as Errors, FileSystem, Freestyle, GitRepo, Identity, Vm, VmBuilder, VmService, VmTemplate, VmWith, VmWithInstance, freestyle };
+export { Deployment, errors as Errors, FileSystem, Freestyle, GitRepo, Identity, Vm, VmBuilder, VmService, VmSpec, VmTemplate, VmWith, VmWithInstance, freestyle };

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "freestyle-sandboxes",
-    "version": "0.1.6",
+    "version": "0.1.8",
     "type": "module",
     "exports": {
         "require": {