{"id":13469007,"url":"https://github.com/queer/boxxy","last_synced_at":"2025-05-14T14:09:10.148Z","repository":{"id":65800721,"uuid":"599299079","full_name":"queer/boxxy","owner":"queer","description":"boxxy puts bad Linux applications in a box with only their files.","archived":false,"fork":false,"pushed_at":"2024-12-04T20:40:41.000Z","size":623,"stargazers_count":1639,"open_issues_count":24,"forks_count":26,"subscribers_count":7,"default_branch":"mistress","last_synced_at":"2025-05-12T01:47:36.903Z","etag":null,"topics":["help-wanted"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/queer.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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":"2023-02-08T21:16:54.000Z","updated_at":"2025-05-09T23:35:49.000Z","dependencies_parsed_at":"2023-03-17T04:15:55.419Z","dependency_job_id":"944e4b1f-3a1a-40be-8cc8-c0252be909a4","html_url":"https://github.com/queer/boxxy","commit_stats":null,"previous_names":[],"tags_count":39,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/queer%2Fboxxy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/queer%2Fboxxy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/queer%2Fboxxy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/queer%2Fboxxy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/queer","download_url":"https://codeload.github.com/queer/boxxy/tar.gz/refs/heads/mistress","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254160226,"owners_count":22024567,"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":["help-wanted"],"created_at":"2024-07-31T15:01:24.137Z","updated_at":"2025-05-14T14:09:05.112Z","avatar_url":"https://github.com/queer.png","language":"Rust","funding_links":["https://patreon.com/amyware"],"categories":["Rust"],"sub_categories":[],"readme":"# boxxy\n\nboxxy (case-sensitive) is a tool for boxing up misbehaving Linux applications\nand forcing them to put their files and directories in the right place,\n**without symlinks!**\n\nboxxy is a part of the [amyware discord server](https://discord.gg/7WgSTwh).\n\nIf you like what I make, consider supporting me on Patreon:\n\n[\u003cimg src=\"https://i.imgur.com/YFjoCd1.png\" width=\"162\" height=\"38\" /\u003e](https://patreon.com/amyware)\n\nLinux-only! boxxy uses Linux namespaces for its functionality.\n\nFor example, consider tmux. It wants to put its config in `~/.tmux.conf`. With\nboxxy, you can put its config in `~/.config/tmux/tmux.conf` instead:\n\n```yaml\n# ~/.config/boxxy/boxxy.yaml\nrules:\n- name: \"redirect tmux config from ~/.tmux.conf to ~/.config/tmux/tmux.conf\"\n  target: \"~/.tmux.conf\"\n  rewrite: \"~/.config/tmux/tmux.conf\"\n  mode: \"file\"\n```\n\n[![asciicast](https://asciinema.org/a/558679.svg)](https://asciinema.org/a/558679)\n\n## maintenance status\n\nI am on a break from maintaining open-source projects due to health reasons.\nPRs will still be accepted and issues will still be looked at, but there are no\npromises about when this will happen.\n\n## motivation\n\nI recently had to use the AWS CLI. It wants to save data in `~/.aws`, but I\ndon't want it to just clutter up my `$HOME` however it wants. boxxy lets me\nforce it to puts its data somewhere nice and proper.\n\n## features\n\n- box any program and force it to put its files/directories where you want it to\n- context-dependent boxing, ie different rules apply in different directories\n  depending on your configuration\n- minimal overhead\n- opt-in immutable fs outside of rule rewrites, ie only the files/directories\n  you specify in rules are writable\n- `0.5.0`: boxxy can scan your homedir to automatically suggest rules for\n  you! ![image of boxxy scan](https://amyware.nyc3.digitaloceanspaces.com/2023/03/25/G6hrd3iQjEy65.png)\n- `0.6.0`: boxxy can use project-local `boxxy.yaml` files, and can load\n  `.env` files for you! ![image of 0.6.0 features](https://amyware.nyc3.digitaloceanspaces.com/2023/03/28/Jawp5It1xrnWN.png)\n- `0.6.1`: boxxy rules can inject env vars: ![image of 0.6.1 features](https://amyware.nyc3.digitaloceanspaces.com/2023/03/29/ukcWuiYdtI8yq.png)\n- `0.7.2`: boxxy can fork the boxxed process into the background with the\n  `--daemon` flag.\n- `0.8.0`: boxxy can pass rules at the command line with `--rule`, and disable\n  loading config files with `--no-config`.\n- `0.8.2`: Explain how to run AppImages properly: ![image of 0.8.2 features](https://amyware.nyc3.digitaloceanspaces.com/2023/10/31/yMiHJaURUud6E.png)\n\n### potential drawbacks\n\n- new project, 0.x.y, comes with all those warnings\n- **cannot** use sudo inside the container (see [#6](https://github.com/queer/boxxy/issues/6))\n- primarily tested for my use-cases\n\n## example usage\n\n```sh\ngit:(mistress) | ▶  cat ~/.config/boxxy/boxxy.yaml\nrules:\n- name: \"Store AWS CLI config in ~/.config/aws\"\n  target: \"~/.aws\"\n  rewrite: \"~/.config/aws\"\n\ngit:(mistress) | ▶  boxxy aws configure\n INFO  boxxy \u003e loaded 1 rules\n INFO  boxxy::enclosure \u003e applying rule 'Store AWS CLI config in ~/.config/aws'\n INFO  boxxy::enclosure \u003e redirect: ~/.aws -\u003e ~/.config/aws\n INFO  boxxy::enclosure \u003e boxed \"aws\" ♥\nAWS Access Key ID [****************d]: a\nAWS Secret Access Key [****************c]: b\nDefault region name [b]: c\nDefault output format [a]: d\ngit:(mistress) | ▶  ls ~/.aws\ngit:(mistress) | ▶  ls ~/.config/aws\nconfig  credentials\ngit:(mistress) | ▶  cat ~/.config/aws/config\n[default]\nregion = c\noutput = d\ngit:(mistress) | ▶\n```\n\n### suggested usage\n\n- `alias aws=\"boxxy aws\"` (repeat for other tools)\n- use contexts to keep project configs separate on disk\n- dotfiles!\n- stop using symlinks!!!\n- no more dev config files when writing code\n\n## requirements\n\nboxxy requires `newuidmap` to function, which is not included by default in all\ndistributions. To install:\n\nAlpine:\n```sh\n$ apk add shadow-uidmap\n```\n\nDebian / Ubuntu:\n```sh\n$ apt install uidmap\n```\n\nRHEL / Fedora:\n```sh\n$ yum install shadow-utils\n```\n\n## configuration\n\nThe boxxy configuration file lives in `~/.config/boxxy/boxxy.yaml`. If none\nexists, an empty one will be created for you.\n\n```yaml\nrules:\n# The name of the rule. User-friendly name for your reference\n- name: \"redirect aws-cli from ~/.aws to ~/.config/aws\"\n  # The target of the rule, ie the file/directory that will be shadowed by the\n  # rewrite.\n  target: \"~/.aws\"\n  # The rewrite of the rule, ie the file/directory that will be used instead of\n  # the target.\n  rewrite: \"~/.config/aws\"\n- name: \"use different k8s configs when in ~/Projects/my-cool-startup\"\n  target: \"~/.kube/config\"\n  rewrite: \"~/Projects/my-cool-startup/.kube/config\"\n  # The context for the rule. Any paths listed in the context are paths where\n  # this rule will apply. If no context is specified, the rule applies\n  # globally.\n  context:\n  - \"~/Projects/my-cool-startup\"\n  # The mode of this rule, either `directory` or `file`. `directory` is the\n  # default. Must be specified for the correct behaviour when the target is a\n  # file. Required because the target file/directory may not exist yet.\n  mode: \"file\"\n  # The list of commands that this rule applies to. If no commands are\n  # specified, the rule applies to all programs run with boxxy.\n  only:\n  - \"kubectl\"\n```\n\n### syntax\n\n```yaml\nrules:\n- name: \"any valid string\" # required\n  target: \"path\" # required\n  rewrite: \"path\" # required\n  context: # optional\n  - \"path\"\n  - \"path\"\n  mode: \"directory | file\" # optional\n  only: # optional\n  - \"binary name\"\n  - \"binary name\"\n  env: # optional\n    KEY: \"value\"\n```\n\n## developing\n\n1. set up pre-commit: `pre-commit install`\n2. make sure it builds: `cargo build`\n3. do the thing!\n4. test with the command of your choice, ex. `cargo run -- ls -lah ~/.config`\n\n### how does it work?\n\n- create temporary directory in /tmp\n- set up new user/mount namespace\n- bind-mount `/` to tmp directory\n- bind-mount rule mounts rw so that target programs can use them\n- remount `/` ro\n- run!\n\n## credits\n\n- `fixtures/helloworld-appimage-x86_84.AppImage`: https://github.com/ClonedRepos/hello-world-appimage\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fqueer%2Fboxxy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fqueer%2Fboxxy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fqueer%2Fboxxy/lists"}