quickRun() Method

Learn how to instantly execute code in multiple programming languages using the QuickRun method.

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.

Before using quickRun(), you must first establish a connection to the sandbox by calling create() or fromSnippet(). The sandbox must be connected before executing code.

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.

Parameter	Type	Description
runtime	string	Specifies the programming language to execute (see the supported languages above).
sourceCode	string	The 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.

Parameter	Type	Description
stdin	string	Input data passed to the program’s standard input (like console input).
expectedOutput	string	The expected output for validation
additionalFilesAsZip	string	Base64URL-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.

Field	Description
runStatus	Indicates 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.
programRunData	An object containing detailed execution metrics and output. Returns null if execution hasn’t completed yet.
programRunData.stdout	String containing everything the program printed to the standard output stream. The SDK automatically decodes this value, so you can use it directly without additional decoding.
programRunData.stderr	String containing any error messages or debug logs printed to the standard error stream. The SDK automatically decodes this value, so you can use it directly without additional decoding.
programRunData.cpuTimeUsedInMilliseconds	Reports how long the code took to execute (CPU time), measured in milliseconds. Helpful for performance benchmarking or optimization.
programRunData.wallTimeUsedInMilliseconds	Reports the wall-clock time (real time) taken for execution, measured in milliseconds.
programRunData.memoryUsedInKilobyte	Indicates the total memory used during execution, measured in kilobytes.
programRunData.exitCode	The exit code returned by the program (0 typically indicates success).
programRunData.exitSignal	The exit signal if the process was terminated by a signal, or null otherwise.
compilerOutputAfterCompilation	Compiler output (for compiled languages). The SDK automatically decodes this value, so you can use it directly without additional decoding. Returns null for interpreted languages or if there’s no compiler output.
finishedAt	Timestamp 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 code:

helloWorld.ts

import { Sandbox } from '@fermion/sandbox'

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

// Connect to sandbox first (required)
await sandbox.create()

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

// Output is already decoded by the SDK
const output = result.programRunData?.stdout
console.log(output) // Outputs: "Hello, World!\n"
console.log(result.runStatus) // "successful"

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.

Compilation Errors

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 compilerOutputAfterCompilation.

import { Sandbox } from '@fermion/sandbox'

const sandbox = new Sandbox({ apiKey: 'fermion-api-key' })
await sandbox.create() // Connect first (required)

const result = await sandbox.quickRun({
  runtime: 'Java',
  sourceCode: 'public class Main { // Missing closing brace'
})

console.log(result.runStatus) // "compilation-error"
if (result.compilerOutputAfterCompilation) {
  // Output is already decoded by the SDK
  const compilerOutput = result.compilerOutputAfterCompilation
  console.log(compilerOutput) // Shows compiler error messages
}

Runtime Errors

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.stderr.

import { Sandbox } from '@fermion/sandbox'

const sandbox = new Sandbox({ apiKey: 'fermion-api-key' })
await sandbox.create() // Connect first (required)

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?.stderr) {
  // Output is already decoded by the SDK
  const stderr = result.programRunData.stderr
  console.log(stderr) // Shows error details
}

Timeout Errors

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' })
await sandbox.create() // Connect first (required)

const result = await sandbox.quickRun({
  runtime: 'Python',
  sourceCode: 'while True: pass' // Infinite loop
})

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

Best Practices

• Connect to sandbox first : Always call create() or fromSnippet() before using quickRun()
• 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
• Output is already decoded : The SDK automatically decodes stdout, stderr, and compilerOutputAfterCompilation, so you can use them directly without additional decoding
• 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 accessing stderr directly
• 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

How long does code execution take?

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.

What if my code needs external files?

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.

Can I run code that reads from files?

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.

What happens if my code runs forever?

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.

Is the execution environment safe?

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.