Installation (Windows)

Aestra is built for Windows with zero host pollution. You do NOT need Rust, MSVC, or any C++ compiler to run Aestra. Only standard Python 3.10+ is required.

Prerequisites

Windows Native Installer (.msi)

Install Aestra using the standard Windows graphical installer:

# Download Aestra-Setup.msi from GitHub Releases and double-click or run:
msiexec /i Aestra-Setup.msi /quiet

Or install via Windows Package Manager (winget):

winget install Aestra.Aestra

Or install globally via pip:

pip install aestra

What the MSI installer configures:

• Installs to %ProgramFiles%\Aestra with proper system permissions
• Permanently registers aestra in the system PATH
• Creates a Desktop shortcut with the native aestra.ico emblem
• Supports seamless in-place updates and rollback via native Windows MSI MajorUpgrade

Verify installation

Run diagnostic checks to verify runtime engines and toolchain compilers:

aestra doctor

Uninstall

To cleanly remove Aestra at any time, use Windows Settings or run msiexec:

# In Windows Settings -> Installed apps -> Aestra -> Uninstall, or:
msiexec /x Aestra-Setup.msi /quiet

Competitive Programmer's Quickstart

Aestra acts as your automated local judge for competitive programming and coding contests. Never manually copy-paste test inputs again.

1. Where do I keep my code?

Anywhere on your computer! You never need to save files inside the Aestra folder. Work directly in your usual contest directory:

C:\Users\YourName\Documents\Contest\
├── solution.cpp             # Your solution (or .py, .rs, .go)
└── cases\                   # Sample test cases folder
    ├── 01.in                # Input from problem statement
    ├── 01.out               # Expected output
    ├── 02.in
    └── 02.out

2. How to create test cases

For each sample test given in the problem statement, create matching pairs of files in cases/:

• 01.in: Paste the sample input from the problem statement.
• 01.out: Paste the expected answer from the problem statement.
• For test 2: create 02.in and 02.out, and so on.

3. Running the automated judge

Open your terminal in your contest directory and test your solution with a single command:

aestra test solution.cpp --cases cases

Supports .cpp, .py, .rs, .go, or .exe. C++, Rust, and Go are automatically compiled with instant 0ms SHA-256 build caching.

4. Drag-and-drop interactive mode

If you prefer not to type commands, launch the interactive dashboard:

1. Run aestra in any terminal.
2. Press 2 for Batch Test Suite.
3. Drag and drop your solution.cpp file from File Explorer into the terminal window, press Enter.
4. Drag and drop your cases/ folder into the terminal window, press Enter.

Safety and system integrity

Aestra is designed to execute untrusted code safely. It runs entirely in user space, never requests root or administrator privileges, never modifies system files, never writes outside its own directory, and leaves no persistent background processes or services.

How untrusted code is contained

When the native POSIX sandbox executes a binary, it applies multiple layers of kernel-enforced constraints before the target program starts running. These are not heuristic — they are enforced by the Linux kernel scheduler itself.

What Aestra does NOT do

• Never requests sudo, root, or administrator privileges
• Never writes outside the project directory
• Never installs system-wide services, daemons, or startup scripts
• Never modifies your shell profile, PATH, registry, or system configuration
• Never sends telemetry, analytics, or crash reports to any server
• Never opens network connections (the sandbox itself is fully offline)

Subprocess engine safety

On Windows and macOS where the native POSIX sandbox is not available, SubprocessEngine uses Python's subprocess.run() with strict timeout enforcement. While this does not provide kernel-level memory limits, the process is still killed after the timeout expires. No zombie processes are left behind — the watchdog ensures cleanup.

Target use cases

Aestra is engineered for environments where untrusted or user-submitted code must be executed with microsecond-level determinism, strict hardware boundaries, and zero risk to the host system.

Competitive programming judges

Online judge platforms, contest engines, and internal team training environments require predictable time and memory accounting across thousands of heterogeneous submissions. Traditional judges rely on wall-clock measurements that fluctuate with server CPU load, causing false Time Limit Exceeded verdicts during traffic spikes.

Aestra solves this by delegating time limits to Linux kernel scheduler accounting:

• Deterministic CPU time: Measures strictly user_time + kernel_time via the wait4 system call with microsecond resolution. Background server operations never inflate submission runtimes.
• Hardware memory ceiling: Uses RLIMIT_AS to restrict address space. When a submission allocates beyond its quota (e.g. vector<int> a(1e9)), the allocation immediately fails without touching host swap or triggering the OS OOM killer.
• Sub-millisecond startup: Uses native fork and execve without the multi-hundred-millisecond latency overhead of container lifecycle management.

Automated academic grading

Computer science university courses and autograding portals (such as automated submission runners and evaluation environments) frequently run untrusted student code that may contain infinite loops, memory leaks, or accidental system calls.

• Zero root privilege: Runs entirely in user space. Student submissions cannot modify system configuration, write outside the designated sandbox, or corrupt other processes.
• Fork bomb protection: Enforces RLIMIT_NPROC to cap child process creation, preventing malicious or accidental recursive fork() calls from locking the grading server.
• Standardized verdicts: Direct mapping to educational grading categories (ACCEPTED, WRONG_ANSWER, TIME_LIMIT_EXCEEDED, MEMORY_LIMIT_EXCEEDED, RUNTIME_ERROR).

Local problem setting & stress testing

Contest problem setters and competitive programmers preparing for algorithmic contests need to stress-test candidate solutions against edge cases before publishing:

• Automated test discovery: Scans test suites matching .in with .out or .ans and executes full batches with aggregated verdicts.
• Diff inspector: Pinpoints exact token differences between actual program output and expected answers using TOKEN or EXACT mode.
• Generator stress loops: Can be scripted inside a Python loop to continuously generate random test cases, run a brute-force $O(N^2)$ solution against an optimized $O(N \log N)$ solution, and stop upon finding a counterexample.

AI & LLM code evaluation

Autonomous AI agents, coding assistants, and research benchmark suites (such as HumanEval, MBPP, or SWE-bench) generate and execute arbitrary code strings at high velocity. Running LLM-generated code directly on the host machine presents substantial risk of system pollution, rogue network sockets, or infinite execution loops.

• Environment isolation: Unsets all host environment variables, removing API keys, credentials, and network proxy access from the executed child process.
• Hard backstop watchdog: If a runaway AI-generated process ignores SIGXCPU, a hard kernel SIGKILL terminates the process cleanly within 1 second.
• Machine-readable telemetry: The Python SDK returns structured dataclasses (ExecutionResult) ready for automated reward scoring and validation pipelines.

Running programs

Execute a compiled binary or script under hardware-enforced CPU and memory constraints, and receive structured telemetry about the execution.

CLI usage

The aestra run command executes a single binary with the specified constraints:

aestra run ./solution.out --time-limit 2000 --memory-limit 512

Or invoke directly via Python module: python -m src.cli run ./solution.out --time-limit 2000 --memory-limit 512

Telemetry output

After execution completes (or is terminated), Aestra prints a structured telemetry block:

[Telemetry]
Status: TIME_LIMIT_EXCEEDED
CPU Time: 2003ms
Peak Memory: 12.1MB
Exit Code: 137 (SIGKILL)

The CPU time shown is user + kernel time measured by the kernel via wait4 — not wall-clock time. This means background system load does not affect the measurement.

Available flags

Python SDK

Use the engine directly from Python for programmatic execution and result inspection:

from pathlib import Path
from src.config import ExecutionLimits
from src.engine import get_engine

engine = get_engine()
limits = ExecutionLimits(time_limit_ms=2000, memory_limit_mb=512)
result = engine.execute(Path("./solution.out"), limits, input_data="42\n")

print(result.status.value)        # OK | TIME_LIMIT_EXCEEDED | ...
print(f"{result.cpu_time_ms:.2f} ms")
print(f"{result.peak_memory_mb:.1f} MB")
print(result.stdout)

Execution statuses

Every execution returns an ExecutionStatus enum. These map directly to competitive programming judge verdicts:

Batch testing

Run a program against a full directory of test cases, automatically discover input/output pairs, and receive aggregated verdicts with per-case timing.

Basic usage

aestra test ./solution.out --cases ./tests/ --mode token

Or invoke directly via Python module: python -m src.cli test ./solution.out --cases ./tests/ --mode token

Test case discovery

Aestra automatically discovers paired input/output files in the test directory. It supports multiple naming conventions commonly used in competitive programming:

Files are matched by base name — foo.in pairs with foo.out or foo.ans. Input files without a matching output file are skipped with a warning.

Verdicts

Each test case produces one of the following verdicts:

Comparison modes

The --mode flag controls how actual output is compared against expected output. See the Output comparison section for detailed behavior.

Output comparison modes

The OutputChecker class compares actual program output against expected answers using one of three comparison strategies. The mode you choose affects whether trailing whitespace, extra newlines, or formatting differences cause a WRONG_ANSWER verdict.

Available modes

Python usage

from src.checker import OutputChecker, CheckerMode

checker = OutputChecker(CheckerMode.TOKEN)
result = checker.check(actual="42 \n", expected="42")
print(result.is_correct)  # True — whitespace difference ignored in TOKEN mode

# EXACT mode would reject this:
strict = OutputChecker(CheckerMode.EXACT)
result = strict.check(actual="42 \n", expected="42")
print(result.is_correct)  # False — trailing space and newline cause mismatch

CheckResult object

The check() method returns a CheckResult dataclass:

Interface and system layout

Aestra provides structured interfaces at every layer: a clear terminal output layout for interactive debugging, a composable Python SDK for automated pipelines, and hardware-enforced boundaries at the kernel level.

System architecture layout

The system is organized into decoupled layers communicating across language boundaries:

Terminal CLI output layout

When running through the command line, Aestra produces structured visual output designed for rapid terminal inspection.

Single execution layout

$ aestra run ./solution.out --time-limit 2000 --memory-limit 512

[Telemetry]
Status: OK
CPU Time: 14.8ms
Peak Memory: 8.4MB
Exit Code: 0

[Output]
42

Batch test runner layout

$ aestra test ./solution.out --cases ./tests/ --mode token

Running 4 test cases on solution.out...
Limits: 2000ms CPU, 512MB RAM | Mode: TOKEN

  [ACCEPTED]               test_01.in        12.4ms    8.2MB
  [ACCEPTED]               test_02.in        15.1ms    8.4MB
  [TIME_LIMIT_EXCEEDED]    test_03.in      2001.2ms   12.0MB
  [WRONG_ANSWER]           test_04.in         9.8ms    6.1MB
      Expected:
      42 100
      Actual:
      42 99

Verdict: 2/4 test cases accepted.

Verdict badge taxonomy

Verdicts represent standardized competitive programming judge outcomes:

Python SDK dataflow layout

The programmatic interface follows a unidirectional dataflow pipeline:

from pathlib import Path
from src.config import ExecutionLimits
from src.engine import get_engine
from src.checker import OutputChecker, CheckerMode

# 1. Configure resource limits
limits = ExecutionLimits(time_limit_ms=1000, memory_limit_mb=256)

# 2. Acquire appropriate engine (NativeEngine or SubprocessEngine)
engine = get_engine()

# 3. Execute binary and capture telemetry
result = engine.execute(Path("./solution"), limits, input_data="10 20\n")

# 4. Compare output against expected answer
checker = OutputChecker(mode=CheckerMode.TOKEN)
check_result = checker.check(actual=result.stdout, expected="30\n")

print(f"Verdict: {'ACCEPTED' if check_result.is_correct else 'WRONG_ANSWER'}")
print(f"CPU Time: {result.cpu_time_ms}ms | Peak RAM: {result.peak_memory_mb}MB")

Architecture

Aestra uses a two-tier execution model. The Rust core handles low-level POSIX sandboxing, while the Python frontend provides CLI orchestration, answer verification, and configuration management. The two layers communicate through a zero-cost PyO3 FFI bridge.

Tier 1 — Native POSIX sandbox

On Linux and WSL, aestra_core (compiled from src/sandbox_posix.rs) performs the following sequence:

1. Creates three POSIX pipes for stdin, stdout, and stderr IPC
2. Calls fork() to create a child process
3. In the child: applies setrlimit for RLIMIT_CPU, RLIMIT_AS, RLIMIT_NPROC, and RLIMIT_FSIZE
4. Redirects file descriptors with dup2 and calls execve with an empty environment
5. In the parent: writes input data to stdin pipe, then reads stdout and stderr through bounded buffers
6. Calls wait4 to collect the exit status and rusage struct containing CPU time and peak RSS
7. Interprets the exit signal (SIGXCPU, SIGKILL, SIGSEGV) to determine the verdict

Tier 2 — Subprocess fallback

On Windows and macOS, or when the native extension is not compiled, SubprocessEngine in src/engine.py provides an equivalent interface using Python's subprocess.run(). It passes timeout= for time enforcement and measures wall-clock time via time.perf_counter().

Limitations of the fallback engine:

• Memory measurement is not available (reports 0 bytes)
• Wall-clock time is used instead of CPU time — affected by system load
• No kernel-level process limits — the target runs with normal user permissions

Project structure

aestra/
├── src/
│   ├── core/
│   │   ├── lib.rs               # PyO3 module definition — exposes execute_native()
│   │   └── sandbox_posix.rs     # Rust POSIX sandbox: fork, setrlimit, execve, wait4
│   ├── __init__.py              # Package exports
│   ├── checker.py               # OutputChecker & FloatToleranceChecker
│   ├── cli.py                   # Production CLI (run, test, fuzz, doctor)
│   ├── compiler.py              # Multi-language compiler pipeline & SHA-256 caching
│   ├── config.py                # ExecutionLimits dataclass
│   ├── engine.py                # NativeEngine & SubprocessEngine
│   ├── models.py                # ExecutionResult & ExecutionStatus
│   ├── runner.py                # BatchRunner engine & testcase discovery
│   └── sdk.py                   # High-level SDK, concurrent Fuzzer & Minimizer
├── tests/
│   ├── test.py                  # Master test suite runner
│   └── test_*.py                # Modular unit & integration tests
├── scripts/
│   ├── aestra.wxs               # WiX v4 definition for native Windows MSI installer
│   └── build_msi.ps1            # Automated zero-cost WiX build script
├── assets/                      # Application icons & emblem branding
├── Cargo.toml                   # Core Rust extension crate configuration
├── pyproject.toml               # Python build & packaging metadata
└── .github/workflows/           # CI, release packaging, and MSI workflows

API reference

Complete reference for all public classes, methods, and data models in the Aestra Python SDK.

ExecutionLimits

Python src.config.ExecutionLimits

Frozen dataclass that defines resource constraints for a single execution run.

Properties

ExecutionResult

Python src.models.ExecutionResult

Frozen dataclass containing the outcome and telemetry from a single execution.

Properties

get_engine()

Python src.engine.get_engine() → BaseEngine

Factory function that returns the best available execution engine. Attempts to import aestra_core and returns NativeEngine if available, otherwise returns SubprocessEngine.

from src.engine import get_engine

engine = get_engine()
# Returns NativeEngine on Linux/WSL, SubprocessEngine on Windows/macOS

OutputChecker

Python src.checker.OutputChecker

execute_native()

Rust aestra_core.execute_native() → dict

Low-level Rust function exposed via PyO3. Called internally by NativeEngine.

Contributing

Contributions to Aestra are welcome. We maintain strict engineering standards to preserve deterministic execution and FFI boundary safety. This guide covers development setup, quality checks, pull request workflow, and project conventions.

Development setup

You need both Rust and Python to work on the full codebase:

Prerequisites

Environment setup

git clone https://github.com/Elitsuv/aestra.git
cd aestra

python3 -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

pip install maturin ruff mypy pytest
maturin develop

Quality standards

All pull requests must pass the following checks locally before submission. The CI pipeline runs these automatically on every PR.

Python linting Python

ruff check .              # Lint check
ruff format --check .     # Format check
mypy src/                 # Type check

Rust linting Rust

cargo fmt --all -- --check                                    # Format check
cargo clippy --all-targets --all-features -- -D warnings      # Lint check
cargo test --all                                              # Unit tests

Pull request lifecycle

1. Branch naming: Use scoped branch names like feat/sandbox-limits, fix/zombie-pid, or docs/api-reference
2. Atomic commits: Write clear, imperative commit messages following conventional commits — e.g. feat(rust-core): enforce rlimit AS
3. Target main: All PRs target the main branch. Ensure both Python and Rust CI checks pass before requesting review.
4. PR quality audit: The PR template includes a checklist for code quality, test coverage, and documentation updates.

Label taxonomy

Attach appropriate labels to your PR for categorization and changelog generation:

Size labels

Type labels

Domain labels

CI pipeline

The CI pipeline runs on every push to main and every pull request. It has two jobs:

Python quality CI

Runs on ubuntu-latest with Python 3.11. Executes Ruff lint, Ruff format, and Mypy type checking against src/.

Rust core build CI

Runs on both ubuntu-latest and windows-latest in a matrix. Executes cargo fmt --check, cargo clippy -D warnings, cargo test, and maturin build --release to verify the extension compiles cleanly on both platforms.

Changelog

Release notes and version history for Aestra.

Recent commits