{"id":13446818,"url":"https://github.com/senges/kitt","last_synced_at":"2026-02-21T18:01:56.338Z","repository":{"id":37524103,"uuid":"475852106","full_name":"senges/kitt","owner":"senges","description":"The container based portable Shell environment","archived":false,"fork":false,"pushed_at":"2023-02-23T14:01:05.000Z","size":242,"stargazers_count":20,"open_issues_count":3,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-09-07T07:28:38.237Z","etag":null,"topics":["bash","containers","docker","dotenv","dotfiles","nix","nixos","nixpkgs","python","shell","zsh"],"latest_commit_sha":null,"homepage":"","language":"Python","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/senges.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2022-03-30T11:42:22.000Z","updated_at":"2025-07-31T19:40:25.000Z","dependencies_parsed_at":"2024-01-07T10:50:50.304Z","dependency_job_id":"a92f562e-cb37-4b81-8f88-7ef0ee476f54","html_url":"https://github.com/senges/kitt","commit_stats":{"total_commits":152,"total_committers":1,"mean_commits":152.0,"dds":0.0,"last_synced_commit":"7c8c80a5095c76c5d89e3726a09921d474dcf530"},"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/senges/kitt","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/senges%2Fkitt","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/senges%2Fkitt/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/senges%2Fkitt/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/senges%2Fkitt/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/senges","download_url":"https://codeload.github.com/senges/kitt/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/senges%2Fkitt/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29689644,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-21T15:51:39.154Z","status":"ssl_error","status_checked_at":"2026-02-21T15:49:03.425Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["bash","containers","docker","dotenv","dotfiles","nix","nixos","nixpkgs","python","shell","zsh"],"created_at":"2024-07-31T05:01:00.699Z","updated_at":"2026-02-21T18:01:56.311Z","avatar_url":"https://github.com/senges.png","language":"Python","readme":"# Kitt\n\nKitt is a container based portable shell environment manager.\n\nBuild, spawn, push and distribute your shell, with your tools, and your config, anywhere.\n\n## Demo\n\n![](./docs/static/example01.png)\n\n## Installation\n\nFirst, make sure you have python3 and Docker installed.\n\nTo use kitt as a non root user, you should be in docker group : `sudo usermod -aG docker USER`.\n\n```\n➜  pip install kitt-shell\n```\n\n.. or just run `kitt.py` from sources.\n\n\u003e \n\n## How to use Kitt\n\nFill a configuration file (see [examples folder](./examples)) either in `toml` or `json` format. \nFeed it to Kitt and let the magic happend !\n\n```\n➜  kitt build examples/devops.conf devops\n✓ Build success !\n\n➜  kitt run devops\nuser@kitt:~# \n```\n\nNot your computer but you need your tools ? No problem.\n\n```\n➜  kitt pull senges/kitt devops\n✓  Image devops pull done\n\n➜  kitt run devops\nuser@kitt:~# \n```\n\nFew commands workflow examples are available in [examples folder](./examples/commands.md).\n\n### Kitt CLI reference\n\n```\n➜  kitt --help\n\nUsage: kitt [OPTIONS] COMMAND [ARGS]...\n\n  main command group\n\nOptions:\n  -h, --help   Show this message and exit.\n  -d, --debug  Debug mode\n\nCommands:\n  build    Build image from source config file\n  inspect  Show image metadata\n  list     List local images\n  patch    Patch image runtime metadata\n  prune    Prune local images\n  pull     Pull image and exit\n  push     Push kitt image to registry\n  refresh  Pull latest version of local images\n  remove   Remove local image\n  run      Run kitt shell\n  version  Show version\n```\n\n## Configuration\n### Basics\n\n```toml\n[options]\ndocker_in_docker = false    # Share docker socket\nforward_x11 = false         # Configure x11 forward\n\n[workspace]\nimage = \"ubuntu:22.04\"  # OCI System Image\ntools = []              # Nix tools\nuser = \"user\"           # Username inside container\nhostname = \"kitt\"       # Container hostname\ndefault_shell = \"bash\"  # One of bash, zsh, sh, dash\npaths = []              # Additional folders in $PATH\n\n# [[workspace.envs]]  # Container exported ENV (multiple)\n# name = \"\"\n# value = \"\"\n\n# [[workspace.volumes]]   # Container bind volumes (multiple)\n# host = \"\"   # Local directory\n# bind = \"\"   # Bin inside container\n# mode = \"\"   # Mode (default is 'rw')\n\n# [secrets]\n# [[secrets.files]]   # File entry (multiple)\n# src = \"\"                    # Host path\n# dest = \"\"                   # Container path\n# [[secrets.envs]]   # Env variable (multiple)\n# name = \"\"                   # Variable name\n# value = \"\"                  # Secret value\n```\n\nFor more details about **Nix tools**, see [tools installation](#Tools-installation) section.\n\n### Secrets\n\nKitt is able to embed password encrypted secrets (files and env vars) inside an image.\n\nA password prompt will be shown at container runtime to decrypt and restore the secrets :\n* Env vars are loaded inside the container\n* Files are restored insed a tempFS destoyed at container exit\n\n\u003e **Warning**  \n\u003e Kitt vault uses SHA256(password) as AES encryption key.\n\u003e Use with caution, weak password could lead to sensitive information leak.\n\n### Plugins\n\nKitt offers multiple _optional_ plugins to improve environment customization.\n\n| Plugin     | Description                           | Requires |\n|------------|---------------------------------------|----------|\n| _sh_       | run basic shell command               |          |\n| _zsh_      | install and setup Zsh (oh-my-zsh)     |          |\n| _copy_     | copy local files inside container     |          |\n| _download_ | download ressources inside container  | curl     |\n| _git_      | clone git repository inside container | git      |\n| _pip_      | install pip package                   | pip      |\n\nSee [PLUGINS.md](./PLUGINS.md) for configuration details.\n\n**Need another plugin ?**\n\nAdd jinja formated plugin inside `kitt/static/plugins` folder and use it in your config file under the same name.\n\n## How does it work ?\n\nKitt will build an [OCI Container Image](https://github.com/opencontainers/image-spec) (compatible with Docker, Podman, ...), according to the provided configuration file. It will install requested tools inside, setup your desired shell(s), shortcuts, completion, plugins, and add your configuration files.\n\nAt runtime, Kitt will create a container from this image, spawn a shell inside and attach it to your current TTY. \n\n### Tools installation\n\nFor the tool installation part, Kitt relies on the huge 80k+ packages [NixOS Store](https://search.nixos.org). \nIt does provide an uniform OS agnostic way of installing tools inside containers, and can be extended if necessary.\n\nThanks to Nix, you can effortlessly change your base image OS, anytime.\n\n### Containerization\n\n\u003e At first, kitt was meant to run with Podman as it is rootless by design (which solves uig/gid mapping problems).  \n\u003e However, for multiple reasons, it should now mainly run with Docker.\n\u003e Podman support is in progress, see branch `feat/podman`.\n\n**What is UID/GID reflexion ?**\n\n\u003e TL;DR: It's great for shared folders file rigths.\n\nKitt uses [fixuid](https://github.com/boxboat/fixuid) project to reflect host user UID/GID inside the container. What does that means ?\n\nAs Docker containers run as root (except rootless ones, but still), if you have a shared volume\nbetween your host and container, files created inside the container will be owned by root on the host. This mecanism makes working with volumes for user owned files very unconvenient.\n\nWith `fixuid`, the user inside the container will have the exact same real `uid` as your current host user. So if you bind a directory (your `home` for example), any file created by the user inside the container will be own by your user on the host side instead of root.","funding_links":[],"categories":["Development with Docker","docker"],"sub_categories":["Development Environment"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsenges%2Fkitt","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsenges%2Fkitt","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsenges%2Fkitt/lists"}