> ## Documentation Index
> Fetch the complete documentation index at: https://novita.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Clonación de sandbox heredada

export const SandboxBetaVersionWarning = () => {
  if (typeof document === "undefined") {
    return null;
  } else {
    return <Warning>The following legacy features require the legacy SDK and CLI versions listed in <Link href="/docs/es/guides/sandbox-legacy-e2b-compatible" target="self">Legacy SDKs & CLI</Link>. Please note that legacy features may be less stable than production releases. If you encounter any issues while using these features, please <Link href="https://meetings-na2.hubspot.com/junyu" target="_blank">contact us</Link>.</Warning>;
  }
};

<Warning>
  Esta página heredada se conserva para los usuarios que todavía usan la línea de SDK 1.x o beta. Las nuevas integraciones con el SDK 2.x deben seguir la documentación actual de Sandbox.
</Warning>

En la etapa actual, los agentes de IA se enfrentan a una limitación fundamental al ejecutar tareas complejas: el problema de "n de 1" — la IA y los desarrolladores están confinados a un único entorno de trabajo para el razonamiento en serie. Este patrón genera varios problemas clave:

1. **Conflictos de experimentos y contaminación del entorno**. Cuando un agente de IA prueba varias soluciones, los cambios experimentales en el código pueden interferir con el flujo de trabajo principal del desarrollador o contaminar el entorno de ejecución actual. Una vez que un experimento sale mal, la recuperación a menudo requiere una reversión, y no se pueden conservar rutas de exploración valiosas.

2. **Incapacidad para explorar varias soluciones en paralelo**. Al estar limitado a un único entorno, el agente de IA solo puede probar distintos enfoques de forma secuencial. Este modo en serie no solo es ineficiente, sino que, más importante aún, limita la amplitud de la exploración de la IA: no puede validar simultáneamente múltiples hipótesis paralelas o enfoques de implementación.

3. **Escalabilidad limitada de la potencia de cómputo**. Al enfrentarse a tareas que requieren "Wide-Research" (por ejemplo, comparar 100 soluciones simultáneamente, generar por lotes múltiples versiones de implementación), la arquitectura de entorno único restringe fundamentalmente la capacidad de paralelizar el procesamiento de tareas.

La característica **"Clonación de sandbox"** permite la transición de "Deep-Research" a "Wide-Research":

1. **Arquitectura de exploración de múltiples líneas temporales**: Como un árbol de decisiones, el agente de IA puede partir del mismo estado base y crear múltiples copias independientes de sandbox, cada una explorando una ruta de solución diferente sin interferir con las demás.
2. **Capacidad real de cómputo en paralelo**: Al dividir tareas grandes en subtareas por lotes, el agente de IA puede escalar su potencia de cómputo decenas o incluso cientos de veces, procesando simultáneamente decenas o cientos de ramas de exploración.
3. **Entorno de experimentación sin riesgos**: Los sandboxes clonados están completamente aislados, lo que permite a la IA experimentar y probar libremente diversas posibilidades sin afectar al entorno original ni al flujo de trabajo principal del desarrollador.
4. **Uso eficiente de recursos**: Aunque se pueden iniciar simultáneamente múltiples instancias de sandbox, mediante la gestión dinámica y la terminación oportuna de las ramas (instancias de sandbox) que ya no aportan valor, el consumo global de recursos de cómputo puede mantenerse dentro de un rango razonable.

Esta capacidad permite a los agentes de IA superar los cuellos de botella de rendimiento actuales, pasando de ofrecer sugerencias teóricas a entregar soluciones fiables que han sido verificadas en paralelo y probadas realmente, logrando de verdad la capacidad de explorar, iterar y resolver problemas complejos de forma autónoma.

<SandboxBetaVersionWarning />

## Terminología

* **Sandbox original**: La instancia de sandbox original que se está clonando.
* **Nuevo sandbox**: La nueva instancia de sandbox creada mediante la operación de clonación.

## Descripción general de la característica

Actualmente, la característica de clonación de sandbox admite los dos escenarios siguientes:

* Clonar un sandbox en estado Running
* Clonar un sandbox en estado Paused

### Clonar un sandbox en ejecución

**Durante el proceso de clonación:**

* El sandbox original se suspenderá brevemente durante la clonación;
* La instancia de sandbox no estará disponible durante la suspensión;
* La duración de la suspensión es cercana al tiempo requerido para una única operación de pausa.

**Una vez completada la clonación:**

**Sandbox original:**

* El estado se restaura a running;
* El registro de pausa existente se actualizará a un nuevo registro de pausa, basado en el estado actual del sandbox;
* Se genera un nuevo registro de plantilla de snapshot (para eliminar esta plantilla de snapshot, primero debes terminar tanto el sandbox original como los sandboxes clonados);

**Nuevo sandbox:**

* El estado es running;
* Listo para usarse de inmediato.

### Clonar un sandbox pausado

**Durante el proceso de clonación:**

Cuando el sandbox original está en estado pausado:

* El proceso de clonación no activará el inicio del sandbox original;
* El sandbox original permanece en estado pausado.

**Una vez completada la clonación:**

**Sandbox original:**

* El registro de pausa existente no se borra;
* Se genera un nuevo registro de plantilla de snapshot (para eliminar esta plantilla de snapshot, primero debes terminar tanto el sandbox original como los sandboxes clonados);

**Nuevo sandbox:**

* El estado es running;
* Listo para usarse de inmediato.

### Reglas de herencia de atributos del nuevo sandbox

| Atributo               | Heredado |
| ---------------------- | -------- |
| reanudación automática | Sí       |
| pausa automática       | No       |

## Descripción de parámetros

* `count`: El número de instancias de sandbox que se van a clonar. El valor mínimo es 1 y el máximo no debe superar el límite de instancias de sandbox en ejecución concurrentes de la plataforma (consulta: [Límite de cuota de sandbox](/docs/es/guides/sandbox-quota-limit));
* `strict`: Si se debe clonar estrictamente según el número especificado en el parámetro `count`; el valor predeterminado es false.
  * `true`: Si el número de instancias clonadas correctamente es menor que `count`, se devuelve un error de clonación; los sandboxes creados correctamente se liberarán automáticamente.
  * `false`: Devuelve el número real de instancias de sandbox clonadas correctamente.
* `timeout`(`timeoutMs`): El tiempo de espera para clonar instancias de sandbox.
  * Si no se especifica:
    * Cuando el sandbox original está en estado running, hereda su configuración de tiempo de espera;
    * Cuando el sandbox original está en estado paused, se usa el valor predeterminado de 5 minutos.

## Valor de retorno

Después de una operación de clonación correcta, se devuelve un objeto que contiene las siguientes propiedades:

| Propiedad              | Descripción                                                             |
| ---------------------- | ----------------------------------------------------------------------- |
| `sandboxes`            | Lista de instancias de sandbox clonadas correctamente                   |
| `count`                | Número de sandboxes clonados correctamente                              |
| `snapshot_template_id` | ID de la plantilla de snapshot generada durante el proceso de clonación |

## Ejemplos de código

<CodeGroup>
  ```python Python icon="python" theme={"system"}
  from novita_sandbox.core import Sandbox

  # Create a sandbox
  sandbox = Sandbox.create(template="base")
  # clone
  clones = Sandbox.clone(sandbox.sandbox_id, 2)

  print("snapshot:", clones.snapshot_template_id)
  for sbx in clones:
      print("clone sandbox:", sbx.sandbox_id)
  ```

  ```js JavaScript & TypeScript icon="js" theme={"system"}
  import { Sandbox } from '@novita-sandbox/core'

  // Create a sandbox
  const sandbox = await Sandbox.create('base')

  // clone
  const sbxClones = await Sandbox.clone(sandbox.sandboxId, { count: 2 })

  console.log("snapshot:", sbxClones.snapshotTemplateId)
  for (const idx in sbxClones.sandboxes) {
      console.log("clone sandboxID[" + idx + "]:", sbxClones.sandboxes[idx].sandboxId)
  }
  ```
</CodeGroup>

Además, también puedes usar Novita Sandbox CLI para clonar una instancia de sandbox especificada:

```bash Bash icon="terminal" theme={"system"}
# novita-sandbox-cli sandbox clone [sandboxID] -c [count] -s [strict] -t [timeout]
novita-sandbox-cli sandbox clone 0r0efkbfwzfp9p7qpc1c -c 2
```