> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fermion.app/llms.txt
> Use this file to discover all available pages before exploring further.
# quick_run() Method
> Execute code instantly in multiple programming languages using the quick_run method in Python.
The **`quick_run()`** method provides a fast and secure way to execute code directly within your Python application. It supports **ten popular runtimes**, including **Python, Java, C++, Node.js**, and more.
Before calling `quick_run()`, you must first connect to the sandbox using either `await create()` or `await from_snippet()`. The sandbox must be active before you can execute any code.
## Supported Languages
The following programming languages are supported by the `quick_run()` method.
***
## Method Signature
### `async quick_run(runtime: Literal['C', 'C++', 'Java', 'Python', 'Node.js', 'SQLite', 'MySQL', 'Go', 'Rust', '.NET'], source_code: str, stdin: Optional[str] = None, expected_output: Optional[str] = None, additional_files_as_zip: Optional[str] = None) -> DecodedRunResult`
**Description:**\
Executes code using the DSA execution API and returns the results. This method provides a simple way to execute code in various languages without needing to set up a full sandbox container.
***
## Method Parameters
The `quick_run()` method takes a set of parameters that define how your code will execute. Some are required, while others allow input, validation, or additional file support.
***
### Required Parameters
| Parameter | Type | Description |
| ------------- | ---- | ------------------------------------------------------------------------------------------------------------- |
| `runtime` | str | The programming language to execute (must match one of the supported runtimes above). |
| `source_code` | str | The source code to execute inside the sandbox. Use triple quotes (`"""`) or backticks for multi-line strings. |
***
### Optional Parameters
| Parameter | Type | Description |
| ------------------------- | ---- | ------------------------------------------------------------------------------------------ |
| `stdin` | str | Input data passed to the program’s standard input. |
| `expected_output` | str | Expected output for validation purposes. |
| `additional_files_as_zip` | str | Base64URL-encoded ZIP file containing extra files (e.g., database schema or dependencies). |
***
## Execution Results
The `quick_run()` method returns a **`DecodedRunResult`** object containing detailed execution results: status, output, timing, and resource usage.
| Field | Description |
| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `run_status` | Final execution result (RunStatus enum). Use `.value` to get the string value. Possible values: `"successful"`, `"compilation-error"`, `"time-limit-exceeded"`, `"wrong-answer"`, `"non-zero-exit-code"`, `"died-sigsev"`, `"died-sigfpe"`, `"died-sigabrt"`, `"internal-isolate-error"`, `"unknown"`. |
| `program_run_data` | Object holding detailed execution data like stdout, stderr, CPU time, and memory usage. Returns `None` if execution hasn't finished. |
| `program_run_data.stdout` | Program's standard output (already decoded by the SDK, not Base64URL). |
| `program_run_data.stderr` | Program's error output (already decoded by the SDK, not Base64URL). |
| `program_run_data.cpu_time_used_in_milliseconds` | CPU time consumed during execution (milliseconds). |
| `program_run_data.wall_time_used_in_milliseconds` | Real (wall-clock) time elapsed (milliseconds). |
| `program_run_data.memory_used_in_kilobyte` | Memory used during execution (kilobytes). |
| `program_run_data.exit_code` | Program's exit code (0 indicates success). |
| `program_run_data.exit_signal` | Termination signal if the process was killed, or 0 otherwise. |
| `compiler_output_after_compilation` | Compiler output (for compiled languages). Already decoded by SDK; returns `None` for interpreted languages. |
| `finished_at` | ISO 8601 UTC timestamp when execution finished (e.g., `"2025-11-06T08:14:10.127Z"`). |
***
### Validation (if you provided `expected_output`)
If you supplied an `expected_output` when running your code, QuickRun automatically compares the actual output with your expected value. The comparison result is reflected in the `run_status` field:
* If the output matches: `run_status.value` will be `"successful"`
* If the output doesn't match: `run_status.value` will be `"wrong-answer"`
* If there's a compilation error: `run_status.value` will be `"compilation-error"`
* If there's a runtime error: `run_status.value` 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 quick\_run()
Below are examples showing how to use `quick_run()` in Python.
```python hello_world.py theme={null}
import asyncio
from fermion_sandbox import Sandbox
async def main():
sandbox = Sandbox(api_key="fermion-api-key")
# Connect to sandbox first
await sandbox.create(should_backup_filesystem=False)
result = await sandbox.quick_run(
runtime="Python",
source_code='print("Hello, World!")'
)
# Output is already decoded
if result.program_run_data:
output = result.program_run_data.stdout
print(output) # "Hello, World!\n"
print(result.run_status.value) # "successful"
asyncio.run(main())
```
```python with_input.py theme={null}
import asyncio
from fermion_sandbox import Sandbox
async def main():
# Initialize the sandbox with your API key
sandbox = Sandbox(api_key="fermion-api-key")
# Connect to the sandbox first (required)
await sandbox.create(should_backup_filesystem=False)
# Run the Python code with input
result = await sandbox.quick_run(
runtime="Python",
source_code='name = input()\nprint(f"Hello, {name}!")',
stdin="Alice"
)
# Output is already decoded by the SDK
if result.program_run_data:
print(result.program_run_data.stdout) # "Hello, Alice!\n"
asyncio.run(main())
```
## Error Handling
Even well-written code can fail. The `quick_run()` method provides clear and structured feedback to help you identify and debug issues efficiently.\
Common failure types include **compilation errors**, **runtime exceptions**, and **timeouts**.\
Each is explained below with example usage.
Compilation errors occur when the source code cannot be compiled, typically due to syntax issues or missing elements. The `run_status.value` will be `"compilation-error"`, and the compiler output can be accessed through `compiler_output_after_compilation`.
```python theme={null}
import asyncio
from fermion_sandbox import Sandbox
async def main():
sandbox = Sandbox(api_key="fermion-api-key")
await sandbox.create(should_backup_filesystem=False) # Connect first (required)
result = await sandbox.quick_run(
runtime="Java",
source_code='public class Main { // Missing closing brace'
)
print(result.run_status.value) # "compilation-error"
if result.compiler_output_after_compilation:
# Output is already decoded by the SDK
compiler_output = result.compiler_output_after_compilation
print(compiler_output) # Shows compiler error messages
asyncio.run(main())
```
Runtime errors happen when the code compiles successfully but fails during execution, for example, dividing by zero or accessing invalid memory. In such cases, `run_status.value` will be `"non-zero-exit-code"`, and the error details are available in `program_run_data.stderr`.
```python theme={null}
import asyncio
from fermion_sandbox import Sandbox
async def main():
sandbox = Sandbox(api_key="fermion-api-key")
await sandbox.create(should_backup_filesystem=False) # Connect first (required)
result = await sandbox.quick_run(
runtime="Python",
source_code='print(1 / 0)' # Division by zero
)
print(result.run_status.value) # "non-zero-exit-code" or another error status
if result.program_run_data and result.program_run_data.stderr:
stderr_output = result.program_run_data.stderr
print(stderr_output) # Shows error details
asyncio.run(main())
```
Timeout errors occur when a program runs beyond the allowed execution time. In such cases, the `run_status.value` will be `"time-limit-exceeded"`.
```python theme={null}
import asyncio
from fermion_sandbox import Sandbox
async def main():
sandbox = Sandbox(api_key="fermion-api-key")
await sandbox.create(should_backup_filesystem=False) # Connect first (required)
result = await sandbox.quick_run(
runtime="Python",
source_code='while True: pass' # Infinite loop
)
print(result.run_status.value) # "time-limit-exceeded"
asyncio.run(main())
```
## Best Practices
* **Connect to the sandbox first:** Always call `await create()` or `await from_snippet()` before using `quick_run()`.
* **Always check `run_status` first:** Before reading output, confirm the code executed successfully (`run_status.value == "successful"`).
* **Ensure `program_run_data` is not `None`:** Verify that the result object includes `program_run_data` before accessing its properties.
* **Output is automatically decoded:** The SDK automatically decodes `stdout`, `stderr`, and `compiler_output_after_compilation`. You can use them directly without additional decoding.
* **Use `expected_output` for automated validation:** If the output matches your expected value, `run_status.value` will be `"successful"`, otherwise it will be `"wrong-answer"`.
* **Handle errors gracefully:** Check `run_status.value` and read `stderr` to display meaningful error messages.
* **Validate user input:** Always validate and sanitize user-submitted code before execution to ensure safety and reliability.
***
## Performance Tips
* Typical code execution time: **1–3 seconds**
* **Compiled languages** (C++, Java, Rust) may take slightly longer due to compilation overhead.
* **Interpreted languages** (Python, Node.js) generally start faster.
* **Database runtimes** (SQLite, MySQL) depend on query complexity and data size.
***
## Frequently Asked Questions
Code execution typically completes within **1–3 seconds**, depending on the 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 additional files by encoding them as a **Base64 ZIP** and passing
them through the **`additional_files_as_zip`** parameter.\
This allows your program to access dependencies, data files, or assets during execution.
Yes. Your program can read from files provided through **`additional_files_as_zip`**,\
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
**`time-limit-exceeded`** 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.