This repo holds scripts which allow users to interact with the Gensyn Reproducible Execution Environment (REE) as a Docker container. REE enables fully reproducible execution of machine-learning workloads. Note that this current release is constrained to reproducible inference of LLMs.
We provide an overview of REE at https://gensyn.ai/ree and full documentation at https://docs.gensyn.ai/tech/ree.
This repository provides access to both open-source and proprietary components.
The REE SDK source code, and any other files expressly identified as MIT-licensed, are licensed under the MIT License in the REE-SDK-License file.
The REE compiler binary and the REE reproducible-operators binary, as included in any Docker image, release artifact, or other binary distribution are not licensed under the MIT License. Those proprietary components are licensed under the REE Binary License Agreement in the REE-Binary-License file. This is also visible by pressing l in the provided TUI.
By downloading, pulling, installing, accessing, or using the proprietary REE binaries or any Docker image or release artifact containing them, you agree to the REE Binary License Agreement.
To get started with REE, please first ensure you have installed and configured Docker for your system. Note that if you are using Docker Desktop, you may need to adjust the memory limit. Then, clone this repository:
git clone https://github.com/gensyn-ai/ree.git
cd ree
We provide two scripts for running REE: ree.py and ree.sh. We expect most users to use ree.py, which provides a more user-friendly interface. The ree.sh script is a lower-level interface that may be useful for debugging or advanced use cases (and is called by ree.py).
To get started, simply run ree.py using Python:
python3 ree.py
This will drop you into a Terminal User Interface (TUI) where you can select a model to run, provide a prompt, and run reproducible inference. For long prompts, we recommend using a prompt file and providing that to the TUI in the appropriate field. The prompt file must be in JSONLines format, where each line is either a string or an object with a prompt field containing the string prompt. For example:
"What is the capital of France?"
{"prompt": "What is the largest mammal?"}
Note that the Prompt Text and Prompt File fields are mutually exclusive.
Once REE is running, you will be presented with a TUI that allows you to select a model, provide a prompt, and run inference. The TUI will guide you through the process and provide options for configuring the inference run. After the run is complete, REE will generate a receipt that contains all of the information about the run, including the model used, the prompt, the output, and all of the metadata needed to reproduce the run. The Model Name refers to a HuggingFace model identifier, such as Qwen/Qwen3-8B. The Prompt is the text input that you want to provide to the model for inference. You can either type this directly into the TUI or provide a file containing the prompt.
For a list of available models, please see our documentation. Note that this list is non-exhaustive: any HuggingFace model that is compatible with our system may be used. If you have a specific model in mind that is not on our list, please file an issue and we will do our best to support it.
Executing a model using REE produces two outputs: the inference output (i.e., the text generated by the model), and a receipt. The receipt is a JSON file that contains all of the information about the run, including the model used, the prompt, the output, and all of the metadata needed to reproduce the run. The receipt is designed to be shared with others, who can then use it to verify that they can reproduce the same output using REE. We recommend sharing receipts alongside any claims about model behavior, so that others can verify those claims for themselves.
REE provides a number of subcommands for fine-grained use cases, though most users will only need to use two subcommands: run, and verify.
The run subcommand will, as the name suggests, run a single inference workload for the specified model and generate a receipt. This involves the following steps:
- Download the REE image (if not already present locally -- note that this make take several minutes the first time you run it).
- Spin up the REE container.
- Run the inference workload inside the container using the provided configuration. This will also generate the receipt file.
The verify subcommand takes as input a receipt file and will then invoke REE to verify that the receipt is valid. This is useful for users who have received a receipt from another user and want to verify it, or for users who have generated a receipt and want to verify it before sharing it with others.
The validate subcommand validates that a given receipt is properly structured and internally consistent (i.e., the hashes given in the receipt match the actual hashes of the contents). This is a less stringent check than verify, which actually re-runs the inference and checks that the output matches the receipt, and is useful for users who want to check that a receipt is well-formed before attempting to verify it. Note that verify will automatically perform validation as part of its process.