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

# Long-running sandboxes

> Enable long-running mode to keep a Novita sandbox alive beyond the default 1-hour timeout cap for persistent services and background agent jobs.

By default, a sandbox `timeout` is effective for **at most 1 hour** — any larger value is capped. Long-running mode lifts this cap: with it enabled, the `timeout` you pass when creating the sandbox can exceed 1 hour. This is useful for workloads that need to stay alive well beyond a typical session, such as persistent services, long-running agent tasks, or background jobs.

Long-running mode is configured via the `metadata` field when creating a sandbox. The key is `long_running` and the value is `"true"` (as a string).

> [!TIP]
>
> `long_running` works **together with** `timeout`: set the timeout you actually need when creating the sandbox — with `long_running` enabled, it can exceed the default 1-hour cap. Without `long_running`, `timeout` is effective for at most 1 hour. **If `timeout` is not set, it defaults to 5 mins.**

> [!WARNING]
>
> Long-running mode does not disable [idle timeout](/guides/sandbox-idle-timeout): if you set one, it still applies, and an inactive sandbox will be paused or killed accordingly.

## Basic usage

Pass the `long_running` key in the `metadata` object when creating a sandbox.

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

const novita = new Novita({
  apiKey: process.env.NOVITA_API_KEY || '',
})

// Create a long-running code-interpreter sandbox.
// With long_running enabled, timeoutMs can exceed the default 1-hour cap.
const sandbox = await novita.codeInterpreter.create({
  metadata: {
    long_running: 'true',
  },
  timeoutMs: 86_400_000, // 24 hours
})
```

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

novita = Novita(api_key=os.environ['NOVITA_API_KEY'])

# Create a long-running code-interpreter sandbox.
# With long_running enabled, timeout can exceed the default 1-hour cap.
sandbox = novita.code_interpreter.create(
    metadata={
        'long_running': 'true',
    },
    timeout=86_400,  # 24 hours
)
```

```bash CLI icon="terminal" theme={"system"}
# --long-running writes long_running=true to the metadata
novita sandbox create base --long-running --timeout 24h -d
```

## How it works

* On `create` (and `resume`), when `long_running` is set, the `timeout` you pass can exceed the default 1-hour maximum running time.

## Scope and inheritance

* Only `create` accepts the `long_running` parameter.
* `resume` (including auto-resume): a sandbox created with `long_running` keeps the behavior after being resumed from a snapshot.
* `clone` inherits the parameter, and the sandbox keeps it when it continues running after a `reset`.

## Examples

Create a long-running sandbox that stays alive for up to **7 days**:

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

const novita = new Novita({
  apiKey: process.env.NOVITA_API_KEY || '',
})

// 7 days = 7 * 24 * 60 * 60 * 1000 ms
const sandbox = await novita.codeInterpreter.create({
  metadata: {
    long_running: 'true',
  },
  timeoutMs: 604_800_000,
})
```

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

novita = Novita(api_key=os.environ['NOVITA_API_KEY'])

# 7 days = 7 * 24 * 60 * 60 seconds
sandbox = novita.code_interpreter.create(
    metadata={
        'long_running': 'true',
    },
    timeout=604_800,
)
```

```bash CLI icon="terminal" theme={"system"}
# Create a long-running sandbox that stays alive for up to 7 days
novita sandbox create base --long-running --timeout 168h -d
```


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