CH-RUN-OCI(1)

📦
version 0.44 · 10 versions
, in ubuntu stonking

🎀 CH-RUN-OCI — the OCI wrapper for ch-run 💖

bestie. sit down. we're talking about ch-run-oci, a Charliecloud page, and it's a whole vibe. it's giving "glorified translator between two worlds that don't really get each other." let's go ✨

📛 NAME

ch-run-oci — OCI wrapper for ch-run, no notes 💅

🌸 SYNOPSIS

$ ch-run-oci OPERATION [ARG ...]

that's it. that's the whole surface. one operation, some args, and a lot of scaffolding behind the curtain 🦋

💜 DESCRIPTION

⚠️ Note: this command is experimental, okay? Features may be incomplete and/or buggy. The quality of the code is not yet up to the usual Charliecloud standards, and error handling is poor. Please report any issues you find so we can fix them! 🫶

So like, ch-run-oci is an Open Containers Initiative (OCI) wrapper for ch-run(1). And lowkey you probably do not want to run this command directly — it exists to interface with other software that expects an OCI runtime. The current goal is to support completely unprivileged image building (think buildah --runtime=ch-run-oci) rather than general OCI container running. Completely different eras, honestly.

Support of the OCI runtime specification is only partial. Two reasons, bestie:

  1. It's an experimental and incomplete feature. (We said it.)
  2. More importantly, the philosophy and goals of OCI differ significantly from those of Charliecloud. The way that these two think about the world is just... not the same.

Key differences, because you deserve to know:

  • OCI is designed to run services, while Charliecloud is designed to run scientific applications.
  • OCI containers are persistent things with a complex lifecycle, while Charliecloud containers are simply UNIX processes.
  • OCI expects support for a variety of namespaces, while Charliecloud supports user and mount, no more and no less. periodt.
  • OCI expects runtimes to maintain a supervisor process in addition to user processes; Charliecloud has no need for this. not the vibe.
  • OCI expects runtimes to maintain state throughout the container lifecycle in a location independent from the caller.

For these reasons, ch-run-oci is a bit of a kludge, and much of what it does is provide scaffolding to satisfy OCI requirements. iconic behavior honestly 😭

Which OCI features are and are not supported is laid out in the rest of this man page, and the technical analysis and discussion live in the Contributor's Guide.

Also babes, this command supports OCI version 1.0.0 only and fails with an error if other versions are offered. no cap. 🚫

🔥 OPERATIONS

All OCI operations are accepted, but some are no-ops or merely scaffolding to satisfy the caller. For comparison, see also:

🧚 create

$ ch-run-oci create --bundle DIR --pid-file FILE [--no-new-keyring] CONTAINER_ID

Create a container. Charliecloud doesn't have separate create and start phases — it's all one moment, main character energy — so this operation only sets up OCI-related scaffolding.

Arguments:

  • --bundle DIR — Directory containing the OCI bundle. This must be /tmp/buildahYYY, where YYY matches CONTAINER_ID below. (yes, they have to match. it's a whole thing.)
  • --pid-file FILE — Filename to write the "container" process PID to. Note that for Charliecloud, the process given is fake; see above. This must be DIR/pid, where DIR is given by --bundle.
  • --no-new-keyring — Ignored. (Charliecloud does not implement session keyrings.) 🙈
  • CONTAINER_ID — String to use as the container ID. This must be buildah-buildahYYY, where YYY matches DIR above.

Unsupported arguments:

  • --console-socket PATH — UNIX socket to pass pseudoterminal file descriptor. Charliecloud does not support pseudoterminals; fail with an error if this argument is given. For Buildah, redirect its input from /dev/null to prevent it from requesting a pseudoterminal. 💀

🦋 delete

$ ch-run-oci delete CONTAINER_ID

Clean up the OCI-related scaffolding for the specified container. it's the cleanup era, we love a tidy queen ✨

💀 kill

$ ch-run-oci kill CONTAINER_ID

No-op. that's it. that's the whole thing. 😭

⭐ start

$ ch-run-oci start CONTAINER_ID

Execute the user command specified at create time in a Charliecloud container. (this is the actual moment, btw 🔥)

👑

$ ch-run-oci state CONTAINER_ID

Print the state of the given container on standard output as an OCI compliant JSON document. pretty princess JSON 💅

🚫 UNSUPPORTED OCI FEATURES

As noted above, various OCI features are not supported by Charliecloud. We have tried to guess which features would be essential to callers; ch-run-oci fails with an error if these are requested. Otherwise, the request is simply ignored — like, not even a text back.

We are interested in hearing about scientific-computing use cases for unsupported features, so we can add support for things that are needed. genuinely, tell us 🫶

Our goal is for this man page to be comprehensive: every OCI runtime feature should either work or be listed as unsupported. no gaps, bestie.

Unsupported features that are an error:

  • Pseudoterminals
  • Hooks (prestart, poststart, and prestop)
  • Annotations
  • Joining existing namespaces
  • Intel Resource Director Technology (RDT)

Unsupported features that are ignored:

  • Mounts other than the root filesystem
  • User/group mappings beyond one user mapped to EUID and one group mapped to EGID
  • Disabling prctl(PR_SET_NO_NEW_PRIVS)
  • Root filesystem propagation mode
  • sysctl directives
  • masked and read-only paths (remaining unprivileged protects you)
  • Capabilities
  • rlimits
  • Devices (all devices are inherited from the host)
  • cgroups
  • seccomp
  • SELinux
  • AppArmor
  • Container hostname setting

🌈 ENVIRONMENT VARIABLES

  • CH_LOG_FILE — If set, append log chatter to this file, rather than standard error. This is useful for debugging situations where standard error is consumed or lost. Also sets verbose mode if not already set (equivalent to --verbose).
  • CH_LOG_FESTOON — If set, prepend PID and timestamp to logged chatter. 🎀
  • CH_XATTRS — If set, save xattrs in the build cache and restore them when rebuilding from the cache (equivalent to --xattrs).
  • CH_RUN_OCI_HANG — If set to the name of a command (e.g., create), sleep indefinitely when that command is invoked. The purpose here is to halt a build so it can be examined and debugged. (yes, it's literally designed to hang. on purpose. a feature.) 🧚

🐛 REPORTING BUGS

If Charliecloud was obtained from your Linux distribution, use your distribution's bug reporting procedures.

Otherwise, report bugs to: <https://github.com/hpc/charliecloud/issues> — go off, tell us everything 💌

👀 SEE ALSO

contributors to the Charliecloud project, which has been established as "Charliecloud a Series of LF Projects, LLC". For web site terms of use, trademark policy, and related information, please see: <https://lfprojects.org>.

okay that's the whole page bestie, you ate it, you understood it, slay 💅✨ this was version 0.44, dated 2026-05-31 07:53 UTC — go forth and go build some images, unprivileged and iconic. 🫶🌸

📦 where this page comes from