runc CLI localization is the practice of translating low-level OCI container runtime documentation without changing a bundle’s structure, its `config.json` keys, command arguments or security meaning. Translators working on `runc spec`, `runc run`, `runc create`, `runc start`, `runc state`, `runc exec` and lifecycle instructions must explain what each command changes while preserving exact identifiers. At this layer, an innocent-looking wording error can confuse a container’s configured root filesystem with a process that has actually started.
This guide to translating runc commands and OCI bundles is designed for international Linux engineers, security reviewers, documentation writers, educators and localization teams. runc implements a low-level container runtime interface based on the Open Container Initiative specifications. The project’s own documentation cautions that direct use is mainly for specialized purposes; higher-level tools such as Podman and Docker are generally more appropriate for everyday container management.
We begin with the bundle and runtime state model, then explain lifecycle, process control, rootless operation, security settings and multilingual quality checks. Examples are conceptual or use invented names unless specifically marked otherwise. Test against an approved Linux lab with the installed runc release, kernel configuration and organization permissions; never experiment with unreviewed mounts, privileged bundle settings or destructive operations on production systems.
- Main question: translate runc OCI runtime commands without changing the bundle or process lifecycle.
- Audience: Linux engineers, educators, localization specialists and security reviewers worldwide.
- Core distinctions: image versus bundle; rootfs versus state root; create versus start; configured state versus running process.
- Protect: `config.json` fields, command flags, paths, IDs, capabilities, UID mappings and signals.
- Safe learning: controlled lab only, version checks, security approvals and evidence-preserving diagnostics.
Begin with the OCI runtime model
Why runc is low-level
A typical container platform has several layers. An orchestrator or management CLI handles users’ desired workflows, a runtime service manages images and tasks, and an OCI runtime executes a container according to a bundle specification. runc is designed for the latter role rather than a general image registry or Compose workflow.
Translate “low-level runtime” as a scope boundary. Do not describe `runc run` as equivalent to a high-level `docker run` command with all networking, image-pull and lifecycle services magically supplied. The reader needs to know what must exist before runc can execute a bundle.
The OCI bundle model
An OCI runtime bundle typically contains a `config.json` file and a root filesystem tree, often under a directory named `rootfs`. The configuration describes process and runtime settings. The root filesystem is not itself the runc process or a downloaded image registry reference.
Keep filenames, directory names and JSON keys literal. Explain “bundle” in ordinary language as a prepared filesystem and configuration combination, while noting that its path and permissions matter. A translated instruction should never suggest changing the spelling of `config.json` to match the target language.
Prepared root filesystem versus image
runc does not simply interpret a registry tag as a complete runnable environment. Higher-level tooling may prepare the root filesystem from an image; runc then consumes the OCI bundle. This distinction is particularly important when translators reuse generic container tutorial language.
Preserve the difference between pulling an image, unpacking filesystem content and executing a configured process. If the source mentions an OCI image archive, do not automatically call it the bundle. Explain the source artifact separately from the runtime-ready directory.
The role of `runc spec`
The `runc spec` command can generate a starting OCI runtime configuration template. It is a template to inspect and adjust for a specific root filesystem and process, not a universally safe production specification. Its values may need deliberate changes before use.
Translate instructions about editing and reviewing the generated file without translating schema-defined JSON keys. Identify `runc spec` as preparation rather than container execution. A screenshot should not imply that generating a file proved the runtime started successfully.
Understanding `config.json`
An OCI configuration contains fields for process arguments, environment, working directory, root filesystem, mounts and Linux-specific settings. Such fields are machine-facing syntax. An editor who changes `process`, `root` or `mounts` into natural-language equivalents can invalidate the intended configuration.
Keep all keys and boolean values literal inside code. Translate the purpose of fields in a separate explanation. A reader should be able to distinguish a schema-defined key from a sample pathname or application argument that may be intentionally substituted in a lab.
The process argument array
The `process.args` array identifies what the runtime will execute inside the container. It differs from a prose instruction describing what the application should do. The order and exact characters of arguments can matter, especially for shell interpretation and executable paths.
Preserve argument order, array punctuation and quotation marks. Explain that `sh` or another program must exist within the prepared root filesystem. Do not promise that a command present on the host is necessarily available inside a minimal container.
Execution and state transitions
Terminal and foreground behavior
OCI bundles can specify terminal behavior, and runc’s execution mode interacts with that configuration. The project’s example for explicit `create` and `start` uses a nonterminal process in its simple demonstration. A translator should not collapse interactive and detached examples into one procedure.
Keep `terminal` and related booleans exact in JSON. Explain foreground attachment, background operation and process exit separately, referring to the documented example. Readers need to know whether a sample command can hold their terminal or finish immediately.
The convenience `runc run` path
`runc run` can handle creating and starting a container from a prepared bundle in one convenient operation. The project’s introductory explanation notes lifecycle handling around the running process. This is different from the separate `create` and `start` sequence used when a supervisor controls stages.
Translate “run” as the combined execution action without inferring that a registry image is downloaded. Preserve the container ID argument. Label examples as conceptual if the root filesystem, namespaces and security context were not actually tested.
Separate `create`, `start` and `delete`
The explicit lifecycle can create a container object, start the configured process, inspect its state and later delete the runtime container. These verbs are not interchangeable: create prepares state, start triggers execution and delete removes runtime state subject to preconditions.
Use separate translations for preparation, execution and cleanup. The reader should not treat a created state as “running”. If a source note says “delete after the process stops,” retain the condition rather than turning it into an unconditional command.
The meaning of `runc state`
A state query reports information about a selected runtime container. It can help determine whether it is created, running or stopped, but the returned data does not replace application-level readiness checks. Context such as the runtime root directory and container ID affects which state is queried.
Preserve state labels in raw JSON and explain them with carefully chosen local-language vocabulary. A running process can be unhealthy; a stopped runtime object does not reveal every reason for exit. Translate observation rather than infer root cause.
List containers and their IDs
`runc list` exposes runtime container records known to the selected runtime state root. Two separate invocations with different `–root` directories may show different sets, so empty output is not necessarily proof that a container never existed.
Keep IDs and filesystem paths literal. State which runtime state directory and user context were used if they matter to the diagnosis. Avoid conflating these records with a Kubernetes cluster inventory or a containerd namespace listing.
Root directory for runtime state
runc can use a runtime state root controlled through an option such as `–root`. This path governs where its runtime state is tracked, not the same thing as the root filesystem configured for the container process. The shared English word “root” can make these two roles easy to confuse.
Translate the two concepts separately: runc’s state storage root and the container’s filesystem root. Preserve literal paths. When demonstrating a rootless environment, explain why the state directory must be writable by the invoking user.
Security boundaries in an OCI bundle
Rootless operation and assumptions
runc supports rootless setups under appropriate Linux kernel and user namespace conditions. Its documentation demonstrates a `spec –rootless` template and a user-writable state root. Availability depends on host configuration, permitted mappings and other settings.
Do not translate rootless as “no security permissions needed” or “works on every machine.” Explain that a non-root invoking user still needs appropriate kernel and namespace support. Preserve the tested configuration and refrain from applying a privileged example universally.
User namespaces and UID mappings
User namespaces can map container-visible user identities to different host identities. A UID displayed as zero inside a container does not automatically mean it has unrestricted host root authority. The mappings and kernel settings determine what is allowed.
Use precise words for container user, host user and mapping rather than calling every ID an account name. Keep numeric UID and GID values literal inside a configuration. A translation should make the trust boundary clearer, not imply that the container has escaped host permission checks.
Mounts are security-relevant configuration
An OCI bundle may bind host paths or set mount points inside the root filesystem. Source and destination paths perform different roles, and read-only versus writable settings change the exposure. An incorrect translated example can inadvertently encourage mounting sensitive host data.
Distinguish host-side source path from container-side destination. Keep both literal in a runnable configuration and describe their relationship in prose. For public teaching, use invented safe directory paths and avoid showing privileged host mounts as routine defaults.
Linux namespaces in the runtime spec
PID, mount, network, IPC, UTS and user namespaces can isolate different aspects of the process environment. Their names have precise technical meanings, and not all environments use the same setup. A generic statement that a container is “fully isolated” can overstate what a configuration provides.
Translate each namespace type with a short functional explanation while preserving actual schema values. Avoid treating containerd namespaces, Kubernetes API Namespaces and Linux kernel namespaces as one concept. Each one selects or isolates something different.
Capabilities and security profile
Linux capabilities, seccomp filters and other security controls may be represented in the runtime configuration. A translated guide can become dangerous if it presents permission expansion as an innocent compatibility adjustment. Security settings should be reviewed by the team responsible for the host.
Keep capability names and profile identifiers literal. Explain what a setting affects without suggesting broad permissions as a universal fix for a failed sample. When a policy blocks an operation, treat that denial as a meaningful boundary rather than a nuisance to remove.
Cgroups and resource boundaries
Resource controls may apply to CPU, memory and process groups through cgroup-related configuration. A value in a spec is not the same as a real-time resource metric. Host kernel and cgroup setup determine what can be enforced, and the correct unit matters.
Translate limits, requests and measurements as different ideas. Preserve numeric formats and schema names. Avoid turning a resource error into a confident diagnosis without checking actual system evidence, current process state and configuration.
Multilingual verification and release
Execution with `runc exec`
`runc exec` can start an additional process within an existing runtime container, subject to the container’s state and the requested options. It is a process operation, not a read-only metadata query. An innocent diagnostic example can still execute code inside the environment.
Protect executable names, arguments and IDs. Explain that a shell may not be present and that the command can change files or expose data. Prefer approved disposable bundles and harmless demonstrations rather than experimenting with live services.
Signals, termination and delete
Runtime process control includes actions such as signaling and terminating execution. The difference between asking a process to stop and deleting runtime state matters for troubleshooting and evidence preservation. A translator should not use “clear” or “reset” as a vague substitute.
Keep signal names literal and distinguish stop requests, forced termination and cleanup according to the actual command and version. Label any irreversible or state-changing step before the code and require an authorized decision rather than assuming cleanup is always the next step.
Events, checkpoint and optional support
Some runtime capabilities and tooling around events or checkpoint-and-restore depend on build choices and external dependencies such as CRIU. A translated instruction should not claim every binary and host can perform those advanced operations simply because an upstream example exists.
Use clear qualifiers such as “when available and supported.” Record the tested version, platform and prerequisite. Keep option names and artifact filenames literal. A failed unsupported command is different from a mistranslation of its documentation.
OCI specification and runc versioning
runc implements behavior aligned with OCI runtime specifications, but versions and host integration details matter. The spec is the best conceptual authority for fields, while the installed binary and release notes explain actual CLI behavior and security fixes.
Translate explanatory descriptions rather than rewriting schema properties. Link to official sources and indicate when a statement is tied to a particular release. Technical readers should not be forced to guess whether a feature was tested or merely anticipated.
Unicode and bidirectional code safety
A right-to-left translation can visually reorder slashes, dashes, JSON punctuation and container IDs. Rich-text editing can also insert smart quotation marks or invisible direction controls. The underlying data may therefore change even when the code sample looks plausible.
Place machine-readable snippets in left-to-right code blocks, retain ASCII syntax and test copied bytes. Validate JSON after translation. Review narrow screens and screen-reader order, especially when code is embedded between Arabic, Hebrew or mixed-script prose.
Release with a security and language review
A credible runc article needs a technical reviewer who understands Linux permissions, OCI bundles and lifecycle transitions, plus a language reviewer who can verify clarity for beginners. Both should inspect the same approved snippets, not independent variants that drift over editing.
Record tool version, host type, tested configuration and whether sample values are fictional. Scan for secrets, internal paths and private system details. Separate raw records from translated interpretation, so the result remains both understandable and operationally traceable.
One reproducible learning sequence
Start with an approved, disposable Linux lab and an existing, reviewed OCI bundle. Identify its directory, `config.json` and root filesystem, then inspect the configured process arguments. If you regenerate a specification template, do not mistake the template itself for a running container. Record runc version, the current user and state-root context before attempting any runtime action.
In a separate reviewed demonstration, observe a container’s lifecycle. Discuss the difference between a combined run and an explicit create-then-start sequence, and use state observations to explain what has happened. Every container ID in the narrative must be traceable to the actual example; no identifier should be altered for grammatical flow.
Finally, invite a colleague working in another language to explain which file is machine-readable, which command starts execution, which result reports state and what permissions are required. If the reader confuses the root filesystem with runc’s state root, or assumes a generated spec proves that a process is running, revise the explanatory language before release.
Detailed scenarios for accurate low-level runtime translation
The bundle directory is mistaken for an image
A translated tutorial says “download the OCI bundle” when the source actually begins with a prepared root filesystem and a `config.json`. Readers may expect runc itself to pull a registry image and construct the directory. The distinction matters because a low-level runtime does not supply the same workflow as higher-level image tools.
Write two different sentences: “Obtain or prepare the filesystem using approved tooling” and “Run the prepared OCI bundle with runc.” This prevents the translation from assigning image-management responsibilities to the wrong layer. A reviewer should identify both required artifacts before attempting execution.
A translator renames `config.json`
In an effort to make a tutorial feel local, an editor changes the filename `config.json` to an equivalent phrase in the target language. The prose sounds friendly, but the runtime’s expected bundle structure no longer matches the example. This is a structural error rather than a stylistic choice.
Keep parser-defined filenames unchanged. Translate what the file does in an adjacent caption. Run a strict check that sample paths, braces, JSON keys and quotes remain exactly as approved, and do not let page formatting split the filename.
The process is configured but has never started
A configuration file contains `process.args` and a terminal setting, and the article declares that the application is running. The mere existence of those fields proves only that process execution was specified, not that runc has been invoked or that the process survived startup.
Distinguish configured intent, created state, running state and observed application behavior. A technical reviewer should be able to point to actual state evidence before a translated passage claims an application started successfully.
A template is treated as a production security profile
Generating a configuration through `runc spec` creates a starting template. If the translated guide says the file is ready for every production environment, readers may overlook mount paths, capabilities, namespace mappings and process assumptions that require review.
Call it a template or initial specification and require deliberate validation before execution. An appropriate learner exercise highlights fields that depend on the root filesystem and security environment, rather than inviting readers to accept one example uncritically.
An unmodified example assumes a shell
A simple introductory runc example may use a shell as its configured process. A different root filesystem might not contain that executable. If the command fails, the article should not diagnose runtime corruption solely from the inability to start a missing program.
Translate the dependency on the root filesystem clearly. Preserve literal process arguments and explain that the executable path is resolved within the prepared environment. Test with a disposable bundle whose contents are known.
Terminal configuration changes the result
A foreground session and a detached process do not offer the same interactive behavior. A source sample using `terminal: false` for a create/start demonstration should not be casually rewritten as an interactive terminal example without checking the execution mode.
Keep the `terminal` key and boolean value literal. Explain whether the operator should expect attached input and output or background execution. A reviewer should be able to identify what happens when the configured process exits.
The combined run versus explicit lifecycle
The project documentation distinguishes a convenient `run` path from a sequence that explicitly creates and starts the container. Translating both paths as “start” hides the fact that one may manage more lifecycle steps on behalf of the operator.
Use different explanations for preparing runtime state and beginning process execution. In an educational timeline, show the lifecycle as separate stages and mark cleanup as another action, not a synonym for the process ending.
A created state is called healthy
After `runc create`, an observer may see a created object without a running application process. A translation that describes this state as “successfully serving requests” overstates the evidence and may mislead another operator into skipping necessary checks.
State that the runtime object was created, then identify any later observation establishing whether the process started. Do not equate runtime state with health of an application that requires ports, files or external dependencies.
An old container ID is reused in a note
A learner records a container ID from a previous lab and accidentally substitutes it into a later state or cleanup example. The translated prose remains coherent but the command may address the wrong runtime object, particularly if several attempts use similar names.
Keep an ID-to-object register within a tutorial. Mark placeholders clearly and require a final comparison between each command and the earlier source listing. Do not invent runnable identifiers that appear to have been observed.
The runtime state root is confused with rootfs
A support note says “change the root” without identifying whether it refers to the OCI root filesystem or runc’s runtime state directory selected by `–root`. These are unrelated roles, and mistakes can explain why a container is not visible to a later command.
Use two qualified expressions: “bundle root filesystem” and “runc state root.” Preserve both actual paths, and ask a novice to point to the directory containing `config.json` versus the place where runc tracks runtime state.
Rootless is mistaken for permission-free
A non-root user runs a rootless configuration and the translated guide says no host capabilities or policy checks matter. In reality, rootless execution depends on user namespaces and host settings, and some operations may remain restricted.
Translate rootless as execution without invoking runc as host root under defined prerequisites, not exemption from Linux security. State which kernel and mapping conditions are assumed, and avoid promising identical results on every distribution.
UID zero inside a container
A process appears as UID zero inside a user namespace but may map to a non-root identity on the host. A translation calling it “full administrator of the computer” misrepresents the boundary and can confuse security education.
Describe container-visible and host-visible identities separately. Keep numeric UIDs and mappings unchanged in code. A reviewer should explain how namespace mappings change the meaning of an apparent root identity.
Security incidents, language traps and review exercises
Mount source and destination reversed
A bind mount can expose a host directory at a specified path inside a container. If the translator reverses source and destination, the resulting explanation describes a different filesystem relationship and may even suggest dangerous access to sensitive host data.
Label both sides of the mapping and state which one belongs to the host. Preserve exact paths and read-only flags. Use deliberately fictional directories in public examples and never encourage privileged host mounts simply to make a tutorial demonstrate success.
The security capability name is localized
Linux capabilities use defined token names. A local-language translation of a capability string inside an OCI spec may invalidate the configuration or misidentify the privilege. This illustrates why fluent translation cannot enter a machine-enforced security field.
Keep capability constants and seccomp-related keys untouched. Provide translated definitions and security implications separately. Ask security reviewers whether a sample adds privileges that are unnecessary for the educational task.
An error is “fixed” by removing restrictions
Suppose a bundle fails because a host security policy blocks an action. A bad translated troubleshooting note recommends removing seccomp filtering or broadening capabilities as the routine solution. That would erase the security boundary without establishing the required application behavior.
Translate a denial accurately as a policy or permission finding. The next step is to review intended behavior and authorized policy with the system owner, not to weaken safeguards indiscriminately.
Cgroup measurements and limits are mixed
A configuration may contain memory or CPU constraints, while a monitoring tool reports current usage. A translation that confuses the configured limit with measured consumption can lead teams to diagnose resource exhaustion without supporting evidence.
Keep units and numeric values exact. Explain configuration, enforcement and observed usage as different layers. A careful case study compares the set limit with appropriate runtime measurements rather than drawing conclusions from one number.
An exec command is mistaken for inspection
`runc exec` can launch an additional process in an existing container. A caption that says “look inside without changing anything” is not generally accurate. Even diagnostic executables can write files, alter cache state or expose credentials.
Distinguish metadata inspection from process execution and mark the command’s operational effect. An authorized lab should use a harmless, understood executable; a published example should never presume that running arbitrary code is risk-free.
A stop request and deletion collapse into one verb
Stopping a process and deleting its runtime state are different operations. A translated runbook that uses the same local word for both can cause evidence loss or unexpected service interruption, particularly when the operator reads only the imperative line.
Use precise action labels and clearly separate proposed commands. Identify what can be observed before each state change, what approvals are needed and which artifacts could become unavailable afterward.
An advanced checkpoint feature is presumed universal
Checkpoint-and-restore can depend on external tooling and specific build or host capabilities. A translator who sees a checkpoint example may present it as a standard feature on every runc installation, resulting in broken exercises and inaccurate support expectations.
Use “where supported” and list prerequisites. Preserve command syntax and artifact identities while referring to the tested version. Differentiate feature unavailability from an invalid translated option.
JSON punctuation changes during editorial cleanup
A localized code block may receive curly quotes, full-width colons or a translated `true` value. These small visual substitutions can break JSON parsing even though the surrounding text is easier to read. The error is particularly common when copying snippets through presentation software.
Freeze machine-readable blocks and validate them with a JSON parser. Let editors translate the labels and captions rather than the syntax. Test copy-paste from the final published page, because layout software can reintroduce changes after a pre-publication review.
Arabic prose around a long path
Right-to-left layout can make a slash-separated path or a command with flags appear in a confusing order. An engineer may copy an invisible bidirectional control mark along with executable text. Such a command is no longer identical to the approved source.
Use left-to-right code isolation, preserve simple ASCII punctuation and compare the copied bytes. Have a reader using a screen reader explain the sequence of options, not just what the visual code appears to say.
Secrets included in process environment
A runtime configuration or diagnostic capture may contain environment variables, internal mounts, sensitive paths or bearer tokens. An international translation team must not paste raw operational data into a public article solely to make the example realistic.
Use synthetic, consistent values and redact both screenshots and transcribed text. Review alt attributes, page metadata and sample URLs for secrets. Keep confidential source material in the authorized workflow and publish only sanitized educational examples.
A timeline is inferred from state alone
A state observation taken at one instant does not prove precisely when a process started, why it stopped or what happened between two captures. Translators often supply missing connecting verbs to make an article flow, accidentally inventing events.
Preserve snapshot times and distinguish observed states from chronology that needs logs or further evidence. A clear report can say “the recorded state differed between captures” without claiming an unobserved restart sequence.
Preparing the final independent handover
A useful multilingual handover states the bundle directory, state root, runc version, container ID, relevant spec fields, observed lifecycle state and known limitations. A reader should not need the original engineer’s unwritten assumptions to understand the result.
Ask an OCI reviewer to audit technical accuracy and a new language reader to explain each action and its consequences. Any disagreement about what command runs, changes or deletes is a reason to revise before publishing.
Frequently asked questions
Does runc download container images?
Not as a high-level registry workflow. runc executes an OCI runtime bundle containing a configuration and prepared root filesystem. Other tools commonly prepare the image contents and bundle.
What must an OCI bundle contain?
A typical bundle contains `config.json` and a prepared root filesystem. The specification defines structure and fields; the runtime version and host platform affect execution behavior.
Does `runc spec` launch a container?
No. It generates an initial runtime configuration template. The file must be reviewed for process, mounts, namespaces, privileges and environment before it is used.
What is the difference between create and start?
Create prepares runtime container state; start begins execution of its configured process. A created container is not equivalent to a running application.
Is rootless universally available?
No. It depends on Linux user namespace support and host mappings and configuration. Keep rootless examples versioned and test them in an approved environment.
Can the source and destination of a mount be translated?
Their meaning can be explained, but actual filesystem path tokens in runnable code must remain literal. Reversing them changes the mount relationship.
Why not describe `exec` as read-only?
It launches an additional process, which can read sensitive data or change state depending on the executable and privileges. It is not automatically a passive inspection command.
Should I translate JSON field names?
No. Parser-defined keys, booleans and punctuation must stay exact. A separate local-language explanation can describe what each field controls.
How should I handle an unsupported command?
Confirm the installed runc release, host prerequisites and relevant help. An unavailable feature is not necessarily evidence of translation error or runtime corruption.
What makes this translation publishable?
Independent security and technical checks, accurate lifecycle terminology, validated JSON and code-copy behavior, redacted values, accessible examples and clearly stated limits on what observed state proves.
Upstream references
Use the official runc repository and documentation for current CLI behavior and the OCI runtime specification for bundle fields and process semantics. Higher-level container workflows are addressed separately by Podman localization and containerd ctr localization.