NAME

       toolbox-create - Create a new toolbox container

SYNOPSIS

       toolbox create [--authfile AUTHFILE]
                      [--distro DISTRO | -d DISTRO]
                      [--image NAME | -i NAME]
                      [--release RELEASE | -r RELEASE]
                      [CONTAINER]

DESCRIPTION

       Creates  a  new  toolbox container. You can then use the toolbox enter command to interact
       with the container at any point.

       A toolbox container is an OCI container created from an OCI image. On Fedora, the  default
       image  is  known  as fedora-toolbox:N, where N is the release of the host. If the image is
       not  present  locally,   then   it   is   pulled   from   a   well-known   registry   like
       registry.fedoraproject.org.  Other  images may be used on other host operating systems. If
       the host is not recognized, then the Fedora image will be used.

       The container is created with podman create, and its entry point is set to  toolbox  init-
       container.

       By default, a toolbox container is named after its corresponding image. If the image had a
       tag, then the tag is included in the name of  the  container,  but  it's  separated  by  a
       hyphen, not a colon. A different name can be assigned by using the CONTAINER argument.

   Container Configuration
       A  toolbox  container  seamlessly  integrates  with  the  rest  of the operating system by
       providing access to the user's home directory, the Wayland  and  X11  sockets,  networking
       (including Avahi), removable devices (like USB sticks), systemd journal, SSH agent, D-Bus,
       ulimits, /dev and the udev database, etc..

       The user ID and account details from the host is propagated into  the  toolbox  container,
       SELinux  label  separation  is  disabled,  and the host file system can be accessed by the
       container at /run/host. The container has access to the host's Kerberos credentials  cache
       if it's configured to use KCM caches.

       A  toolbox  container  can be identified by the com.github.containers.toolbox label or the
       /run/.toolboxenv file.

       The entry point of a toolbox container is the toolbox init-container command which plays a
       role in setting up the container, along with the options passed to podman create.

   Entry Point
       A  key  feature  of  toolbox  containers  is their entry point, the toolbox init-container
       command.

       OCI containers are inherently  immutable.  Configuration  options  passed  through  podman
       create  are  baked  into  the definition of the OCI container, and can't be changed later.
       This means that changes and improvements made  in  newer  versions  of  Toolbox  can't  be
       applied  to  pre-existing toolbox containers created by older versions of Toolbox. This is
       avoided by using the entry point to configure the container at runtime.

       The entry point of a toolbox container customizes the container to fit the current user by
       ensuring  that it has a user that matches the one on the host, and grants it sudo and root
       access.

       Crucial  configuration  files,  such  as   /etc/host.conf,   /etc/hosts,   /etc/localtime,
       /etc/resolv.conf  and  /etc/timezone,  inside the container are kept synchronized with the
       host. The entry point also bind mounts various subsets of the host's filesystem  hierarchy
       to their corresponding locations inside the container to provide seamless integration with
       the   host.   This   includes    /run/libvirt,    /run/systemd/journal,    /run/udev/data,
       /var/lib/libvirt, /var/lib/systemd/coredump, /var/log/journal and others.

       On  some  host  operating systems, important paths like /home, /media or /mnt are symbolic
       links to other locations. The entry point ensures that paths inside  the  container  match
       those on the host, to avoid needless confusion.

OPTIONS

       --authfile FILE

       Path to a FILE with credentials for authenticating to the registry for private images. The
       FILE is usually set using podman login, and will be used by podman pull to get the image.

       The default location for FILE is $XDG_RUNTIME_DIR/containers/auth.json and its  format  is
       specified in containers-auth.json(5).

       --distro DISTRO, -d DISTRO

       Create  a  toolbox container for a different operating system DISTRO than the host. Cannot
       be used with --image. Has to be coupled with --release unless the selected DISTRO  matches
       the host.

       --image NAME, -i NAME

       Change  the  NAME  of  the  image used to create the toolbox container. This is useful for
       creating containers from custom-built images. Cannot be used with --distro and --release.

       If NAME does not contain a registry, the local image storage will  be  consulted,  and  if
       it's not present there then it will be pulled from a suitable remote registry.

       --release RELEASE, -r RELEASE

       Create  a toolbox container for a different operating system RELEASE than the host. Cannot
       be used with --image.

EXAMPLES

   Create a toolbox container using the default image matching the host OS
              $ toolbox create

   Create a toolbox container using the default image for Fedora 36
              $ toolbox create --distro fedora --release f36

   Create a custom toolbox container from a custom image
              $ toolbox create --image bar foo

   Create a custom toolbox container from a custom image that's private
              $ toolbox create --authfile ~/auth.json --image registry.example.com/bar

SEE ALSO

       toolbox(1),  toolbox-init-container(1),  podman(1),   podman-create(1),   podman-login(1),
       podman-pull(1), containers-auth.json(5)

                                                                                toolbox-create(1)