Skip to content
ricochet

Execution Backend

ricochet runs content items in an execution backend. Three backends are supported:

Backend engine value Use when
Host (omitted) Content runs as a rootless OCI container.
Container container Single host with a Docker or Podman-compatible daemon. Content runs as a container spawned through the daemon.
Kubernetes k8s Multi-node cluster, content scheduled as Pods.

If [backend] is omitted, ricochet uses the host backend. Content runs as a rootless OCI-compatible container using the language interpreters installed on the host. This works on a fresh install without a container daemon or any other system dependency.

Both backends run content on the same machine as ricochet-server. The difference is how content is isolated and where the runtime environment comes from.

Dimension Host backend Container backend (container)
Isolation mechanism Namespace and cgroup with PID isolation OCI containers, spawned by the host’s Docker/Podman daemon
Daemon required No Yes (Docker, Podman, or compatible)
Interpreters Discovered on the host Defined by the execution environment
Observability Content is not visible to docker ps or container metrics tools Each app and task is a container visible to standard tooling
Setup cost None, works on a fresh ricochet-server install Install and run a container daemon, grant socket access

Use the host backend for deployments where the host already has the interpreters you need and you do not want to operate a container daemon.

Use the container backend when you want each running app and task to be an observable container.

Set engine = "container" to spawn content as containers via a local Docker- or Podman-compatible daemon.

ricochet-config.toml
[backend]
engine = "container"
default_image = "r-default"
exec_env_config_path = "ricochet-exec-env.toml"
content_path = "/var/lib/ricochet/data/content"
cache_path = "/var/lib/ricochet/data/.cache"
Field Required Description
engine yes Must be "container".
default_image no An image name from the ricochet-exec-env.toml to be used as a default when no exec-env is specified.
exec_env_config_path yes Path to the exec-env config TOML. Absolute, or relative to RICOCHET_HOME.
content_path yes Path that is bind-mounted into every spawned container. Must contain ricochet’s deployment bundles.
cache_path yes Path bind-mounted into every spawned container. Stores R, Julia, and Python package caches shared across content.
proxy_host no Hostname ricochet’s reverse proxy uses to reach spawned content containers. Defaults to localhost.

ricochet refuses to start if exec_env_config_path, content_path, or cache_path is missing.

default_image and per-content exec_env values are looked up in the exec-env config. For example, r-default resolves to a concrete image reference (docker.io/ricochetrs/r-alpine:4.5). If the value does not match an image name in the config, ricochet treats it as a full image reference and uses it as-is.

The exec-env config TOML maps image names to concrete container images and declares the language runtimes inside each image. Content items pick an image via their exec_env setting. ricochet falls back to default_image when none is set.

The example below references the official ricochet exec-env images. Adjust the image and tag, or substitute your own.

ricochet-exec-env.toml
[image.r-default]
image = "docker.io/ricochetrs/r-alpine:4.5"
os = "alpine-3.23"
arch = ["linux/amd64", "linux/arm64"]
description = "Default R 4.5 environment (Alpine)"
r = [
{ version = "4.5.3", bin = "/usr/bin/R" },
]
[image.r-44]
image = "docker.io/ricochetrs/r-alpine:4.4"
os = "alpine-3.23"
arch = ["linux/amd64", "linux/arm64"]
r = [
{ version = "4.4.3", bin = "/usr/bin/R" },
]
[image.python-default]
image = "docker.io/ricochetrs/python-ubuntu:3.13"
os = "ubuntu-26.04"
arch = ["linux/amd64", "linux/arm64"]
description = "Default Python 3.13 environment (Ubuntu)"
python = [
{ version = "3.13", bin = "/usr/local/bin/python3" },
]

The r, python, and julia arrays declare the interpreter versions present in the image and the path to their binaries. ricochet uses these to match a content item’s required version against an available runtime.

ricochet-server talks to the daemon over its local socket. The user running ricochet-server needs read and write access to that socket, typically by being a member of the docker group.

For multi-node clusters, use engine = "k8s". ricochet creates a Deployment per app and a Job per task using the cluster’s API.

ricochet-config.toml
[backend]
engine = "k8s"
namespace = "ricochet"
default_image = "r-default"
exec_env_config_path = "/etc/ricochet/exec-env.toml"
pvc_content_name = "ricochet-content"
pvc_cache_name = "ricochet-cache"
image_pull_policy = "IfNotPresent"

The same ricochet-exec-env.toml format applies, and the official exec-env images work unchanged as Pod images.

See Kubernetes installation for cluster prerequisites, Helm chart values, and PVC sizing guidance.