Idle timeout

You can configure an idle timeout for your sandboxes to automatically stop or pause when no active connections are detected. This helps reduce costs by ensuring unused sandboxes are not running indefinitely.

The idle timeout is configured via the metadata field when creating a sandbox. The key is idle_timeout and the value is the number of seconds (as a string).

Basic usage

Pass the idle_timeout key in the metadata object when creating a sandbox. The value is the idle timeout duration in seconds (as a string). When no client is connected to the sandbox for the specified duration, the sandbox will be automatically killed or paused.

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.

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.

How idle timeout works

The idle timeout feature monitors active connections to your sandbox:

When no connections are active — the sandbox’s end time is set to current_time + idle_timeout_seconds.
When a connection becomes active again — the sandbox’s end time is restored to the original maximum sandbox lifetime.
When the idle timeout elapses without any reconnection — the sandbox is killed (or paused if autoPause is enabled).

This means a sandbox won’t be stopped as long as there is at least one active client connected to it (e.g., via Sandbox.connect() or open WebSocket/HTTP connections).

Pausing instead of killing

By default, an idle sandbox is killed when the idle timeout expires. If you want the sandbox to be paused instead so you can resume it later, enable the autoPause option:

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().

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().

When autoPause is enabled, the sandbox state transitions to paused on idle timeout. You can connect to it later to resume execution.

Combining with other metadata

The idle_timeout metadata key can be combined with other metadata keys you may already use:

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)

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)

Timeout constraints

Constraint	Value	Description
Minimum	30 seconds	Values below 30 seconds are treated as “idle disabled” to prevent rapid start/stop cycles.
Default	Disabled (0)	If `idle_timeout` is not specified, the feature is disabled and the sandbox runs until its maximum lifetime.
Maximum	Sandbox lifetime	The idle timeout cannot exceed the sandbox’s configured `timeout` (maximum lifetime).

If you set idle_timeout to a value below the minimum threshold (30 seconds), the idle timeout feature will be silently disabled for that sandbox. The sandbox will run until its maximum lifetime expires.

Disabling idle timeout

To explicitly disable the idle timeout for a sandbox, simply omit the idle_timeout key from the metadata, or set it to "0":

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()

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()

Common use cases

Short-lived execution tasks

Use a short idle timeout for sandboxes that run one-off tasks and don’t need to persist after the client disconnects:

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()

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()

Long-running interactive sessions

Use a longer idle timeout for sandboxes used in interactive sessions where users may step away temporarily:

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.

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.

Get started

Model APIs

Agent Sandbox

GPUs

Observability

Resources

Basic usage

How idle timeout works

Pausing instead of killing

Combining with other metadata

Timeout constraints

Disabling idle timeout

Common use cases

Short-lived execution tasks

Long-running interactive sessions

​Basic usage

​How idle timeout works

​Pausing instead of killing

​Combining with other metadata

​Timeout constraints

​Disabling idle timeout

​Common use cases

​Short-lived execution tasks

​Long-running interactive sessions

Basic usage

How idle timeout works

Pausing instead of killing

Combining with other metadata

Timeout constraints

Disabling idle timeout

Common use cases

Short-lived execution tasks

Long-running interactive sessions