spirit-v1.5: an open VLA model and its RoboChallenge runtime

A foundation model for robots, plus the harness to score it

The repository description is short and the scope is worth reading carefully, because it contains two different things. It holds the official implementation of the Spirit-v1.5 VLA model, where VLA stands for vision, language and action, so a model that takes what a robot sees plus a language instruction and produces actions. Alongside that implementation, it contains the runtime wrapper required to reproduce the results on the RoboChallenge benchmark, and the README carries a results image for that benchmark. So this is a research code release with a reproduction harness attached, not a general purpose robotics library. The audience is a robotics researcher or a lab that wants to run the model, evaluate it on a standard table-top benchmark, or fine-tune it on their own data. The claim in the README is that as of the eleventh of January 2026 the model ranks first on the RoboChallenge Table30 benchmark, and since the initial release in January 2026 there have been two news entries, the first covering the technical blog, the inference code and the base and fine-tuned checkpoints, and the second, in April 2026, announcing the fine-tuning code. That sequence tells you the release was staged, with training code arriving later, and the repository layout reflects it.

A Qwen3-VL backbone with a DiT head

The architecture is described in a single comment in the directory tree, and it is the most informative line in the repository. The main model architecture file, modeling_spirit_vla.py, is described as a Qwen3-VL backbone plus a DiT head plus a policy API. That combination explains the shape of the system. The vision and language part is a pretrained vision-language model from the Qwen3-VL family, so the model inherits a general visual and textual representation rather than learning perception from scratch. The diffusion transformer head is what turns that representation into actions, and a diffusion policy is a generative approach to action, which means the policy samples trajectories rather than regressing a single action. The policy API in the same file is the seam between the model and the runtime, and it is what the RoboChallenge executor drives. Around that core, the tree shows the supporting layers a robotics release needs. There is a dataset package with a dataset implementation and a data transformations module, and a utils package with checkpoint loading and saving, distributed training helpers, logging, data normalisation, sampling strategies, tensor operations and vision-language model utilities. The sampling module in particular belongs to the diffusion head rather than to the dataset, and its presence is a reminder that inference here involves multiple steps rather than a single forward pass.

A RoboChallenge integration written as an HTTP client

The RoboChallenge directory is the part of the repository that is not model code, and its structure explains how the evaluation actually runs. There is a Python entrypoint, run_robochallenge.py, and a runner directory with the executor, described as handling checkpoint loading, inference and input and output, and a task_info module holding task metadata such as robot type, action type and prompts. The robot directory is derived from an open source RoboChallengeInference project, and it contains the HTTP client for the benchmark and a job worker with the job polling loop and execution flow. The utils directory under it, also derived from that project, holds shared enums and constants, logging helpers and miscellaneous utilities. So the benchmark is a remote service, and this repository talks to it over HTTP, polls for job status and executes the tasks locally. The distinction between the derived directory and the rest is a useful one to keep in mind when reading the code, because anything under robot and the nested utils directory came from elsewhere, while the executor and the task metadata are the glue written for this model. The robot directory also contains the interface client, which is the piece that decides how the model's actions are turned into commands for the simulated or physical robot.

Dependencies pinned hard, with a flash-attn trap

The dependency specification is unusually strict, and that is a deliberate choice rather than an accident. The base set for inference pins torch at 2.8.0, torchvision at 0.23.0, transformers at 4.57.1, diffusers at 0.35.2, safetensors at 0.5.3, numpy at 2.2.6, pillow at 10.4.0, requests at 2.32.5 and scipy at 1.15.2, and the pyproject repeats the same list as the project dependencies. The training extra adds opencv-python at 4.8.0 or newer for augmentation, wandb for experiment tracking, tqdm for progress bars, einops at 0.8.1 which the README notes is required by flash-attn, and flash-attn at 2.8.3. The uv configuration adds one more detail, with an extra build dependency entry pinning torch to 2.8.0 for the flash-attn build, which is what lets the package compile against the right PyTorch ABI. The README warns about the same thing in prose, that flash-attn requires matching CUDA and PyTorch versions, with a pointer to the flash-attention installation guide for when the install fails. The upshot for a reader is that this is a repository you should install inside a fresh environment rather than into an existing one, because the pins are the compatibility contract for the checkpoints.

Installing for inference, and installing for training

There are two supported routes and four command sequences, and the README is clear that the difference is what you need to run. The recommended path is uv, and for inference only the first pair applies.

uv sync
source .venv/bin/activate

For training, the extra is added to the sync.

uv sync --extra train
source .venv/bin/activate

The pip route is the same idea with more steps, creating a virtual environment and installing the base requirements file.

python -m venv .venv
source .venv/bin/activate
pip install -r requirements-base.txt

And for training with pip, the training requirements file is installed on top of the base one. The three dependency files are named for exactly this purpose, with requirements-base.txt described as the core dependencies for inference and kept backward compatible, requirements-train.txt as the additional training dependencies, and requirements.txt as the complete set for both. The system requirements are short, Python 3.10 or newer, and hardware tested on an NVIDIA A100 80GB GPU. One A100 for inference is the stated reference point, and that single line tells you more about the intended audience than anything else in the README.

Running the benchmark: five environment variables and a launcher

The runtime entry point is a minimal launcher script at scripts/run_robochallenge.sh, and the README explains the configuration it expects. The script requires several environment variables to be set, with the note that USED_CHUNK_SIZE defaults to 60 if it is not specified and that all the other variables are mandatory. TASK_NAME must correspond to a task defined in robochallenge/runner/task_info.py, ROBOCHALLENGE_JOB_ID is the unique identifier for the job collection, USER_TOKEN is the authentication token, and CKPT_PATH is the directory containing the model.safetensors file. The example below is for the move_objects_into_box task.

export TASK_NAME=move_objects_into_box
export ROBOCHALLENGE_JOB_ID=your_job_collection_id
export USER_TOKEN=your_user_token
export CKPT_PATH=/path/to/your_checkpoint_dir
export USED_CHUNK_SIZE=60

./scripts/run_robochallenge.sh

Two checkpoints are published on Hugging Face under the Spirit-AI-robotics organisation, the base model and a fine-tuned model for the move-objects-into-box task, and the launcher points at the fine-tuned one for that task. The action chunk size is worth understanding rather than copying. A chunk of 60 means the policy emits a block of actions and the runner executes part of it before asking for more, which is the usual way a generative policy is driven on a robot, and the default is a real parameter with latency and smoothness consequences rather than a formality.

Fine-tuning: the dataset, train.py and eight GPUs

The fine-tuning guide lists three prerequisites, and the third one sets the bar. You need the pretrained Spirit-v1.5 base model checkpoint, a training dataset as described in the dataset section, and a multi-GPU setup, with eight A100 80GB recommended. The training script is at the root of the repository and there is a second launcher, run_finetune.sh, beside the benchmark launcher in scripts. The data side is handled by the dataset package, with a dataset implementation and a transforms module, and the utils package carries the distributed training helpers, the data normalisation utilities and the logging module, which is where the wandb integration for experiment tracking sits. The dependency picture follows from that, since the training extra is where opencv for augmentation, wandb, tqdm, einops and flash-attn live. Flash Attention 2 is there for efficient training, and the README's note about matching CUDA and PyTorch versions applies to training at least as much as to inference. Two constraints are worth stating plainly. Reproducing the published RoboChallenge numbers means running the benchmark service, which needs a job collection identifier and a user token, so the leaderboard claim in the README cannot be checked by running the model alone. And a fine-tune on eight A100s is a research budget, not a weekend project.

Editorial conclusion

Adopt spirit-v1.5 if you are doing robotics research and want an open VLA checkpoint with the inference code, the benchmark wrapper and the fine-tuning path in one place, rather than a hosted API with no weights behind it. It does not fit a team without datacenter GPUs, because the model was tested on an NVIDIA A100 80GB and fine-tuning is recommended on eight of them, and it does not fit anyone who needs the RoboChallenge numbers reproduced without a job account and a token. Before you start, check the flash-attn version against your CUDA and PyTorch build, since the README flags that as the usual install failure, and decide whether you need inference only or the train extra.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. Project website
4. README
5. Spirit-AI-Team/spirit-v1.5 on GitHub