Idle timeout - Documentation

You can configure an idle timeout for your sandboxes to automatically stop or pause when no active connections are detected. 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

import { Novita } from 'novita-sandbox'

const novita = new Novita()

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

// The sandbox is running...

from novita_sandbox import Novita

novita = Novita()

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

# The sandbox is running...

Pausing instead of killing

If you want the sandbox to be paused instead so you can resume it later, enable the auto-pause option.

import { Novita } from 'novita-sandbox'

const novita = new Novita()

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

// After 60 seconds of inactivity, the sandbox will be paused.

from novita_sandbox import Novita

novita = Novita()

sandbox = novita.sandbox.create(
    metadata={
        'idle_timeout': '60',
    },
    auto_pause=True,
)

# After 60 seconds of inactivity, the sandbox will be paused.

Combining with other metadata

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

import { Novita } from 'novita-sandbox'

const novita = new Novita()

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

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

from novita_sandbox import Novita

novita = Novita()

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

print('Sandbox ID:', sandbox.sandbox_id)

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 { Novita } from 'novita-sandbox'

const novita = new Novita()

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

// Alternatively, omit idle_timeout entirely.
const sandbox2 = await novita.sandbox.create()

from novita_sandbox import Novita

novita = Novita()

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

# Alternatively, omit idle_timeout entirely.
sandbox2 = novita.sandbox.create()

Last modified on August 5, 2026

⌘I