# OpenWorm's FAQ says edits inside the container survive, and the stop script discards them

> The container that assembles a nervous system model and a body model into one simulation of a roundworm, needing 60 GB of disk and 2 GB of memory, with a default run that produces a fraction of the output shown in the project's own examples. Four Dockerfiles and roughly a dozen scripts sit in a repository whose README names four of them.

**openworm/OpenWorm** — Repository for the main Dockerfile with the OpenWorm software stack and project-wide issues

- Repository: https://github.com/openworm/OpenWorm
- Website: http://openworm.org
- Stars: 3,067 · Forks: 245
- Language: Python
- License: MIT
- Published: 2026-09-24 · Updated: 2026-09-24 · Language: en
- Canonical page: https://hysenlabs.com/projects/openworm-openworm

## This repository holds the packaging, not the simulation

The repository description is unusually honest about its own scope: it exists to hold the main Dockerfile with the OpenWorm software stack, plus project-wide issues.

The science lives elsewhere. The nervous system model and the body model are separate projects with their own repositories, and this container pulls them together and runs both, with the body model consuming the nervous system's output.

The container is described as a self-contained environment, fully set up to get a beginner started. The README also adds a scope limit to it: at the moment it runs simulations and produces visualisations for you, but those visualisations have to be viewed outside the container. So the deliverable is files on your filesystem, not a service to point a browser at.

That framing explains the rest of the repository. A Dockerfile that clones two model repositories at build time, one orchestrating script that decides what runs in what order, and a set of shell wrappers is exactly the shape of an assembly project, and it is also why the repository's own tree is mostly scripts.

## The default run is a fraction of the output the examples show

The quickstart section's example output comes with a note that is easy to skim and important to plan around. It says that running the simulation for its full length would produce content like the examples above, but that the default run time is limited so the run finishes in a reasonable time. As a result you will see partial output, equivalent to about five percent of run time compared with the examples, and to extend it you pass an argument.

That argument is documented in the advanced section. It takes a number, it is described as the duration of the simulation in milliseconds, its default is fifteen, and the value to use for the full movie is five thousand, which the README annotates as five seconds.

So two different figures describe how short the default is, and they do not agree. The note says about five percent; the argument documentation goes from fifteen to five thousand. Both numbers are in the same document and neither is reconciled with the other.

The unit is worth pausing on as well. The duration is expressed in milliseconds, so the default is fifteen milliseconds of simulated time and the full run the examples show is five seconds of it. That is a very short window for a nervous system model, and it is the reason the examples and the default disagree about how much you will see.

## The prerequisites are 60 GB of disk against 2 GB of memory

The pre-requisites are two numbers and a tool.

You need at least sixty gigabytes of free space and at least two gigabytes of memory. That asymmetry is the whole footprint of the project in one line, and it reads as a real requirement rather than a slip: the container installs a display server, a window manager, a virtual framebuffer, an OpenGL stack, a Java runtime, an MPI runtime, and the Linux kernel source with its headers and the module build tools. Sixty gigabytes is what that comes to, and most of it is the parts you are not thinking about when you picture a neuron simulation.

Two gigabytes of memory, by contrast, is enough to run it.

The third requirement is the ability to clone git repositories, and the README links both a command line installation guide and a graphical client for people who would rather not use a terminal.

It then anticipates the disk problem. If your machine does not have sixty gigabytes free, you can point image storage at an external drive, and there is a separate instruction for macOS, where the location is set in an preferences tab, plus a forum thread linked for Linux.

## Edits made inside the container are destroyed by the cleanup step the procedure ends with

There is a question in the FAQ about modifying the simulation without rebuilding, and the answer is encouraging until the last sentence.

It says yes, it is possible, and marginally more complex. The easiest way is to modify anything in the container once you are inside it, where it works like a normal shell. To change code rather than files you need a terminal editor. And then: once you have modified something in the container you do not need to rebuild.

The last sentence: if you run the stop script once you exit, those changes will be gone.

Step six of the running procedure is exactly that. After the simulation ends you run the stop script to clean up the running container. So the two sections of the same README describe incompatible workflows: the FAQ invites you to work inside the container and tells you rebuilding is unnecessary, while the procedure concludes by removing the container those edits live in.

The procedure itself starts two steps earlier, from a clone:

```bash
git clone http://github.com/openworm/openworm
cd openworm
```

Note that the address is plain http, while every other link in the document, including the three workflow badges at the top, uses the encrypted form.

There is a companion script for the use case that works. One of them logs you into the container before the orchestrating script runs, so you can inspect the internals of the several code bases checked out inside it, and the same cleanup script ends that session too.

The README also names the two files to edit when you do want a change that sticks: the Dockerfile for what gets installed and the orchestrating script for what runs. Both require a rebuild.

## Four Dockerfiles and about a dozen scripts, with four documented

The root listing is where this repository's history is visible, and the README does not describe most of it.

There are three files named as Dockerfiles: the main one, one with a second number appended, and one named for Intel. Three continuous integration workflows carry matching names, one for the image, one for a quick run, one for Intel, and all three are badged at the top of the README. So the duplication is systematic rather than accidental, and an Intel-targeted variant is the probable reason.

The scripts are less tidy. The README names four: a build script, a run script, a stop script, and one that opens a shell in the container. Each is documented with a Windows batch equivalent and a PowerShell invocation.

The tree contains those four, plus a second generation of build and run scripts with a digit appended, plus a second shell-only variant with that digit, plus a quick run script, plus a script whose name suggests a language runtime, plus a rebuild script and a test script. There is also a configuration file whose name marks it silent and ties it to the Intel SDK.

Nothing in the README says which generation is current. A contributor arriving at this repository has four documented entry points and roughly eight undocumented ones, and the two Intel-named artefacts are the only clue about why any of it is duplicated.

## The container user is granted passwordless root, and the image never drops privileges

The Dockerfile creates a user and then grants that user everything.

The user name is a build argument defaulting to a two-letter name, and it is the same name that appears in the paths the README tells you to copy files out of, so the naming is consistent across the build and the documentation.

The creation is done by writing directly to the password and group files with a shell redirect rather than using the tools for the job. The numeric identifiers are hardcoded in the script as one thousand for both the user and the group, so they are not configurable even though the user name is. The home directory is then created and handed over.

Next, a drop-in file is written into the sudo configuration directory granting that user the ability to run anything as anyone without a password, with restrictive permissions on the file itself. A passwordless grant like that is a common container convenience and also means there is no credential inside the image to leak.

The part that undercuts it comes later. The instruction that would switch the image to run as that user is present in the Dockerfile and commented out. So the image builds and runs as root, the passwordless grant is never exercised, and the user exists only so that files it creates have a predictable owner on your filesystem.

## A base that upgrades itself during build, and a kernel source tree in the image

The Dockerfile opens on a current long-term Ubuntu and then upgrades itself twice in the same layer, first a normal upgrade and then a distribution upgrade. That is convenient and it means the image is not reproducible: the same Dockerfile produces a different filesystem on different days, and there is no pin to appeal to.

The package list is the reason for the disk figure. Beyond the obvious build tools and the Python headers it installs a display server, a window manager, X utilities, OpenGL and Mesa development libraries, a font library, a virtual framebuffer, a terminal multiplexer, a Java 8 runtime, an MPI runtime with its headers, ffmpeg, and unzip. It then installs the Linux kernel source, the generic kernel headers and the module build tools, which is a kernel build environment inside a container.

The Python side is small and exactly pinned: one neural simulation package at a specific version, installed system-wide with the flag that tells pip to write outside its managed environment. Then the model repositories are cloned, so the simulation source is fetched at build time rather than vendored.

One more line is worth naming. The image adds the user to the video group, which is what gives the OpenGL stack access to a display device. Combined with the display server and the virtual framebuffer, that is the rendering path for the body's 3D model.

## Conclusion

This repository fits someone who wants to see the parts of a whole-organism simulation work end to end on their own machine, rather than to study any one component, because its job is assembly and its value is that the two models run against each other in one container. Three things to plan for. The default run is deliberately short and needs an argument to reach the output shown in the examples, so budget your expectations and your disk accordingly. Changes made inside the container do not survive the cleanup step the main procedure ends with, so plan on editing the two files the README points at and rebuilding rather than editing in place. And the repository carries several generations of build and run scripts with only four documented, so establish which pair is current before you trust a result.

## FAQ

### What is the OpenWorm Project?

An attempt to build the first comprehensive computational model of C. elegans, a microscopic roundworm with about a thousand cells. The approach is bottom-up: behaviour is meant to emerge from a simulation built on data from experiments, with data contributed by the scientific community and new collaborations formed with universities to fill gaps.

### How do I run the OpenWorm simulation?

Clone the repository, optionally run the build script, then run the run script; skipping the build step downloads the latest released image instead. You need Docker running, at least 60 GB of free space and at least 2 GB of memory. Output displays for five to ten minutes, the simulation then ends, you run the stop script to clean up, and results appear in an output directory on your machine. A duration argument in milliseconds extends the run beyond its short default.

### Where are the OpenWorm results stored?

In an output directory on your machine, outside the container, and the README notes the visualisations must be viewed there too. Inside the container the fuller output sits in a timestamped directory under the body model's simulations path, whose name can be found by checking the output directory; the worm motion data is a named text file in that directory.

### Does C. elegans feel pain?

The repository does not address sentience, and this is a computational modelling project rather than a biology reference. What it says about the organism is that it is extremely well studied in biology and that a deep, principled understanding of it remains elusive, which is the gap the project exists to work on.

## Sources

- [License: MIT](https://github.com/openworm/OpenWorm/blob/master/LICENSE)
- [openworm/OpenWorm on GitHub](https://github.com/openworm/OpenWorm)
- [Project website](http://openworm.org)
- [README](https://github.com/openworm/OpenWorm/blob/master/README.md)
- [Releases](https://github.com/openworm/OpenWorm/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/openworm-openworm