{"id":13688719,"url":"https://github.com/89luca89/lilipod","last_synced_at":"2025-05-16T01:06:54.953Z","repository":{"id":61629169,"uuid":"534397800","full_name":"89luca89/lilipod","owner":"89luca89","description":"Lilipod is a simple container manager, able to download, unpack and use OCI images from various container registries.","archived":false,"fork":false,"pushed_at":"2025-04-07T02:38:12.000Z","size":3037,"stargazers_count":429,"open_issues_count":15,"forks_count":13,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-04-08T12:08:36.264Z","etag":null,"topics":["chroot","containers","development","docker","go","golang","linux","nerdctl","oci","podman","registry","tools"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/89luca89.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"COPYING.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-09-08T21:22:52.000Z","updated_at":"2025-04-02T16:08:39.000Z","dependencies_parsed_at":"2023-01-21T05:17:22.351Z","dependency_job_id":"af737a7a-9bc3-431c-afff-9f873952b767","html_url":"https://github.com/89luca89/lilipod","commit_stats":{"total_commits":12,"total_committers":4,"mean_commits":3.0,"dds":"0.41666666666666663","last_synced_commit":"68b04f28b30332ffae74e626209a64642407efeb"},"previous_names":["89luca89/lilipod","89luca89/scatman"],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/89luca89%2Flilipod","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/89luca89%2Flilipod/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/89luca89%2Flilipod/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/89luca89%2Flilipod/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/89luca89","download_url":"https://codeload.github.com/89luca89/lilipod/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254448579,"owners_count":22072764,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["chroot","containers","development","docker","go","golang","linux","nerdctl","oci","podman","registry","tools"],"created_at":"2024-08-02T15:01:20.940Z","updated_at":"2025-05-16T01:06:49.936Z","avatar_url":"https://github.com/89luca89.png","language":"Go","funding_links":[],"categories":["golang","tools","Go"],"sub_categories":[],"readme":"# Lilipod\n\n\u003cpicture\u003e\n\u003csource srcset=\"assets/logo-dark.svg\" media=\"(prefers-color-scheme: dark)\"\u003e\n\u003cimg src=\"assets/logo-light.svg\"\u003e\n\u003c/picture\u003e\n\nLilipod aims to be a **very** simple (as in few features) container and image manager.\n\n## Lilipod?\n\nSounds like little-pod, and I like it.\n\n## So what does this manage?\n\nLilipod is a very simple container manager with minimal features to:\n\n- Download and manager images\n- Create and run containers \n\nIt tries to keep a **somewhat** compatible CLI interface with Podman/Docker/Nerdctl\n\n```shell\n~$ lilipod help\nManage containers and images\n\nUsage:\n  lilipod [command]\n\nAvailable Commands:\n  completion      Generate the autocompletion script for the specified shell\n  cp              Copy files/folders between a container and the local filesystem\n  create          Create but do not start a container\n  exec            Exec but do not start a container\n  help            Help about any command\n  images          List images in local storage\n  inspect         Inspect a container or image\n  logs            Fetch the logs of one or more \n  ps              List containers\n  pull            Pull an image from a registry\n  rename          Rename a container\n  rm              Remove one or more containers\n  rmi             Removes one or more images from local storage\n  run             Run but do not start a container\n  start           Start one or more containers\n  stop            Remove one or more containers\n  update          Update but do not start a container\n  version         Show lilipod version\n\nFlags:\n  -h, --help               help for lilipod\n      --log-level string   log messages above specified level (debug, warn, warning, error)\n  -v, --version            version for lilipod\n\nUse \"lilipod [command] --help\" for more information about a command.\n\n```\n\n\u003e **Warning**\n\u003e This is beta quality software, it's not heavily used and tested like other alternatives. Be aware.\n\n## So are these containers like in Podman or Docker right?\n\n![image](https://github.com/89luca89/scatman/assets/598882/d01d62d6-f659-4c07-b474-cd6505ff8ab5)\n\nWell...superficially yes; Sure you have a separate user, mount (and optionally network, pid, ipc) namespaces, and the processes are in a pivotroot jail, but this does not manage anything else, so: \n\n- no seccomp\n- no capabilities\n- no cgroups\n\nIf you need full blown containers, look no further than [Podman](https://github.com/containers/podman) or [Nerdctl](https://github.com/containerd/nerdctl) for your needs.\n\n## Goals\n\nLilipod wants to be:\n\n- nimble \n- single statically compiled binary\n- no external dependencies (as much as possible...more on this later)\n- Follow Podman command and flags name when possible, try also to match the output\n\n**This tool does not aim to be a full replacement for Podman, Docker, Nerdctl or similar tools**\n\n### Ok but why was it created?\n\nWell, I felt the need to go deeper in how to download a container image from a registry... then one thing lead to another... and here we are. 👀\n\nAlso this is a nice fallback for [Distrobox](https://github.com/89luca89/distrobox) when no container-manager is found, or when it's not possible to install one.  \nBeing a fully self-contained binary that lives in one directory (`LILIPOD_HOME`) it makes it easy to install and remove without package managers.\n\n# Getting started\n\n## Install\n\nDownload the binary from the release page, and use it.\n\n## Compile\n\n```console\nmake\n```\n\nThis will create a statically compiled binary.\n\n### Dependencies\n\nBy itself Lilipod depends only on some Linux utilities (nsenter, tar, cp, ps etc etc), those will be sourced from a bundled `busybox` static binary. This ensures working dependencies even on atypical systems.\n\nBut be aware that to work in a rootless manner, you need to have a working installation of the `uidmap` package.\n\nCiting their README:\n\n### subuid\n- `newuidmap` and `newgidmap` need to be installed on the host. These commands are provided by the `uidmap` package on most distributions.\n\n- `/etc/subuid` and `/etc/subgid` should contain more than 65536 sub-IDs. e.g. `penguin:231072:65536`. These files are automatically configured on most distributions.\n\nSee also [https://rootlesscontaine.rs/getting-started/common/subuid/](https://rootlesscontaine.rs/getting-started/common/subuid/)\n\n## Usage\n\nWhich commands are available:\n\n```console\n~$ lilipod\nManage containers and images\n\nUsage:\n  lilipod [command]\n\nAvailable Commands:\n  completion      Generate the autocompletion script for the specified shell\n  cp              Copy files/folders between a container and the local filesystem\n  create          Create but do not start a container\n  exec            Exec but do not start a container\n  help            Help about any command\n  images          List images in local storage\n  inspect         Inspect a container or image\n  logs            Fetch the logs of one or more \n  ps              List containers\n  pull            Pull an image from a registry\n  rename          Rename a container\n  rm              Remove one or more containers\n  rmi             Removes one or more images from local storage\n  run             Run but do not start a container\n  start           Start one or more containers\n  stop            Remove one or more containers\n  update          Update but do not start a container\n  version         Show lilipod version\n\nFlags:\n  -h, --help               help for lilipod\n      --log-level string   log messages above specified level (debug, warn, warning, error)\n  -v, --version            version for lilipod\n\nUse \"lilipod [command] --help\" for more information about a command.\n```\n\nPull an image:\n\n```console\n:~$ lilipod pull registry.opensuse.org/opensuse/tumbleweed:latest\npulling image manifest: registry.opensuse.org/opensuse/tumbleweed:latest\npulling layer db709715e7606a81da9764311fad42de7cebf7cedc14656853797864c5fc5aae.tar.gz\nCopying blob sha256:db709715e7606a81da9764311fad42de7cebf7cedc14656853797864c5fc5aae 100% |██████████████████████████████| (4.9 MB/s)         \nsaving layer sha256:db709715e7606a81da9764311fad42de7cebf7cedc14656853797864c5fc5aae done\nsaving manifest for registry.opensuse.org/opensuse/tumbleweed:latest\nsaving config for registry.opensuse.org/opensuse/tumbleweed:latest\nsaving metadata for registry.opensuse.org/opensuse/tumbleweed:latest\ndone\n84cfef9d6263a008a2d77f4a0863660f\n```\n\nRun a container and remove it afterwards:\n\n```console\n:~$ lilipod run --rm -ti alpine cat /etc/os-release\nNAME=\"Alpine Linux\"\nID=alpine\nVERSION_ID=3.18.3\nPRETTY_NAME=\"Alpine Linux v3.18\"\nHOME_URL=\"https://alpinelinux.org/\"\nBUG_REPORT_URL=\"https://gitlab.alpinelinux.org/alpine/aports/-/issues\"\n```\n\nCreate the first container:\n\n```console\n:~$ lilipod create --name first-lilipod docker.io/alpine:latest /bin/sh -l\nf1c35f7b7de161116abb3157bd125f06\n```\n\nStart the container:\n\n```console\n:~$ lilipod start -ti first-lilipod\nfirst-lilipod:/# \n```\n\nExec a command in an existing container:\n\n```console\n:~$ lilipod exec -ti first-lilipod cat /etc/os-release\nNAME=\"Alpine Linux\"\nID=alpine\nVERSION_ID=3.18.3\nPRETTY_NAME=\"Alpine Linux v3.18\"\nHOME_URL=\"https://alpinelinux.org/\"\nBUG_REPORT_URL=\"https://gitlab.alpinelinux.org/alpine/aports/-/issues\"\n```\n\nStop the container:\n\n```console\n:~$ lilipod stop first-lilipod\nfirst-lilipod\n```\n\nInspect the container:\n\n```console\n:~$ lilipod inspect --type container first-lilipod\n{\n  \"env\": [\n   \"PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin\",\n   \"HOSTNAME=first-lilipod\",\n   \"TERM=xterm\"\n  ],\n  \"cgroup\": \"private\",\n  \"created\": \"2023.09.07 10:17:04\",\n  \"gidmap\": \"1000:100000:65536\",\n  \"hostname\": \"first-lilipod\",\n  \"id\": \"f1c35f7b7de161116abb3157bd125f06\",\n  \"image\": \"docker.io/alpine:latest\",\n  \"ipc\": \"private\",\n  \"names\": \"first-lilipod\",\n  \"network\": \"private\",\n  \"pid\": \"private\",\n  \"privileged\": false,\n  \"size\": \"\",\n  \"status\": \"stopped\",\n  \"time\": \"private\",\n  \"uidmap\": \"1000:100000:65536\",\n  \"user\": \"root:root\",\n  \"userns\": \"keep-id\",\n  \"workdir\": \"/\",\n  \"stopsignal\": \"SIGTERM\",\n  \"mounts\": [],\n  \"labels\": [],\n  \"entrypoint\": [\n   \"/bin/sh\",\n   \"-l\"\n  ]\n }\n```\n\nInspect the image:\n\n```console\n:-$ lilipod inspect --type image alpine:latest\n{\n  \"architecture\": \"amd64\",\n  \"container\": \"ba09fe2c8f99faad95871d467a22c96f4bc8166bd01ce0a7c28dd5472697bfd1\",\n  \"created\": \"2023-08-07T19:20:20.894140623Z\",\n  \"docker_version\": \"20.10.23\",\n  \"history\": [\n   {\n    \"created\": \"2023-08-07T19:20:20.71894984Z\",\n    \"created_by\": \"/bin/sh -c #(nop) ADD file:32ff5e7a78b890996ee4681cc0a26185d3e9acdb4eb1e2aaccb2411f922fed6b in / \"\n   },\n   {\n    \"created\": \"2023-08-07T19:20:20.894140623Z\",\n    \"created_by\": \"/bin/sh -c #(nop)  CMD [\\\"/bin/sh\\\"]\",\n    \"empty_layer\": true\n   }\n  ],\n  \"os\": \"linux\",\n  \"rootfs\": {\n   \"type\": \"layers\",\n   \"diff_ids\": [\n    \"sha256:4693057ce2364720d39e57e85a5b8e0bd9ac3573716237736d6470ec5b7b7230\"\n   ]\n  },\n  \"config\": {\n   \"Cmd\": [\n    \"/bin/sh\"\n   ],\n   \"Env\": [\n    \"PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin\"\n   ],\n   \"Image\": \"sha256:39dfd593e04b939e16d3a426af525cad29b8fc7410b06f4dbad8528b45e1e5a9\"\n  },\n  \"container_config\": {\n   \"Cmd\": [\n    \"/bin/sh\",\n    \"-c\",\n    \"#(nop) \",\n    \"CMD [\\\"/bin/sh\\\"]\"\n   ],\n   \"Env\": [\n    \"PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin\"\n   ],\n   \"Hostname\": \"ba09fe2c8f99\",\n   \"Image\": \"sha256:39dfd593e04b939e16d3a426af525cad29b8fc7410b06f4dbad8528b45e1e5a9\"\n  }\n} \n```\n\nDelete the container:\n\n```console\n:-$ lilipod rm first-lilipod\nfirst-lilipod\n```\n\n---\n\nFor more advanced use, you can always use `--help` to have information about the commands to launch.\n\nYou can always set the log level to `warn` `error` or `debug` by using the `--log-level` flag:\n\n```console\n:-$ lilipod --log-level debug pull alpine:latest\npulling image manifest: index.docker.io/library/alpine:latest\npulling layer 7264a8db6415046d36d16ba98b79778e18accee6ffa71850405994cffa9be7de.tar.gz\nCopying blob sha256:7264a8db6415046d36d16ba98b79778e18accee6ffa71850405994cffa9be7de 100% |██████████████████████████████| (4.9 MB/s)        \nsaving layer sha256:7264a8db6415046d36d16ba98b79778e18accee6ffa71850405994cffa9be7de done\nfile_utils.go:119 [debug] input checksum is: sha256:7264a8db6415046d36d16ba98b79778e18accee6ffa71850405994cffa9be7de\nfile_utils.go:120 [debug] expected checksum is: sha256:7264a8db6415046d36d16ba98b79778e18accee6ffa71850405994cffa9be7de\nimage_utils.go:354 [debug] successfully checked layer: 7264a8db6415046d36d16ba98b79778e18accee6ffa71850405994cffa9be7de.tar.gz\nimage_utils.go:116 [debug] 1 layers successfully saved\nimage_utils.go:117 [debug] cleaning up unwanded files\nsaving manifest for index.docker.io/library/alpine:latest\nsaving config for index.docker.io/library/alpine:latest\nsaving metadata for index.docker.io/library/alpine:latest\ndone\nff727edbcbe60df2bd6a89cf65d6db2b\n```\n\n---\n\n# Performance\n\nDoing like 1/20th of what Podman or Nerdctl do, at least it tries to be fast...\n\nThere are some basic entering speed for an execution:\n\n```console\n:~$ time (for i in {1..20}; do podman exec -ti --user luca-linux fedora-rawhide whoami \u003e/dev/null 2\u003e/dev/null; done)\n\nreal    0m4.690s\nuser    0m2.178s\nsys     0m0.829s\n:~$ time (for i in {1..20}; do ./lilipod exec -i --user luca-linux fedora-rawhide whoami \u003e/dev/null 2\u003e/dev/null; done)\n\n\nreal    0m0.741s\nuser    0m0.458s\nsys     0m0.450s\n\n```\n\n```console\n:~$ time (for i in {1..20}; do podman run --rm -ti alpine:latest whoami \u003e/dev/null 2\u003e/dev/null; done)\n\nreal    0m10.125s\nuser    0m2.606s\nsys     0m1.744s\n:~$ time (for i in {1..20}; do ./lilipod run --rm -ti alpine:latest whoami \u003e/dev/null 2\u003e/dev/null; done)\n\nreal    0m6.157s\nuser    0m3.545s\nsys     0m2.613s\n\n```\n\n**It takes about 5~8ms to enter a container and execute stuff**\n\nThis obviously is a completely useless and arbitrary metric compared to the difference of utility of the two tools.\n\n# Configuration\n\nYou can set `LILIPOD_HOME` to force lilipod to create images/containers/volumes in a specific directory.\n\nElse lilipod will use `XDG_DATA_HOME` or fallback to `$HOME/.local/share/lilipod`\n\n# Limitations\n\n- by nature this tool does not use stuff like `overlayfs` so **there is no deduplication between container's rootfs**, but **image layer deduplication is present**\n- There is no custom networking, you either share host's network or you're offline\n\n\n# TO DO\n\n- Tests\n- Documentation\n- Create manpages from the usage docs automatically\n- Support Cgroups (low prio)\n- Support Capabilities (low prio)\n- Support private network (`slirp4netns` probably)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F89luca89%2Flilipod","html_url":"https://awesome.ecosyste.ms/projects/github.com%2F89luca89%2Flilipod","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F89luca89%2Flilipod/lists"}