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.

Host vs container on a single host

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.

Container backend

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

[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.

Image resolution

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.

Exec-env config

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.

[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.

Daemon access

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.

Kubernetes backend

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

[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.