Installation

Aestra is not a PyPI package. You build it from source using Maturin, which compiles the Rust core and installs the Python package into your virtual environment in one step.

Prerequisites

If you don't have Rust installed, get it from rustup.rs:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Build from source

Clone the repository, create a virtual environment, and build the native extension:

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
maturin develop

The maturin develop command compiles the Rust aestra_core crate and installs it as a Python extension module into the active virtual environment. This takes about 30 seconds on first build and under 5 seconds on incremental rebuilds.

Optional automated installers

For zero-friction setup without manual environment configuration, we created automated installer scripts (scripts/install.sh and scripts/install.ps1). These scripts automate dependency checks, environment isolation, and compilation in a single command:

curl -fsSL https://raw.githubusercontent.com/Elitsuv/aestra/main/scripts/install.sh | bash

chmod +x scripts/install.sh
./scripts/install.sh

iex (irm https://raw.githubusercontent.com/Elitsuv/aestra/main/scripts/install.ps1)

powershell -ExecutionPolicy Bypass -File .\scripts\install.ps1

Verify installation

Run this command to confirm the engine is working and see which backend is active:

python3 -c "from src.engine import get_engine; e = get_engine(); print(type(e).__name__)"

Uninstall

Delete the cloned directory and remove the virtual environment. No system files are modified:

deactivate           # exit the venv
rm -rf aestra/       # remove the project directory

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 (such as Codeforces, AtCoder, CSES, or internal team training judges) 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 Docker container lifecycle management.

Automated academic grading

Computer science university courses and autograding portals (such as Gradescope or automated lab submission runners) 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 ICPC or Codeforces rounds 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/
│   ├── __init__.py          # Package exports
│   ├── cli.py               # CLI entrypoint (run, test commands)
│   ├── config.py            # ExecutionLimits dataclass
│   ├── models.py            # ExecutionResult, ExecutionStatus enum
│   ├── engine.py            # BaseEngine, NativeEngine, SubprocessEngine, get_engine()
│   ├── runner.py            # BatchRunner engine with testcase discovery
│   ├── checker.py           # OutputChecker with TOKEN/EXACT/IGNORE_WHITESPACE
│   ├── lib.rs               # PyO3 module definition — exposes execute_native()
│   └── sandbox_posix.rs     # Rust POSIX sandbox: fork, setrlimit, execve, wait4
├── tests/
│   └── test.py              # Unified test suite
├── scripts/
│   ├── install.sh           # Zero-dependency Linux/macOS installer
│   └── install.ps1          # PowerShell Windows installer
├── Cargo.toml               # Rust crate config (PyO3, libc)
├── pyproject.toml            # Python project metadata
└── .github/
    └── workflows/ci.yml     # CI: Ruff, Mypy, Clippy, Cargo Test, Maturin Build

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