Node.js vm Module Guide

The vm module provides APIs for compiling and running code within V8 virtual machine contexts. Here's how to use it.

Basic Script Execution#

import vm from 'node:vm';

// Run code in current context
const code = 'x + y';
const result = vm.runInThisContext(code);
// Error: x is not defined (no access to local variables)

// Run with context
const context = { x: 10, y: 20 };
vm.createContext(context);
const result = vm.runInContext('x + y', context);
console.log(result);  // 30

// Run in new context
const result = vm.runInNewContext('x + y', { x: 10, y: 20 });
console.log(result);  // 30

Creating Contexts#

import vm from 'node:vm';

// Create a reusable context
const sandbox = {
  console: console,
  Math: Math,
  result: null,
};

vm.createContext(sandbox);

// Run multiple scripts in same context
vm.runInContext('result = Math.sqrt(16)', sandbox);
console.log(sandbox.result);  // 4

vm.runInContext('result = result * 2', sandbox);
console.log(sandbox.result);  // 8

// Check if object is a context
console.log(vm.isContext(sandbox));  // true
console.log(vm.isContext({}));       // false

Script Compilation#

import vm from 'node:vm';

// Compile script for reuse
const script = new vm.Script('x + y');

// Run in different contexts
const context1 = vm.createContext({ x: 1, y: 2 });
const context2 = vm.createContext({ x: 10, y: 20 });

console.log(script.runInContext(context1));  // 3
console.log(script.runInContext(context2));  // 30

// Script with options
const timedScript = new vm.Script('while(true) {}', {
  filename: 'infinite-loop.js',
  lineOffset: 0,
  columnOffset: 0,
});

// Run with timeout
try {
  timedScript.runInNewContext({}, { timeout: 100 });
} catch (err) {
  console.log('Script timed out');
}

Execution Options#

import vm from 'node:vm';

const code = `
  function calculate() {
    return a * b;
  }
  calculate();
`;

const options = {
  // Timeout in milliseconds
  timeout: 1000,

  // Display filename in stack traces
  filename: 'user-code.js',

  // Adjust line numbers in stack traces
  lineOffset: 10,
  columnOffset: 5,

  // Break on first statement (debugging)
  breakOnSigint: true,
};

const context = vm.createContext({ a: 5, b: 10 });
const result = vm.runInContext(code, context, options);
console.log(result);  // 50

Sandboxed Environment#

import vm from 'node:vm';

// Create minimal sandbox
function createSandbox() {
  const sandbox = {
    // Safe built-ins
    console: {
      log: (...args) => console.log('[Sandbox]', ...args),
    },
    Math: Math,
    Date: Date,
    JSON: JSON,
    parseInt: parseInt,
    parseFloat: parseFloat,

    // Custom APIs
    result: undefined,
  };

  return vm.createContext(sandbox);
}

const sandbox = createSandbox();

// Code can't access Node.js APIs
vm.runInContext(`
  console.log('Hello from sandbox');
  result = Math.PI * 2;
`, sandbox);

console.log(sandbox.result);  // 6.283...

// Dangerous code is blocked
try {
  vm.runInContext(`
    require('fs').readFileSync('/etc/passwd');
  `, sandbox);
} catch (err) {
  console.log('Blocked:', err.message);
  // require is not defined
}

Module Support#

import vm from 'node:vm';

// Create module
const context = vm.createContext({
  console: console,
});

// Synthetic module
const syntheticModule = new vm.SyntheticModule(
  ['default', 'named'],
  function() {
    this.setExport('default', 'default export');
    this.setExport('named', 'named export');
  },
  { context }
);

// Link and evaluate
await syntheticModule.link(() => {});
await syntheticModule.evaluate();

console.log(syntheticModule.namespace);
// { default: 'default export', named: 'named export' }

Safe Evaluation#

import vm from 'node:vm';

// Safe eval function
function safeEval(code, context = {}, options = {}) {
  const sandbox = {
    ...context,
    // Prevent access to dangerous globals
    process: undefined,
    require: undefined,
    module: undefined,
    exports: undefined,
    __dirname: undefined,
    __filename: undefined,
  };

  vm.createContext(sandbox);

  const defaultOptions = {
    timeout: 1000,
    filename: 'eval',
  };

  return vm.runInContext(code, sandbox, {
    ...defaultOptions,
    ...options,
  });
}

// Usage
const result = safeEval('2 + 2');
console.log(result);  // 4

const result2 = safeEval('items.filter(x => x > 5)', {
  items: [1, 3, 5, 7, 9],
});
console.log(result2);  // [7, 9]

Expression Evaluation#

import vm from 'node:vm';

// Evaluate user expressions
class ExpressionEvaluator {
  constructor() {
    this.context = vm.createContext({
      Math: Math,
      Date: Date,
    });
    this.variables = {};
  }

  setVariable(name, value) {
    this.variables[name] = value;
    this.context[name] = value;
  }

  evaluate(expression) {
    try {
      return vm.runInContext(expression, this.context, {
        timeout: 100,
      });
    } catch (err) {
      throw new Error(`Evaluation error: ${err.message}`);
    }
  }
}

const evaluator = new ExpressionEvaluator();
evaluator.setVariable('price', 100);
evaluator.setVariable('quantity', 5);

console.log(evaluator.evaluate('price * quantity'));  // 500
console.log(evaluator.evaluate('Math.round(price * 1.1)'));  // 110

Template Engine#

import vm from 'node:vm';

// Simple template engine using vm
function renderTemplate(template, data) {
  const sandbox = {
    ...data,
    __output: '',
    __append: function(str) {
      this.__output += str;
    },
  };

  vm.createContext(sandbox);

  // Convert template to JavaScript
  let code = '__append(`';
  code += template
    .replace(/`/g, '\\`')
    .replace(/\${/g, '`); __append(')
    .replace(/}/g, '); __append(`');
  code += '`);';

  vm.runInContext(code, sandbox, { timeout: 1000 });

  return sandbox.__output;
}

// Usage
const template = 'Hello, ${name}! You have ${count} messages.';
const result = renderTemplate(template, { name: 'John', count: 5 });
console.log(result);  // 'Hello, John! You have 5 messages.'

Code Analysis#

import vm from 'node:vm';

// Analyze code without executing
function analyzeCode(code) {
  try {
    new vm.Script(code, { filename: 'analysis.js' });
    return { valid: true, error: null };
  } catch (err) {
    return {
      valid: false,
      error: {
        message: err.message,
        line: err.lineNumber,
        column: err.columnNumber,
      },
    };
  }
}

console.log(analyzeCode('const x = 1;'));
// { valid: true, error: null }

console.log(analyzeCode('const x = ;'));
// { valid: false, error: { message: 'Unexpected token ;', ... } }

Worker-like Isolation#

import vm from 'node:vm';

// Create isolated execution environment
class IsolatedRunner {
  constructor() {
    this.context = vm.createContext({
      console: {
        log: (...args) => this.output.push(['log', args]),
        error: (...args) => this.output.push(['error', args]),
      },
      setTimeout: (fn, ms) => {
        if (ms > 5000) throw new Error('Timeout too long');
        return setTimeout(fn, ms);
      },
    });
    this.output = [];
  }

  async run(code, timeout = 5000) {
    this.output = [];

    const script = new vm.Script(`
      (async () => {
        ${code}
      })();
    `);

    try {
      await script.runInContext(this.context, {
        timeout,
        breakOnSigint: true,
      });
    } catch (err) {
      this.output.push(['error', [err.message]]);
    }

    return this.output;
  }
}

// Usage
const runner = new IsolatedRunner();
const output = await runner.run(`
  console.log('Starting...');
  const result = 1 + 2;
  console.log('Result:', result);
`);

console.log(output);
// [['log', ['Starting...']], ['log', ['Result:', 3]]]

Security Considerations#

import vm from 'node:vm';

// IMPORTANT: vm is NOT a security sandbox!
// Malicious code can escape the context

// Example of context escape (DO NOT rely on vm for security)
const malicious = `
  const ForeignFunction = this.constructor.constructor;
  const process = ForeignFunction('return process')();
  process.exit(1);
`;

// For true isolation, use:
// 1. Worker threads with limited permissions
// 2. Child processes
// 3. Containers/VMs
// 4. Third-party sandboxing libraries (vm2, isolated-vm)

// Safe pattern: validate and whitelist operations
function safeExecute(code) {
  // Only allow specific patterns
  const allowedPattern = /^[\d\s+\-*/().]+$/;
  if (!allowedPattern.test(code)) {
    throw new Error('Invalid expression');
  }

  return vm.runInNewContext(code, {});
}

console.log(safeExecute('2 + 2'));  // 4
// safeExecute('require("fs")');  // Error: Invalid expression

Best Practices#

Use Cases:
✓ Simple expression evaluation
✓ Template rendering
✓ Configuration evaluation
✓ Code analysis/validation

Context Setup:
✓ Minimal sandbox
✓ Whitelist allowed APIs
✓ Set timeouts
✓ Validate input

Security:
✓ vm is NOT a security sandbox
✓ Validate/sanitize input
✓ Use for trusted code only
✓ Consider alternatives for untrusted code

Avoid:
✗ Running untrusted code
✗ No timeout limits
✗ Exposing Node.js APIs
✗ Assuming isolation

The Node.js vm module enables code execution in isolated V8 contexts, useful for template engines, expression evaluation, and code analysis. However, it is NOT a security sandbox - malicious code can escape. Use it for semi-trusted code with input validation and timeouts. For truly untrusted code, consider worker threads, child processes, or purpose-built sandboxing solutions like isolated-vm.