delonix run

Usage: delonix run [OPTIONS] <IMAGE> [COMMAND]...

Arguments:
  <IMAGE>
          Image (e.g. `alpine:3.19`)

  [COMMAND]...
          Command + arguments (default: the image's ENTRYPOINT/CMD)

Options:
  -d, --detach
          Run in the background and print the ID

      --name <NAME>
          Container name (default: `dlx-<id>`)

      --hostname <HOSTNAME>
          Hostname inside the container (UTS namespace + `/etc/hostname`). Default: the container name (docker `--hostname`)

  -u, --user <USER>
          Run the process as this user: `uid[:gid]` or `name[:group]` (docker `--user`). Names are resolved in the image's `/etc/passwd`/`/etc/group`

      --net <NET>
          Network: `host` (shares the host's, default), `none` (isolated netns with no connectivity), or the NAME of a network created with `delonix network create`
          
          [default: host]

      --namespace <NAMESPACE>
          Logical ISOLATION namespace (default `default`). Containers in different namespaces cannot reach each other (even on the same network); only a `kind: Dependency` crosses the boundary

      --expose <EXPOSE>
          Auto-register this container's HTTP port in the L7 proxy under its internal FQDN `<name>.<namespace>.delonix.internal` (reachable via the proxy). Needs `--net <network>`. Removed automatically on `container rm`

  -v, --volume <VOLUMES>
          Volume/bind mount, `name:/target[:ro]` or `/host:/target[:ro]`. Repeatable

  -p, --publish <PUBLISH>
          Publish a port, `[hostIp:]hostPort:contPort[/tcp|udp]` or just `port`. Repeatable. SAFE BY DEFAULT: without `hostIp` the port binds to `127.0.0.1` only — reachable from the host itself, NOT from a browser on another machine. Name the address to widen it: `0.0.0.0:8080:80` (every interface), `192.168.1.10:8080:80` (one), or the libvirt gateway to reach it from VMs (see `delonix vm reach`). With `--net host` (the default) the container moves to its own netns with userspace NAT (slirp4netns, like rootless podman); with `--net <network>` it publishes via the ingress (nft DNAT + hostfwd on the single slirp)

      --privileged
          Privileged container (all caps, seccomp off) — trusted workloads

      --entrypoint <ENTRYPOINT>
          Override the image's ENTRYPOINT (COMMAND becomes the arguments to this binary; `--entrypoint ""` clears it and runs just the COMMAND)

  -w, --workdir <WORKDIR>
          Working directory the container's process starts in (default: the image's own configured workdir, or `/`). Persists in the record — an `exec -w` overrides it for that one call only

      --rm
          Remove the container when the process exits (with `-d`, a detached watcher handles removal when the container dies)

      --restart <RESTART>
          Restart policy (only with `-d`): `no` (default), `on-failure[:max]`, `always`, `unless-stopped`. A detached supervisor (one per container, ephemeral — there's no daemon) becomes the container's parent, captures the real exit code, and restarts it according to the policy
          
          [default: no]

      --device <DEVICES>
          Attach a host device, `/dev/x[:/dev/y]`. Repeatable. The container's `/dev` is a tmpfs with a curated list (null/zero/tty/...); this adds real host nodes to it, like `docker --device`

  -e, --env <ENV>
          Additional environment variables (`KEY=VAL`), repeatable

      --label <LABELS>
          Label (`KEY=VAL`), repeatable — e.g. `io.x-k8s.kind.role=control-plane` enables the dedicated cgroup2 delegation for Kind nodes (see `setup_node_cgroup_ns`)

  -m, --memory <MEMORY>
          Memory limit (`64M`, `2G`, `max`). Default: a quarter of the engine's budget (`DELONIX_DEFAULT_PCT`); `max` lifts the cap entirely

  -c, --cpus <CPUS>
          CPU quota (number of cores, e.g. `0.5`, `2`). Default: the lesser of 1.0 and a quarter of the engine's budget

      --cpu-weight <CPU_WEIGHT>
          Relative CPU weight (`cpu.weight`, 1–10000) under contention

      --cpuset <CPUSET>
          CPUs the container is pinned to (`cpuset.cpus`, e.g. `0-3`, `0,2`)

      --io-weight <IO_WEIGHT>
          Relative I/O weight (`io.weight`, 1–10000)

      --device-read-bps <DEVICE_READ_BPS>
          Absolute read limit from the store's disk (`10mb`, `1g`). Docker's `--device-read-bps`

      --device-write-bps <DEVICE_WRITE_BPS>
          Absolute write limit to the store's disk (`10mb`, `1g`). Docker's `--device-write-bps`

      --device-read-iops <DEVICE_READ_IOPS>
          Absolute read IOPS limit from the store's disk

      --device-write-iops <DEVICE_WRITE_IOPS>
          Absolute write IOPS limit to the store's disk

      --read-only
          Read-only rootfs (writes go to tmpfs/volumes)

      --cap-add <CAP_ADD>
          Add a capability (e.g. `NET_ADMIN`). Repeatable

      --cap-drop <CAP_DROP>
          Drop a capability. Repeatable

      --allow-source <PREFIX>
          Let this container send from a source prefix besides its own address, for a container that routes (`a.b.c.d/len`, repeatable). Only inside a prefix the node policy grants (`allowedSourcePrefixes`); every use is logged

      --no-source-check
          Switch anti-spoofing off for this container. Exceptional: only when the node policy grants it (`allowSourceCheckOptOut`); every use is logged

      --security-opt <SECURITY_OPT>
          Security options (docker-style), repeatable: `seccomp=unconfined` | `seccomp=<profile.json>` (OCI/runc format) | `apparmor=<profile>` | `no-new-privileges[=true|false]` (default true, stricter than docker/podman)

      --apparmor <APPARMOR>
          AppArmor profile to apply (`unconfined`, `delonix-default`, or an already-loaded name). `delonix-default` is loaded automatically

      --selinux <SELINUX>
          SELinux context/profile to apply

      --userns
          User namespace: enables the subuid mapping (default in rootless)

      --no-userns
          Disable the automatic activation of the user namespace

      --host-pid
          Share the host's PID namespace (`--pid host`)

      --host-ipc
          Share the host's IPC namespace

      --detect
          Detection mode: seccomp in log mode (doesn't block), to discover syscalls

      --secret <SECRET>
          Inject a secret from the vault (`name`), as an environment variable. Repeatable. With `--secret-files`, it goes to `/run/secrets/<name>`

      --secret-files
          The `--secret`s come in as files in `/run/secrets/` (tmpfs), not env

      --env-file <ENV_FILE>
          Load variables from a `.env` file (`KEY=VAL` per line). Repeatable

      --tmpfs <TMPFS>
          Mount a tmpfs (`/path[:options]`). Repeatable

      --ulimit <ULIMIT>
          Ulimit (`nofile=1024:2048`). Repeatable

      --dns <DNS>
          DNS server for the container's `/etc/resolv.conf`. Repeatable. Overrides the resolver the engine would pick (network gateway, slirp, or the host's copy)

      --dns-search <DNS_SEARCH>
          DNS search domain. Repeatable

      --dns-option <DNS_OPTION>
          `resolv.conf` option (`ndots:2`, `timeout:1`). Repeatable

      --group-add <GROUP_ADD>
          Supplementary group id for the process (`--group-add 1234`). Repeatable. Applied even when the container runs as root — a root process still needs a group to reach a mounted share

      --masked-path <MASKED_PATH>
          Make a path unreadable inside the container (`--masked-path /proc/kcore`). Repeatable. A file is covered with `/dev/null`, a directory with an empty read-only tmpfs

      --readonly-path <READONLY_PATH>
          Remount a path read-only inside the container (`--readonly-path /proc/sys`). Repeatable

      --sysctl <SYSCTL>
          Container sysctl (`net.core.somaxconn=1024`). Repeatable

      --gpus <GPUS>
          Expose GPUs: `all` | `nvidia` | `dri` (expands to the `/dev` nodes)

      --ip <IP>
          Fixed IP on the network (`--net <network>`), e.g. `10.89.0.10`

      --network-alias <NETWORK_ALIAS>
          The container's DNS alias on the network. Repeatable

      --add-host <ADD_HOST>
          Extra `/etc/hosts` entry, `name:ip` (as Docker/Podman). Repeatable. PERSISTED: survives `stop`/`start` and `restart`, which rewrite `/etc/hosts` from scratch

      --wait
          With `-d`, block until the image's `HEALTHCHECK` passes (or the timeout elapses). Replaces the `until curl ...; do sleep; done` that every script ends up writing. No `HEALTHCHECK` in the image is a clear error, never a silent instant return

      --wait-timeout <WAIT_TIMEOUT>
          How long `--wait` waits before giving up (seconds)
          
          [default: 60]

      --health-cmd <HEALTH_CMD>
          Probe command, run with `/bin/sh -c` inside the container. Without it, the image's own `HEALTHCHECK` is monitored; any other `--health-*` flag turns monitoring on for an image that has one

      --health-interval <HEALTH_INTERVAL>
          Seconds between probes
          
          [default: 30]

      --health-timeout <HEALTH_TIMEOUT>
          A probe that runs longer than this counts as a failure. The probe kills ITSELF (the wrapper is `sh`), so nothing is left stuck inside the container
          
          [default: 30]

      --health-retries <HEALTH_RETRIES>
          Consecutive failures before the container is `unhealthy`
          
          [default: 3]

      --health-start-period <HEALTH_START_PERIOD>
          Grace at startup: failures inside this window do not count, and the container reads `starting` rather than `unhealthy`
          
          [default: 0]

      --knows <KNOWS>
          Restrict DNS resolution to these containers (isolation). Repeatable

      --knows-none
          The container resolves NO other container by name

      --pod <POD>
          Join a pod's netns (`--net <network>`), sharing IP/ports

      --net-bps <NET_BPS>
          Egress bandwidth cap (`10mbit`, `512kbit`). Only with `--net <network>`

      --net-burst <NET_BURST>
          Burst for the bandwidth cap. Only with `--net-bps`

      --log-driver <LOG_DRIVER>
          Log driver (`json`, `cri`, ...)

      --log-file <LOG_FILE>
          Log file path (overrides the default)

      --log-cri
          CRI format in the log file (for the kubelet/`crictl logs`)

  -h, --help
          Print help (see a summary with '-h')

EXAMPLES:
  # detached, published on the host, with a name of your own
  delonix run -d -p 8080:80 --name web nginx

  # a database with a named volume and a network of its own, so the data
  # outlives the container
  delonix run -d --net app -v pgdata:/var/lib/postgresql/data -e POSTGRES_PASSWORD=dev postgres:16

  # in the foreground, removed on exit — the shape for a one-off task
  delonix run --rm alpine echo hello

  # with a memory and CPU cap, and a restart policy
  delonix run -d -m 512M --cpus 1.5 --restart on-failure nginx

SEE ALSO:
  delonix ps · delonix logs · delonix stop · delonix container run

  delonix › run