> ## 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.

# Leerlauf-Timeout

export const SandboxConfigHint = () => {
  if (typeof document === "undefined") {
    return null;
  } else {
    return <Note>Before running the example code in this document, please ensure you have properly configured environment variables. For details, please refer to <a href="/docs/de/guides/sandbox-your-first-agent-sandbox#configure-environment-variables">Configure Environment Variables</a>.</Note>;
  }
};

Du kannst einen **Leerlauf-Timeout** für deine Sandboxes konfigurieren, damit sie automatisch gestoppt oder pausiert werden, wenn keine aktiven Verbindungen erkannt werden. Dies hilft, Kosten zu reduzieren, indem sichergestellt wird, dass ungenutzte Sandboxes nicht unbegrenzt weiterlaufen.

<SandboxConfigHint />

<Note>
  Der Leerlauf-Timeout wird beim Erstellen einer Sandbox über das Feld `metadata` konfiguriert. Der Schlüssel ist `idle_timeout` und der Wert ist die Anzahl der Sekunden (als String).
</Note>

## Grundlegende Verwendung

Übergebe den Schlüssel `idle_timeout` im Objekt `metadata`, wenn du eine Sandbox erstellst. Der Wert ist die Dauer des Leerlauf-Timeouts in **Sekunden** (als String). Wenn für die angegebene Dauer kein Client mit der Sandbox verbunden ist, wird die Sandbox automatisch beendet oder pausiert.

<CodeGroup>
  ```js JavaScript & TypeScript icon="js" theme={"system"}
  import { Sandbox } from 'novita-sandbox/code-interpreter'

  // Create a sandbox that will be automatically killed after 60 seconds of inactivity.
  const sandbox = await Sandbox.create({
    metadata: {
      idle_timeout: '60',
    },
  })

  // The sandbox is running...
  // After 60 seconds with no active connections, it will be killed automatically.
  ```

  ```python Python icon="python" theme={"system"}
  from novita_sandbox.code_interpreter import Sandbox

  # Create a sandbox that will be automatically killed after 60 seconds of inactivity.
  sandbox = Sandbox.create(
      metadata={
          "idle_timeout": "60",
      },
  )

  # The sandbox is running...
  # After 60 seconds with no active connections, it will be killed automatically.
  ```
</CodeGroup>

## So funktioniert der Leerlauf-Timeout

Die Leerlauf-Timeout-Funktion überwacht aktive Verbindungen zu deiner Sandbox:

1. **Wenn keine Verbindungen aktiv sind** — die Endzeit der Sandbox wird auf `current_time + idle_timeout_seconds` gesetzt.
2. **Wenn eine Verbindung wieder aktiv wird** — die Endzeit der Sandbox wird auf die ursprüngliche maximale Sandbox-Lebensdauer zurückgesetzt.
3. **Wenn der Leerlauf-Timeout ohne erneute Verbindung abläuft** — die Sandbox wird beendet (oder pausiert, wenn `autoPause` aktiviert ist).

Das bedeutet, dass eine Sandbox nicht gestoppt wird, solange mindestens ein aktiver Client mit ihr verbunden ist (z. B. über `Sandbox.connect()` oder offene WebSocket/HTTP-Verbindungen).

## Pausieren statt Beenden

Standardmäßig wird eine im Leerlauf befindliche Sandbox **beendet**, wenn der Leerlauf-Timeout abläuft. Wenn du möchtest, dass die Sandbox stattdessen **pausiert** wird, damit du sie später fortsetzen kannst, aktiviere die Option `autoPause`:

<CodeGroup>
  ```js JavaScript & TypeScript icon="js" theme={"system"}
  import { Sandbox } from 'novita-sandbox/code-interpreter'

  // Create a sandbox that will be paused (instead of killed) after 60 seconds of inactivity.
  const sandbox = await Sandbox.create({
    metadata: {
      idle_timeout: '60',
    },
    autoPause: true,
  })

  // After 60 seconds of inactivity, the sandbox will be paused.
  // You can resume it later with Sandbox.connect().
  ```

  ```python Python icon="python" theme={"system"}
  from novita_sandbox.code_interpreter import Sandbox

  # Create a sandbox that will be paused (instead of killed) after 60 seconds of inactivity.
  sandbox = Sandbox.create(
      metadata={
          "idle_timeout": "60",
      },
      auto_pause=True,
  )

  # After 60 seconds of inactivity, the sandbox will be paused.
  # You can resume it later with Sandbox.connect().
  ```
</CodeGroup>

<Note>
  Wenn `autoPause` aktiviert ist, wechselt der Sandbox-Zustand bei einem Leerlauf-Timeout zu `paused`. Du kannst dich später damit [verbinden](/docs/de/guides/sandbox-connect), um die Ausführung fortzusetzen.
</Note>

## Kombination mit anderen Metadaten

Der Metadaten-Schlüssel `idle_timeout` kann mit anderen Metadaten-Schlüsseln kombiniert werden, die du möglicherweise bereits verwendest:

<CodeGroup>
  ```js JavaScript & TypeScript icon="js" theme={"system"}
  import { Sandbox } from 'novita-sandbox/code-interpreter'

  const sandbox = await Sandbox.create({
    metadata: {
      idle_timeout: '120',
      env: 'production',
      userId: 'user-123',
    },
  })

  console.log('Sandbox ID:', sandbox.sandboxId)
  ```

  ```python Python icon="python" theme={"system"}
  from novita_sandbox.code_interpreter import Sandbox

  sandbox = Sandbox.create(
      metadata={
          "idle_timeout": "120",
          "env": "production",
          "user_id": "user-123",
      },
  )

  print("Sandbox ID:", sandbox.sandbox_id)
  ```
</CodeGroup>

## Timeout-Einschränkungen

| Einschränkung | Wert                | Beschreibung                                                                                                                    |
| ------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| **Minimum**   | 30 Sekunden         | Werte unter 30 Sekunden werden als „Leerlauf deaktiviert“ behandelt, um schnelle Start/stop-Zyklen zu verhindern.               |
| **Standard**  | Deaktiviert (0)     | Wenn `idle_timeout` nicht angegeben ist, ist die Funktion deaktiviert und die Sandbox läuft bis zu ihrer maximalen Lebensdauer. |
| **Maximum**   | Sandbox-Lebensdauer | Der Leerlauf-Timeout darf die konfigurierte `timeout` (maximale Lebensdauer) der Sandbox nicht überschreiten.                   |

<Warning>
  Wenn du `idle_timeout` auf einen Wert unterhalb des Mindestschwellenwerts (30 Sekunden) setzt, wird die Leerlauf-Timeout-Funktion für diese Sandbox **still deaktiviert**. Die Sandbox läuft weiter, bis ihre maximale Lebensdauer abläuft.
</Warning>

## Leerlauf-Timeout deaktivieren

Um den Leerlauf-Timeout für eine Sandbox explizit zu deaktivieren, lasse den Schlüssel `idle_timeout` einfach aus den Metadaten weg oder setze ihn auf `"0"`:

<CodeGroup>
  ```js JavaScript & TypeScript icon="js" theme={"system"}
  import { Sandbox } from 'novita-sandbox/code-interpreter'

  // No idle timeout — sandbox runs until its maximum lifetime.
  const sandbox = await Sandbox.create({
    metadata: {
      idle_timeout: '0',
    },
  })

  // Alternatively, omit idle_timeout entirely:
  const sandbox2 = await Sandbox.create()
  ```

  ```python Python icon="python" theme={"system"}
  from novita_sandbox.code_interpreter import Sandbox

  # No idle timeout — sandbox runs until its maximum lifetime.
  sandbox = Sandbox.create(
      metadata={
          "idle_timeout": "0",
      },
  )

  # Alternatively, omit idle_timeout entirely:
  sandbox2 = Sandbox.create()
  ```
</CodeGroup>

## Häufige Anwendungsfälle

### Kurzlebige Ausführungsaufgaben

Verwende einen kurzen Leerlauf-Timeout für Sandboxes, die einmalige Aufgaben ausführen und nach dem Trennen der Client-Verbindung nicht weiter bestehen müssen:

<CodeGroup>
  ```js JavaScript & TypeScript icon="js" theme={"system"}
  import { Sandbox } from 'novita-sandbox/code-interpreter'

  const sandbox = await Sandbox.create({
    metadata: { idle_timeout: '60' },
  })

  // Execute code and get results...
  const result = await sandbox.runCode('print("Hello!")')

  // Disconnect — sandbox will be killed after 60 seconds of inactivity.
  await sandbox.kill()
  ```

  ```python Python icon="python" theme={"system"}
  from novita_sandbox.code_interpreter import Sandbox

  sandbox = Sandbox.create(
      metadata={"idle_timeout": "60"},
  )

  # Execute code and get results...
  result = sandbox.run_code('print("Hello!")')

  # Disconnect — sandbox will be killed after 60 seconds of inactivity.
  sandbox.kill()
  ```
</CodeGroup>

### Lang laufende interaktive Sitzungen

Verwende einen längeren Leerlauf-Timeout für Sandboxes, die in interaktiven Sitzungen genutzt werden, bei denen Benutzer vorübergehend abwesend sein können:

<CodeGroup>
  ```js JavaScript & TypeScript icon="js" theme={"system"}
  import { Sandbox } from 'novita-sandbox/code-interpreter'

  const sandbox = await Sandbox.create({
    metadata: { idle_timeout: '600' }, // 10 minutes
    autoPause: true,
  })

  // The sandbox will pause after 10 minutes of inactivity,
  // and can be resumed when the user returns.
  ```

  ```python Python icon="python" theme={"system"}
  from novita_sandbox.code_interpreter import Sandbox

  sandbox = Sandbox.create(
      metadata={"idle_timeout": "600"},  # 10 minutes
      auto_pause=True,
  )

  # The sandbox will pause after 10 minutes of inactivity,
  # and can be resumed when the user returns.
  ```
</CodeGroup>