Skip to main content
You can configure an idle timeout for your sandboxes to automatically stop or pause them 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.

​
How idle timeout works

The idle timeout feature monitors active connections to your sandbox:
  1. When no connections are active — the sandbox’s end time is set to current_time + idle_timeout_seconds.
  2. When a connection becomes active again — the sandbox’s end time is restored to the original maximum sandbox lifetime.
  3. 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().
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)

​
Timeout constraints

ConstraintValueDescription
Minimum30 secondsValues below 30 seconds are treated as “idle disabled” to prevent rapid start/stop cycles.
DefaultDisabled (0)If idle_timeout is not specified, the feature is disabled and the sandbox runs until its maximum lifetime.
MaximumSandbox lifetimeThe 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()

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

​
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.
Last modified on June 10, 2026