boxxy

boxxy

boxxy (case-sensitive) is a tool for boxing up misbehaving Linux applications and forcing them to put their files and directories in the right place, without symlinks!

boxxy is a part of the amyware discord server.

If you like what I make, consider supporting me on Patreon:

Linux-only! boxxy uses Linux namespaces for its functionality.

For example, consider the AWS CLI. It wants to store its config and credentials in ~/.aws/, but boxxy lets you redirect it to ~/.config/aws/ instead:

# ~/.config/boxxy/boxxy.yaml
rules:
- name: "Store AWS CLI config in ~/.config/aws"
  target: "~/.aws"
  rewrite: "~/.config/aws"

boxxy lets you control where applications read and write files — whether that's for XDG compliance, project-specific configs, or any other path redirection you need. While some applications (like tmux 3.1+) have added native XDG support over time, many others haven't, and boxxy also enables more advanced use cases like context-dependent configurations that applications will never support natively.

maintenance status

I am on a break from maintaining open-source projects due to health reasons. PRs will still be accepted and issues will still be looked at, but there are no promises about when this will happen.

motivation

I recently had to use the AWS CLI. It wants to save data in ~/.aws, but I don't want it to just clutter up my $HOME however it wants. boxxy lets me force it to puts its data somewhere nice and proper.

features

• box any program and force it to put its files/directories where you want it to
• context-dependent boxing, ie different rules apply in different directories depending on your configuration
• minimal overhead
• opt-in immutable fs outside of rule rewrites, ie only the files/directories you specify in rules are writable
• 0.5.0: boxxy can scan your homedir to automatically suggest rules for you!
• 0.6.0: boxxy can use project-local boxxy.yaml files, and can load .env files for you!
• 0.6.1: boxxy rules can inject env vars:
• 0.7.2: boxxy can fork the boxxed process into the background with the --daemon flag.
• 0.8.0: boxxy can pass rules at the command line with --rule, and disable loading config files with --no-config.
• 0.8.2: Explain how to run AppImages properly:

potential drawbacks

• new project, 0.x.y, comes with all those warnings
• cannot use sudo inside the container (see #6)
• primarily tested for my use-cases

example usage

…

suggested usage

• alias aws="boxxy aws" (repeat for other tools)
• use contexts to keep project configs separate on disk
• dotfiles!
• stop using symlinks!!!
• no more dev config files when writing code

requirements

boxxy requires newuidmap to function, which is not included by default in all distributions. To install:

Alpine:

$ apk add shadow-uidmap

Debian / Ubuntu:

$ apt install uidmap

RHEL / Fedora:

$ yum install shadow-utils

configuration

The boxxy configuration file lives in ~/.config/boxxy/boxxy.yaml. If none exists, an empty one will be created for you.

…

syntax

rules:
- name: "any valid string" # required
  target: "path" # required
  rewrite: "path" # required
  context: # optional
  - "path"
  - "path"
  mode: "directory | file" # optional
  only: # optional
  - "binary name"
  - "binary name"
  env: # optional
    KEY: "value"

developing

1. set up pre-commit: pre-commit install
2. make sure it builds: cargo build
3. do the thing!
4. test with the command of your choice, ex. cargo run -- ls -lah ~/.config

how does it work?

• create temporary directory in /tmp
• set up new user/mount namespace
• bind-mount / to tmp directory
• bind-mount rule mounts rw so that target programs can use them
• remount / ro
• run!

credits

• fixtures/helloworld-appimage-x86_84.AppImage: https://github.com/ClonedRepos/hello-world-appimage