# Shadow Simulator: Real Applications in Controlled Network Experiments

> Shadow is a discrete-event network simulator that runs real application code as native Linux processes inside a configurable virtual network. It suits distributed-systems researchers who need deterministic experiments, especially Tor simulations, but its partial system-call support limits application compatibility.

**shadow/shadow** — Shadow is a discrete-event network simulator that directly executes real application code, enabling you to simulate distributed systems with thousands of network-connected processes in realistic and scalable private network experiments using your laptop, desktop, or server running Linux.

- Repository: https://github.com/shadow/shadow
- Website: https://shadow.github.io
- Stars: 1,735 · Forks: 285
- Language: Rust
- License: NOASSERTION
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/shadow-shadow

## Shadow's Role in Distributed-System Experimentation

Shadow addresses a specific gap between network emulators and conventional network simulators. A network emulator runs real applications over real operating-system kernels in real time, which preserves application behavior but makes experiments difficult to reproduce because timing can vary. The README explains that emulated processes can exceed an unknown computational threshold, causing time distortion and undefined behavior. That makes emulator results dependent on execution load and scheduling conditions.

Shadow takes a different position. It still runs unmodified application code, but places that code inside a discrete-event simulation. This arrangement is intended for researchers who need controlled network conditions, repeatable runs, and experiments involving many network-connected processes. The project description names laptops, desktops, and servers running Linux as possible hosts, with simulations scaling to thousands of processes and, according to the README, potentially hundreds of thousands.

The main users are therefore distributed-systems researchers, networking researchers, and developers who need to examine behavior under controlled latency, packet loss, and routing conditions. Tor is the project’s primary motivating use case. Shadow may also be appropriate for experiments involving applications that can operate through its supported system-call surface, but it is not a general-purpose replacement for every Linux network test.

## How Shadow Interposes on Real Linux Applications

Shadow begins with real application code and native Linux processes. It does not require the application to be rewritten as a simulator-specific model. Instead, the simulator co-opts each process at the system-call API. Calls handled by Shadow are intercepted and redirected into the simulated execution environment, while calls outside the supported surface may fail or behave incorrectly.

The managed processes communicate through a private virtual network constructed by Shadow. The simulator implements simulated versions of common protocols, including TCP and UDP. It also models network characteristics such as path latency and packet loss through a configurable network graph. Application code therefore performs ordinary networking operations at the operating-system boundary, but the timing and delivery behavior of those operations are controlled by the simulation rather than by wall-clock execution alone.

This is a hybrid design. The application layer retains real executable code and native process semantics, while the network and time environment remain under simulator control. That combination explains Shadow’s appeal for systems research: an experiment can change network conditions and repeat the same logical workload without relying on a live network. It also explains why compatibility depends on the intercepted system-call API rather than only on the application’s networking logic.

## Emulation, Simulation, and the Network Control Boundary

Shadow should not be confused with a tool that models every network protocol and application as an abstract object. Its distinction is that it directly executes real applications while controlling their interaction with the simulated network. The README contrasts this with mininet, which runs real application code on real OS kernels in real time, and ns-3, which offers control and scalability but replaces real application code with application abstractions.

Shadow’s boundary is visible in its system-call implementation. The project states that it implements more than 150 functions from the system-call API, but it does not fully support every API feature. Applications making basic use of supported calls may work without modification. Applications using complex features or unlisted functions may not function correctly. This means the simulator is not only constrained by its network model. It is also constrained by how faithfully Shadow can intercept and emulate the host interface expected by the application.

That limitation is especially important for systems with timing-sensitive behavior, unusual file or process operations, or complex operating-system features. Shadow’s deterministic network experiment is valuable only when the application can run within the supported execution boundary. The README specifically says Tor simulation is already fairly well supported, but it does not claim equivalent support for every application category.

## Building Shadow from the Repository Setup

The README directs users to install the project dependencies first, then build, test, and install Shadow into `~/.local`. The repository provides a `setup` command for these operations. The documented sequence is:

```bash
$ ./setup build --clean --test
$ ./setup test
$ ./setup install
```

The first command performs a clean build with tests as part of the build operation. The second runs the test command separately, and the third installs the resulting project under `~/.local`. The README does not give a standalone dependency-install command, so dependency installation must follow the linked dependency documentation at `https://shadow.github.io/docs/guide/install_dependencies.html`.

After installation, the README points to the user guide and example simulations. It does not provide a single command for running the first example, so a first use should begin with the project’s usage guide or the examples collection rather than with an invented command. The guide is the appropriate place to learn how an experiment is configured, which applications are launched, and how the network graph is defined. The examples directory is also part of the repository and provides the project’s concrete starting point for experimentation.

## A First Shadow Experiment with a Configured Network

A useful first Shadow experiment is one that launches an application, connects it to the simulator’s private network, and varies a network characteristic such as latency or packet loss. The repository README does not include a complete experiment configuration, so it does not support reproducing a specific config file here. The documented path is to open the example simulations after completing the setup sequence.

The intended data flow is nevertheless clear. Shadow starts the selected real application as a native Linux process. The process performs system calls that Shadow intercepts. TCP or UDP operations are handled by Shadow’s simulated protocol implementations. Network behavior then follows the configured graph, including path latency and packet loss. Results can be collected from the application and experiment environment according to the guide, but the README does not specify a universal result-file format or a standard plotting command.

This setup is preferable to testing a live deployment when the research question concerns how an application responds to network conditions. It avoids depending on external network availability and allows conditions to be changed between runs. However, it also introduces the system-call compatibility question. Before launching a real application, its reliance on files, processes, sockets, timing, and less common operating-system features should be compared with Shadow’s documented API support. The README does not document a complete compatibility matrix in the project description, so this check cannot be reduced to a single version number.

## Maintenance, Licensing, and Upgrade Considerations

Shadow is not archived, and the last push was on 2026-10-14. The repository’s recent releases include `v3.3.0` on 2025-10-16, `v3.2.0` on 2024-06-07, and `v3.1.0` on 2023-12-31. These dates indicate that the project has had versioned releases, but they do not by themselves establish compatibility with a particular application or operating-system image.

The project uses a custom license identified by GitHub as “Other.” The repository includes a `LICENSE` file, so adoption requires reading that file for the actual permissions and conditions. The README does not summarize whether the license permits commercial use, redistribution, modification, or particular forms of deployment. This review therefore cannot give legal guidance or reduce the license to a permissive or restrictive category.

Upgrades also require attention to the application execution boundary. Because Shadow emulates more than 150 system-call functions without fully supporting all API features, a Shadow upgrade can affect which applications run correctly even when the network configuration is unchanged. The release history provides version boundaries for review, while the changelog and documentation are the relevant project files for checking changes before rebuilding an experiment.

## Conclusion

Researchers studying Tor or applications built around basic networking calls should evaluate Shadow first, while teams needing complete kernel behavior or unrestricted application compatibility should verify their required system calls before adoption. The first adoption check is whether the application relies on unsupported API features.

## FAQ

### What is Shadow Simulator used for?

Shadow Simulator is used for controlled, reproducible experiments involving distributed systems and real application code. It supports configurable network conditions such as latency and packet loss, with Tor simulations identified as a primary use case.

### Does Shadow run real applications or only network models?

Shadow directly executes real application code as native Linux processes. It interposes at the system-call API and uses simulated TCP and UDP implementations to connect those processes through a private virtual network.

### Can Shadow run any Linux application unchanged?

No. The README states that Shadow implements more than 150 system-call functions but does not fully support all API features. Applications using basic supported calls may work, while applications using complex features or functions may fail or behave incorrectly.

## Sources

- [Issues](https://github.com/shadow/shadow/issues)
- [Project website](https://shadow.github.io)
- [README](https://github.com/shadow/shadow/blob/main/README.md)
- [Releases](https://github.com/shadow/shadow/releases)
- [shadow/shadow on GitHub](https://github.com/shadow/shadow)

---

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