Ross is a container runtime system written in Rust, structured as a multi-crate workspace. It provides a gRPC-based daemon for managing containers and images, with a CLI for user interaction.
- Docker (for development environment)
- Make
Build the Docker image with pre-compiled binaries:
make build-imageStart the daemon in a Docker container with privileged mode (required for runc):
# Terminal 1: Start the daemon
make dev-runThis will start the Ross daemon listening on port 50051.
In another terminal, use the CLI to run a container:
# Terminal 2: Run hello-world
docker run --rm --network host ross-dev cli run hello-worldOr run alpine with a command:
docker run --rm --network host ross-dev cli run alpine echo "Hello from Ross!"# Terminal 1
$ make dev-run
Starting ross-daemon...
2024-12-09T10:00:00.000000Z INFO ross_daemon: Initializing store at "/tmp/ross/store"
2024-12-09T10:00:00.000000Z INFO ross_daemon: Initializing snapshotter at "/tmp/ross/snapshotter"
2024-12-09T10:00:00.000000Z INFO ross_daemon: Initializing container service
2024-12-09T10:00:00.000000Z INFO ross_daemon: Starting Ross daemon gRPC server on 0.0.0.0:50051
# Terminal 2
$ docker run --rm --network host ross-dev cli run hello-world
Pulling image docker.io/library/hello-world:latest...
docker.io/library/hello-world:latest: Resolving
docker.io/library/hello-world:latest: Resolved digest: sha256:...
719385e32844: Pulling config
719385e32844: Pull complete
c1ec31eb5944: Downloading [1/1]
c1ec31eb5944: Download complete
c1ec31eb5944: Pull complete
docker.io/library/hello-world:latest: Extracting layers
c1ec31eb5944: Extracting layer 1/1
c1ec31eb5944: Extracted (...)
docker.io/library/hello-world:latest: Digest: sha256:...
docker.io/library/hello-world:latest: Status: Downloaded newer image for docker.io/library/hello-world:latest
Image pulled: docker.io/library/hello-world:latest
Creating container...
Container created: abc123...
Starting container...
Waiting for container to exit...
Container exited with code: 0docker run --rm --network host ross-dev cli health# Pull an image
docker run --rm --network host ross-dev cli image pull alpine:latest
# List images
docker run --rm --network host ross-dev cli image list# Run a container
docker run --rm --network host ross-dev cli run alpine echo "Hello from Ross!"
# Run an interactive container with TTY
docker run --rm -it --network host ross-dev cli run -it alpine sh
# Run with options
docker run --rm --network host ross-dev cli run \
--name my-container \
--rm \
-e MY_VAR=value \
alpine sh -c 'echo $MY_VAR'
# List containers
docker run --rm --network host ross-dev cli container list --all# Build the Docker image
make build-image
# Or use the alias
make dev-buildmake dev-testmake dev-clippyGet a shell inside the container with access to the daemon:
make dev-shellThen you can run CLI commands directly:
ross-cli health
ross-cli run hello-worldross/
├── cli/ # Command-line interface (ross-cli)
├── container/ # Container management logic (ross-container)
├── core/ # gRPC protocol definitions (ross-core)
├── daemon/ # gRPC server (ross-daemon)
├── image/ # Image management logic (ross-image)
├── proto/ # Protocol buffer definitions
├── remote/ # Registry client (ross-remote)
├── shim/ # Container runtime shim (ross-shim)
├── snapshotter/ # Filesystem snapshots (ross-snapshotter)
└── store/ # Content-addressable storage (ross-store)
Ross follows a clean separation of concerns:
- Core services (
ross-container,ross-image) contain business logic with no transport dependencies - Shim (
ross-shim) wraps runc for low-level container operations - Snapshotter (
ross-snapshotter) manages overlay filesystem layers - Daemon (
ross-daemon) is a thin gRPC adapter layer - Storage (
ross-store) and registry (ross-remote) handle infrastructure concerns
See LICENSE for details.