Sessions

Sessions represent a persistent connection to a sandbox. All code executions within a session share the same VM, filesystem, and process state.

How sessions work

When you create an InstaVM client and call execute(), a session is automatically created. Subsequent calls to execute() on the same client reuse the same session, which means:

• Variables, files, and installed packages persist between calls
• Each call runs in the same VM
• The session ends when you call kill(), exit a context manager, or the lifetime expires

CLI

# SSH provides a persistent session — state persists across commands
instavm create
instavm connect <vm_id>
# Inside the VM:
# python3 -c "x = 42; print(x)"

Python

from instavm import InstaVM

with InstaVM('your_api_key') as vm:
    vm.execute("x = 42")
    result = vm.execute("print(x)")  # Output: 42
    # Same VM, same state

JavaScript

import { InstaVM } from 'instavm';

const client = new InstaVM('your_api_key');
await client.execute("x = 42");
const result = await client.execute("print(x)");  // Output: 42
// Same VM, same state
await client.dispose();

Session lifecycle

create session → VM boots (~200ms) → execute code → ... → terminate

1. Created -- Session allocated, VM provisioning begins.
2. Active -- VM is running. You can execute code, upload/download files, and manage egress.
3. Terminated -- Session closed. VM and all its state are destroyed.

Automatic session management

Use a context manager to guarantee cleanup:

CLI

# Create with a timeout — VM auto-terminates when it expires
instavm create --timeout 3600
# ... use the VM ...
instavm rm <vm_id>

Python

with InstaVM('your_api_key') as vm:
    vm.execute("print('hello')")
# VM is killed automatically here

JavaScript

import { InstaVM } from 'instavm';

const client = new InstaVM('your_api_key');
try {
  await client.execute("print('hello')");
} finally {
  await client.dispose();
}
// VM is killed automatically

Manual session management

If you need more control:

CLI

# List active VMs and their session status
instavm ls --json

Python

vm = InstaVM('your_api_key')
try:
    result = vm.execute("print('hello')")

    # Check session status
    if vm.is_session_active():
        info = vm.get_session_info()
        print(f"Session ID: {info['session_id']}")
finally:
    vm.close_session()

JavaScript

import { InstaVM } from 'instavm';

const client = new InstaVM('your_api_key');
try {
  const result = await client.execute("print('hello')");
  const usage = await client.getUsage();
  console.log(usage);
} finally {
  await client.dispose();
}

Session expiry

Sessions have a configurable lifetime. When the lifetime expires, the VM is terminated and all state is lost. Set the lifetime when creating a VM directly:

CLI

instavm create --timeout 3600

Python

client = InstaVM('your_api_key')
vm = client.vms.create(
    vm_lifetime_seconds=3600,  # 1 hour
    wait=True
)

JavaScript

import { InstaVM } from 'instavm';

const client = new InstaVM('your_api_key');
const vm = await client.vms.create({
  vm_lifetime_seconds: 3600,  // 1 hour
}, true);

Multi-execute pattern

Sessions are designed for multi-step workflows. Install dependencies once, then run multiple scripts:

CLI

# Connect via SSH for interactive multi-step workflows
instavm create
instavm connect <vm_id>
# Inside the VM:
# pip install pandas
# python3 -c "import pandas as pd; df = pd.DataFrame({'a': [1,2,3]}); print(df.describe())"

Python

with InstaVM('your_api_key') as vm:
    # Step 1: Install dependencies
    vm.execute("import subprocess; subprocess.check_call(['pip', 'install', 'pandas'])")

    # Step 2: Load data
    vm.execute("import pandas as pd; df = pd.DataFrame({'a': [1,2,3]})")

    # Step 3: Process
    result = vm.execute("print(df.describe())")
    print(result['output'])

JavaScript

import { InstaVM } from 'instavm';

const client = new InstaVM('your_api_key');

// Step 1: Install dependencies
await client.execute("import subprocess; subprocess.check_call(['pip', 'install', 'pandas'])");

// Step 2: Load data
await client.execute("import pandas as pd; df = pd.DataFrame({'a': [1,2,3]})");

// Step 3: Process
const result = await client.execute("print(df.describe())");
console.log(result.output);

await client.dispose();

Session info

Query the current session:

Python

info = vm.get_session_info()
# Returns: {'session_id': '...', 'status': 'active', ...}

usage = vm.get_usage()
# Returns: {'cpu_time': ..., 'memory_used': ..., 'network_io': ...}

JavaScript

const usage = await client.getUsage();
// Returns: { cpu_time: ..., memory_used: ..., network_io: ... }

Next steps

• Sandboxes -- the isolation model behind sessions
• Egress Policies -- control what a session can access on the network
• Python SDK: Session Management -- full SDK reference