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

# Timeout Handle

Every sandbox has a **maximum lifetime**, controlled by the `timeout` setting. When the timeout expires, the sandbox is stopped. By default, a new sandbox stays alive for **5 minutes**.

> [!NOTE]
>
> **Timeout vs. Idle timeout — don't confuse them:**
>
> * **Timeout** is the maximum lifetime of the sandbox. It starts counting down from creation, regardless of activity, and always takes effect when it expires.
> * **Idle timeout** only fires when no client is connected for the configured duration.

## Create a sandbox with a timeout

```js JavaScript & TypeScript icon="js" theme={"system"}
import { Novita } from 'novita-sandbox'

const novita = new Novita()
const sandbox = await novita.sandbox.create({ timeoutMs: 60_000 })

await sandbox.kill()
```

```python Python icon="python" theme={"system"}
from novita_sandbox import Novita

novita = Novita()
sandbox = novita.sandbox.create(timeout=60)

sandbox.kill()
```

```bash CLI icon="terminal" theme={"system"}
# Create a sandbox with a 60-second timeout (detached mode), prints the sandbox ID
novita sandbox create base --timeout 60s -d
```

## Update the timeout

You can use `setTimeout` / `set_timeout` to reset how much longer the sandbox should stay alive.

```js JavaScript & TypeScript icon="js" theme={"system"}
import { Novita } from 'novita-sandbox'

const novita = new Novita()
const sandbox = await novita.sandbox.create({ timeoutMs: 60_000 })

await sandbox.setTimeout(300_000)
await sandbox.kill()
```

```python Python icon="python" theme={"system"}
from novita_sandbox import Novita

novita = Novita()
sandbox = novita.sandbox.create(timeout=60)

sandbox.set_timeout(300)
sandbox.kill()
```

```bash CLI icon="terminal" theme={"system"}
# Reset the sandbox timeout to 5 minutes
novita sandbox set-timeout <sandbox_id> 5m
```

## Lifecycle behavior

You can combine `timeout` with `lifecycle` to choose whether the sandbox is killed or paused when the timeout expires.

```js JavaScript & TypeScript icon="js" theme={"system"}
import { Novita } from 'novita-sandbox'

const novita = new Novita()
const sandbox = await novita.sandbox.create({
  timeoutMs: 300_000,
  lifecycle: {
    onTimeout: 'pause',
    autoResume: true,
  },
})
```

```python Python icon="python" theme={"system"}
from novita_sandbox import Novita

novita = Novita()
sandbox = novita.sandbox.create(
    timeout=300,
    lifecycle={
        'on_timeout': 'pause',
        'auto_resume': True,
    },
)
```

```bash CLI icon="terminal" theme={"system"}
# Pause the sandbox instead of killing it when the timeout expires, and allow auto-resume
novita sandbox create base --timeout 5m --on-timeout pause --auto-resume -d
```

If you do not pass `lifecycle`, the sandbox is killed when the timeout expires.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.