Skip to main content
The quickRun() method provides a fast and secure way to execute code directly within your application. It has built-in support for ten popular runtimes: Python, Java, C++, Node.js, etc.

​
Supported Languages

The following languages can be executed with the help of the quickRun() method.

C / C++

Java

Python

Node.js

SQLite / MySQL

Go

Rust

.NET (C#)

​
Method Parameters

The quickRun() method accepts a set of parameters that define how your code will be executed. Some are required to run code successfully, while others let you customize execution behavior, provide input, or validate results.

​
Required Parameters

These parameters are mandatory for every QuickRun execution. Without them, the method won’t know what language to use or what code to run.
ParameterTypeDescription
runtimestringSpecifies the programming language to execute (see the supported languages above).
sourceCodestringThe actual source code to be executed within the sandbox environment. If the source code is multi-line, please use backticks (`) to format the code.

​
Optional Parameters

Use these optional parameters to provide inputs, verify expected outputs, or include additional files required by your program.
ParameterTypeDescription
stdinstringInput data passed to the program’s standard input (like console input).
expectedOutputstringThe expected output for validation
additionalFilesAsZipstringBase64URL-encoded ZIP archive containing any extra files your program depends on. (SQL schema)

​
Execution Results

The quickRun() method returns a runResult object that holds detailed information about the execution outcome: whether it succeeded, failed, or encountered runtime or compilation issues.
FieldDescription
runStatusIndicates the final execution result. Possible values include "successful", "compilation-error", "time-limit-exceeded", "wrong-answer", "non-zero-exit-code", "died-sigsev", "died-sigxfsz", "died-sigfpe", "died-sigabrt", "internal-isolate-error", or "unknown". Returns null if execution hasn’t completed yet.
programRunDataAn object containing detailed execution metrics and output. Returns null if execution hasn’t completed yet.
programRunData.stdoutBase64UrlEncodedBase64URL-encoded string containing everything the program printed to the standard output stream. Decode using decodeBase64Url() to get the actual output.
programRunData.stderrBase64UrlEncodedBase64URL-encoded string containing any error messages or debug logs printed to the standard error stream. Decode using decodeBase64Url() to get the actual error output.
programRunData.cpuTimeUsedInMillisecondsReports how long the code took to execute (CPU time), measured in milliseconds. Helpful for performance benchmarking or optimization.
programRunData.wallTimeUsedInMillisecondsReports the wall-clock time (real time) taken for execution, measured in milliseconds.
programRunData.memoryUsedInKilobyteIndicates the total memory used during execution, measured in kilobytes.
programRunData.exitCodeThe exit code returned by the program (0 typically indicates success).
programRunData.exitSignalThe exit signal if the process was terminated by a signal, or null otherwise.
compilerOutputAfterCompilationBase64UrlEncodedBase64URL-encoded compiler output (for compiled languages). Returns null for interpreted languages or if there’s no compiler output.
finishedAtTimestamp marking when the execution completed, in ISO 8601 UTC format (e.g., "2025-11-06T08:14:10.127Z"). Returns null if execution hasn’t completed yet.

​
Validation (if you provided expectedOutput)

If you supplied an expectedOutput when running your code, QuickRun automatically compares the actual output with your expected value. The comparison result is reflected in the runStatus field:
  • If the output matches: runStatus will be "successful"
  • If the output doesn’t match: runStatus will be "wrong-answer"
  • If there’s a compilation error: runStatus will be "compilation-error"
  • If there’s a runtime error: runStatus will be "non-zero-exit-code" or another error status
This allows for quick correctness checks, ideal for grading systems, test runners, or automated assessments.

​
How to Use QuickRun

Here is a simple example on how you can use the quickRun() to execute a simple python script. 
import { Sandbox, decodeBase64Url } from '@fermion/sandbox'

const sandbox = new Sandbox({ apiKey: 'fermion-api-key' })

const result = await sandbox.quickRun({
	runtime: 'Python',
	sourceCode: 'print("Hello, World!")'
})

// Decode the Base64URL-encoded output
const output = decodeBase64Url(result.programRunData.stdoutBase64UrlEncoded)
console.log(output) // Outputs: "Hello, World!"
console.log(result.runStatus) // "successful"
Here is a another simple example on how you can use the quickRun() to execute a simple C++ program that takes a name input and greets the user. 
import { Sandbox, decodeBase64Url } from '@fermion/sandbox'

const sandbox = new Sandbox({ apiKey: 'fermion-api-key' })

const result = await sandbox.quickRun({
	runtime: 'C++',
	sourceCode: `
    #include <iostream>
    using namespace std;
    int main() {
      string name;
      cin >> name;
      cout << "Hello, " << name << "!" << endl;
      return 0;
    }
  `,
	stdin: 'Alice'
})

// Decode the Base64URL-encoded output
const output = decodeBase64Url(result.programRunData.stdoutBase64UrlEncoded)
console.log(output) // Outputs: "Hello, Alice!"
console.log(result.runStatus) // "successful"
Now, let us try to run a Java code with output checks: 
import { Sandbox, decodeBase64Url } from '@fermion/sandbox'

const sandbox = new Sandbox({ apiKey: 'fermion-api-key' })

const result = await sandbox.quickRun({
	runtime: 'Java',
	sourceCode: `
    public class Main {
      public static void main(String[] args) {
        int sum = 5 + 3;
        System.out.println(sum);
      }
    }
  `,
	expectedOutput: '8'
})

console.log(result.runStatus) // "successful" if output matched, "wrong-answer" if it didn't
const output = decodeBase64Url(result.programRunData.stdoutBase64UrlEncoded)
console.log(output) // "8"

​
Example: Complete Workflow

Here’s a complete example demonstrating how to integrate QuickRun into your application. This workflow shows how to initialize the Sandbox client, execute user-submitted code, validate the output, and handle potential runtime or validation errors. 
import { Sandbox, decodeBase64Url } from '@fermion/sandbox'

async function runUserCode(code: string, input: string, expected: string) {
	const sandbox = new Sandbox({ apiKey: process.env.FERMION_API_KEY! })

	try {
		const result = await sandbox.quickRun({
			runtime: 'Python',
			sourceCode: code,
			stdin: input,
			expectedOutput: expected
		})

		// Check if execution completed
		if (!result.programRunData) {
			return {
				success: false,
				error: 'Execution did not complete',
				type: result.runStatus
			}
		}

		// Decode output and error messages
		const stdout = decodeBase64Url(result.programRunData.stdoutBase64UrlEncoded)
		const stderr = result.programRunData.stderrBase64UrlEncoded
			? decodeBase64Url(result.programRunData.stderrBase64UrlEncoded)
			: ''

		// Check if it ran successfully
		if (result.runStatus !== 'successful') {
			return {
				success: false,
				error: stderr || `Execution failed with status: ${result.runStatus}`,
				type: result.runStatus,
				output: stdout
			}
		}

		// Check if output matched (runStatus will be 'successful' if matched, 'wrong-answer' if not)
		if (result.runStatus === 'successful') {
			return {
				success: true,
				output: stdout,
				executionTime: result.programRunData.cpuTimeUsedInMilliseconds,
				memoryUsed: result.programRunData.memoryUsedInKilobyte
			}
		} else {
			return {
				success: false,
				output: stdout,
				expected: expected,
				runStatus: result.runStatus
			}
		}
	} catch (error) {
		return {
			success: false,
			error: error instanceof Error ? error.message : String(error)
		}
	}
}

// Usage
const testResult = await runUserCode('print(input())', 'Hello', 'Hello')

console.log(testResult)

​
Error Handling

Even well-written code can fail, the quickRun() provides clear feedback to help you identify and debug errors efficiently. Common failure types include compilation errors, runtime exceptions, and timeouts. Each is detailed below with example usage.
These occur when the code fails to compile due to syntax issues or missing elements. The runStatus will be set to “compilation-error”, and the compiler output can be found in compilerOutputAfterCompilationBase64UrlEncoded.
import { Sandbox, decodeBase64Url } from '@fermion/sandbox'

const sandbox = new Sandbox({ apiKey: 'fermion-api-key' })
const result = await sandbox.quickRun({
  runtime: 'Java',
  sourceCode: 'public class Main { // Missing closing brace'
})

console.log(result.runStatus) // "compilation-error"
if (result.compilerOutputAfterCompilationBase64UrlEncoded) {
  const compilerOutput = decodeBase64Url(result.compilerOutputAfterCompilationBase64UrlEncoded)
  console.log(compilerOutput) // Shows compiler error messages
}
Runtime errors happen when the program compiles successfully but fails during execution, such as dividing by zero or accessing invalid memory. In such cases, the runStatus will be “non-zero-exit-code” or another error status, and the error message appears in programRunData.stderrBase64UrlEncoded.
import { Sandbox, decodeBase64Url } from '@fermion/sandbox'

const sandbox = new Sandbox({ apiKey: 'fermion-api-key' })
const result = await sandbox.quickRun({
  runtime: 'Python',
  sourceCode: 'print(1 / 0)' // Division by zero
})

console.log(result.runStatus) // "non-zero-exit-code" or other error status
if (result.programRunData?.stderrBase64UrlEncoded) {
  const stderr = decodeBase64Url(result.programRunData.stderrBase64UrlEncoded)
  console.log(stderr) // Shows error details
}
Timeout errors occur when a program runs beyond the allowed time limit, typically due to infinite loops or heavy computation. The runStatus will be “time-limit-exceeded”.
import { Sandbox } from '@fermion/sandbox'

const sandbox = new Sandbox({ apiKey: 'fermion-api-key' })
const result = await sandbox.quickRun({
  runtime: 'Python',
  sourceCode: 'while True: pass' // Infinite loop
})

console.log(result.runStatus) // "time-limit-exceeded"

​
Best Practices

  • Always check runStatus first : Before looking at output, verify the code ran successfully (runStatus === 'successful')
  • Check programRunData is not null : Ensure programRunData exists before accessing its properties
  • Decode Base64URL-encoded output : Use decodeBase64Url() to decode stdoutBase64UrlEncoded and stderrBase64UrlEncoded
  • Use expectedOutput for automated testing : The system will set runStatus to "successful" if output matches, or "wrong-answer" if it doesn’t
  • Handle errors gracefully : Show helpful messages when code fails by checking runStatus and decoding stderrBase64UrlEncoded
  • Validate user input : If users can submit code, validate it before execution

​
Performance Tips

  • Code execution typically takes 1-3 seconds
  • Compilation languages (C++, Java, Rust) may take slightly longer
  • Interpreted languages (Python, Node.js) start faster
  • Database operations (SQLite, MySQL) depend on query complexity

​
Frequently Asked Questions

Code execution typically completes within 1–3 seconds, depending on the programming language, code complexity, and whether compilation is required. Interpreted languages like Python or Node.js tend to execute faster, while compiled languages such as Java or Rust may take slightly longer.
You can include any required files by encoding them as a Base64 ZIP and passing them through the additionalFilesAsZip parameter. This allows your program to access external dependencies, data files, or assets during execution.
Yes. Your program can read from files provided through additionalFilesAsZip, or you can simulate user input using the stdin parameter for simpler text-based input.
Each code execution has a time limit to prevent infinite loops or unresponsive code. If your program exceeds this limit, it’s automatically stopped and marked as TimeLimitExceeded in the result object.
Absolutely. All code runs inside a secure, isolated sandbox with strict resource and permission controls. This ensures your application and data remain safe from malicious or runaway code.