Edge Python

Sign In

Sign in to publish packages and pin them by sha256.

Sign in with GoogleSign in with GitHub

By continuing, you accept our Terms and Conditions.

@

Connect an agent

Copy and paste this into your agent session.

Edge Python is sandboxed Python that compiles to bytecode and runs on a VM, in the browser as WebAssembly or through the edge CLI.
Install the CLI with curl -fsSL https://cdn.edgepython.com/cli/install.sh | sh
Read https://edgepython.com/SKILL.md first, it is the full reference and every example in it is executable.
Nothing resolves unless edge.json declares it, so run edge add <name> before importing and grant what it asks under permissions for each scope.
Run the entry point with edge run main.py and every *_test.py with edge test.
Search the docs, people, services and packages with GET https://edgepython.com/api/search?q=<term>
Read what it finds by putting /api before the href, so /package/<name>, /package/<name>/<slug>, /@<handle>, /service/<name> and /docs/<path> all answer as data, and GET /api/docs lists the reference.
Pack and ship with edge build, then edge publish app.edge

Internals

Runbook

Five checks run beside the test suites. Each one has a make target at the root of the repo.

CheckCommandIn CI
Fuzzingmake fuzzDaily, 20 minutes
Mirimake miri SUITE=vmDaily, one runner per suite
Benchmake benchEvery push and pull request to main
Consistencymake test-cli SUITE=consistencyEvery push and pull request to main
Std packagesmake test-cli SUITE=stdEvery push and pull request to main

Fuzzing

The fuzzer feeds mutated source through the lexer, the parser and the VM. It also saves a snapshot at the first park and restores it into a fresh VM. It looks for panics and memory faults.

  • It runs on AFL++ through cargo-afl, on stable Rust.
  • The seeds are the programs in tests/cases/vm.json.
  • Only programs that parse reach the VM.

The harness runs the VM with an op budget of 100,000, a thousandth of the sandbox default. A loop that ends but runs long would otherwise read as a hang to AFL.

A campaign runs one instance per logical core until stopped. It needs Linux or macOS and cargo install cargo-afl.

make fuzz

CI runs the same target every day at 03:00 UTC for 1,200 seconds. A saved crash fails the run.

The crashes and hangs are uploaded as the fuzz-findings artifact and kept for 14 days. A local campaign writes them under fuzz/out/, one folder per instance.

The fuzzing manual covers container campaigns, resuming, reproducing a crash and triage.

Miri

Miri interprets the test suites and reports undefined behavior. It needs the nightly toolchain with the miri component. make miri builds the Miri sysroot first.

make miri SUITE=vm

SUITE is one of vm, snapshot, modules, parser, lexer and abi. CI runs every suite every day at 04:00 UTC, each on a runner of its own.

Bench

make bench runs every case of tests/cases/vm.json on the speed build of compiler.wasm and counts the WebAssembly instructions. Each instruction is priced at 0.82 ns. That way bench/.snapshot holds the same seconds and MB per case on every machine.

make bench

The bench fails when the mean or a single case moves past its threshold. It also fails when the snapshot was taken with another Rust, or when a case and its entry do not pair. make bench-update takes the snapshot again.

Consistency

Seeded programs call generated functions cold, again and warm, defined in the main file, in a module and as a method. Every call with the same arguments must answer the same, so code the engine runs differently once it is hot cannot drift. A run checks 500 programs, EDGE_CONSISTENCY_PROGRAMS sets more, and a failure keeps its program under the temp dir with its seed.

Std packages

The tests of every edge-python-std package run on the CLI built from the tree, so an engine change that breaks a published package fails CI.

Fuzzing manualCampaigns, resuming, reproducing and triage.ContributingBuilds, tests and what a pull request runs.CI workflowsThe main, fuzz and Miri jobs.