OCIFBSD(8) FreeBSD System Manager's Manual OCIFBSD(8)

ocifbsd — FreeBSD native OCI runtime

ocifbsd [-vhV] command [arguments]

ocifbsd is a FreeBSD-native OCI (Open Container Initiative) runtime. It maps OCI bundles to jail(8) parameters, manages container lifecycle state under /var/run/ocifbsd, and applies host-side mounts (nullfs, devfs, procfs, tmpfs, fdescfs) into the container rootfs on start.

The following commands are available:

[-n name] bundle
Create a container from an OCI bundle. The jail is created with persist so it remains until start or delete. Prints the 64-hex container id on stdout. If the bundle or image configuration does not specify a hostname, the container's hostname defaults to its name (or, absent a name, its id) so sysctl(8) kern.hostname inside the jail is never empty.
container-id
Start a created container (attach init process, apply mounts).
container-id [-s signal]
Send a signal to the container init process. Default is SIGTERM. Idempotent for already-stopped or never-started containers.
container-id [-f]
Delete a container and unmount applied mounts. Use -f to force deletion of a running container.
container-id
Show the current state of a container. The reported state is reconciled against the live jail: a container recorded as running or paused whose jail no longer exists (for example after a host reboot or an external jail(8) removal) is reported as stopped.
List known containers from the state directory. As with state, each container's status reflects actual jail liveness rather than only the last value written to the state file.
container-id
Show detailed container metadata as JSON.
[-n name] bundle
Create and start a container in one command.
[-n | --dry-run] reference
Parse an OCI image reference and print registry, repository, tag, and store path (default /var/lib/ocifbsd, overridable with OCIFBSD_DATA_DIR). With -n only resolve and print. Without -n, fetch the manifest and layers via the OCI Distribution API into that path.
[-n reference] archive
Import a local OCI image into the image store. archive may be a directory in OCI image-layout form (oci-layout, index.json, blobs/) or a .tar, .tar.gz, or .tar.xz archive of that layout, such as the container images published at https://download.freebsd.org/releases/OCI-IMAGES/. The image layers are verified against their manifest digests and unpacked into a rootfs, and a runtime config.json is generated from the image configuration, so the result can be run with create --image or run --image. With -n the store entry is named by the given reference instead of the archive's org.opencontainers.image.ref.name annotation.
List top-level entries under the local image store (/var/lib/ocifbsd). An empty or missing store is not an error.
list [container]
Show the network configuration (VNET, IPv4/IPv6 addresses, gateways, and DNS servers) of one container, or of every container when no argument is given. Requires view privilege (root or the ocifbsd group).
set container [options]
Modify a container's persisted network configuration. Options accumulate onto the existing configuration:
on|off
Enable or disable VNET (network stack isolation).
cidr, --ip6 cidr
Add an IPv4 or IPv6 address in CIDR form (addr/prefix); may be repeated.
addr, --gateway6 addr
Set the default IPv4 or IPv6 gateway.
addr
Add a DNS nameserver; may be repeated.
, --clear-ip4, --clear-ip6, --clear-dns
Remove all, or a specific class of, address/DNS entries.
Every value is validated before being stored; an invalid address is rejected and the configuration is left unchanged. The configuration is written to /var/lib/ocifbsd/networks/⟨id⟩.json with mode 0640, group-owned by the ocifbsd group. Requires modify privilege (root or the ocifbsd group).

Runtime state under /var/run/ocifbsd and generated config.json files are created mode 0750/0640 and group-owned by the ocifbsd administrative group when it exists, so that only root and members of that group can view or modify container configuration. When the group does not exist, access is restricted to root only. The network subcommands additionally enforce this policy in-process: viewing requires membership in that set, and modifying requires it as well.

Global options (before the command):

, --verbose
Enable verbose output.
, --pretty
Pretty-print JSON output with indentation for the commands that emit JSON (inspect, state). This is the default; the flag is accepted for explicitness.
, --compact
Print JSON as a single compact line instead of the pretty-printed default, for scripts and pipelines.
, --help
Show help message and exit.
, --version
Show version information and exit.

Subcommand options:

name, -name name
Human-readable name for create and run (also used in jail naming).
signal, -signal signal
Signal for kill (number or name).
, --force
Force delete of a running container.

Create a container from an OCI bundle:

ocifbsd create --name my-container /path/to/bundle

Start, inspect state, signal, and delete:

ocifbsd start <id>
ocifbsd state <id>
ocifbsd kill <id>
ocifbsd delete --force <id>

Create and run in one command:

ocifbsd run --name web /path/to/bundle

/var/run/ocifbsd/
Runtime state directory (per-container JSON)
/var/lib/ocifbsd/
Image and volume data directory (future image store)
/var/lib/ocifbsd/networks/
Per-container network configuration (network set)
/etc/ocifbsd/
Configuration directory (reserved)

Override the image and volume data directory (default /var/lib/ocifbsd).
Override the runtime state directory (default /var/run/ocifbsd), useful for tests or an unprivileged, self-contained instance.

jail(8), jail(3), mount(8), rctl(8)

ocifbsd was developed to provide native OCI runtime support for FreeBSD. Phase 1 acceptance covers create/start/state/kill/delete with ATF unit and root integration tests on FreeBSD lab hosts.

ocifbsd was developed by Klara, Inc. under sponsorship from the FreeBSD Foundation, with REVYTECH, Inc. lifecycle and test work on feature/oci-bootstrap.

FreeBSD 15.1-STABLE July 22, 2026 OCIFBSD(8)