{"id":13560010,"url":"https://github.com/ahayzen/folderbox","last_synced_at":"2025-04-03T15:31:25.873Z","repository":{"id":65273299,"uuid":"583166852","full_name":"ahayzen/folderbox","owner":"ahayzen","description":"Folder based containers that isolate project environments with escapes to the host for development","archived":false,"fork":false,"pushed_at":"2025-02-19T20:45:38.000Z","size":64,"stargazers_count":34,"open_issues_count":11,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-02-19T21:31:09.798Z","etag":null,"topics":["bash","command-line","containers","dev-environment","developer-environment","development","linux","podman"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ahayzen.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSES/MPL-2.0.txt","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-12-29T00:57:44.000Z","updated_at":"2025-02-17T05:44:17.000Z","dependencies_parsed_at":"2024-01-16T18:59:45.151Z","dependency_job_id":"68a687d9-4ebb-4718-97c4-9ede6c0cbd32","html_url":"https://github.com/ahayzen/folderbox","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ahayzen%2Ffolderbox","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ahayzen%2Ffolderbox/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ahayzen%2Ffolderbox/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ahayzen%2Ffolderbox/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ahayzen","download_url":"https://codeload.github.com/ahayzen/folderbox/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247027918,"owners_count":20871617,"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":["bash","command-line","containers","dev-environment","developer-environment","development","linux","podman"],"created_at":"2024-08-01T13:00:36.157Z","updated_at":"2025-04-03T15:31:20.846Z","avatar_url":"https://github.com/ahayzen.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003c!--\nSPDX-FileCopyrightText: Andrew Hayzen \u003cahayzen@gmail.com\u003e\n\nSPDX-License-Identifier: MPL-2.0\n--\u003e\n\nWorkspaces using containers which can be executed against a project folder.\nAllowing the development environment to be separate from the host, while still providing sandbox escapes.\n\n# Aims\n\n  * Provide an isolated per project or topic developer environment from the host\n  * Automatic integration with audio, permissions, sound, SSH, windowing etc\n  * Works on any system with `pipewire`, `podman`, `ssh`, `wayland`, `x11` installed\n  * Allow for development on immutable systems, such as Fedora Silverblue, and executing from inside [`distrobox`](https://github.com/89luca89/distrobox/)\n  * Provide a container environment for IDEs (such as VSCode) to attach to\n\n# Usage\n\nRun the `install.sh` for an automated install, this creates the common and containers folders in `~/.local/share/com.ahayzen.folderbox` and symlinks the `folderbox` script into `~/.local/bin`.\n\n\n```bash\n# expects .folderbox folder with box definition\nfolderbox ~/path/to/project\n\n# expects boxname in ~/.local/share/com.ahayzen.folderbox/containers\nfolderbox boxname ~/path/to/project\n```\n\nTo rebuild or pull a container simply remove the container and run `folderbox` again, `podman rmi folderbox-boxname`.\n\nSee the [sandbox folder](./src/sandbox/) for supported sandbox escapes.\n\n# Project Format\n\nA folderbox is defined either in the `.folderbox` folder of the project or in the shared `~/.local/share/com.ahayzen.folderbox/containers` folder.\n\nInside the folder a `Containerfile.in` or `Containerfile` is expected, this should setup the environment - if it's a `.in` file then note you can use `#include \"path/to/common/snippet\"`.\nNote that common snippets are installed into `~/.local/share/com.ahayzen.folderbox/common`.\n\nSee [data/containers/example-cpp](./data/containers/example-cpp) as an example of a container and [data/common](./data/containers) for snippets.\n\nThere also can be a `runargs` file, each line of this file are added as arguments to the `podman run` command. (eg `runargs` could container `--volume=/custom/path:/custom/path` which would then volume mount `/custom/path`).\n\n```\nmy-project/\n  .folderbox/\n    Containerfile.in\n    runargs\n    ...other_context_items...\n  src/\n\n~/.local/share/com.ahayzen.folderbox/containers/my-env/\n  Containerfile.in\n  runargs\n  ...other_context_items...\n```\n\nThese would then be used with either `folderbox /path/to/my-project` or `folderbox my-env /path/to/project`, note that the `my-env` can be used with multiple projects.\n\n# Persistence\n\nThe `$HOME` folder in the container is stored for each folderbox in `~/.local/share/com.ahayzen.folderbox/persist/\u003cboxname\u003e-\u003ccksum of project\u003e-\u003cbasename of project\u003e`,\nthis allows for user installs, repositories, configuration, and bash history to be preserved between sessions.\n\nNote that the container itself is removed once it is stopped, so if packages or changes to the root\nof the container were made, these should be written into the `Containerfile` and the folderbox rebuilt.\n\nIf root folders do need to be persistent then mount them as volumes using the `runargs` file.\n\n# VSCode\n\nVisual Studio Code can attach to the folderbox container by using the [Remote Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) extension.\n\n  * Install the extension `ms-vscode-remote.remote-containers`\n  * Start the `folderbox` container\n  * `View` -\u003e `Command Palette...`\n  * `\u003e Dev Containers: Attach to Running Container...`\n  * Pick your folderbox container\n\n## Flatpak\n\nWith the flatpak of Visual Studio Code this works in a similar way, just the path to `podman` needs to be set so that it can reach the host.\n\nRun the following commands to create a `podman-host` command in your `~/.local/bin`, this is the same as the [distrobox setup](https://github.com/89luca89/distrobox/blob/0e24aae53ae6e2fd6901db3556de9e6b261e7a6f/docs/posts/integrate_vscode_distrobox.md#third-step-podman-wrapper) for Visual Studio Code.\n\n```bash\nmkdir -p ~/.local/bin\nsudo tee ~/.local/bin/podman-host \u003c\u003cEOF\n#!/bin/bash\nset -x\nif [ \"\\$1\" == \"exec\" ]; then\n # Remove 'exec' from \\$@\n shift\n script='\n     result_command=\"podman exec\"\n        for i in \\$(printenv | grep \"=\" | grep -Ev \" |\\\"\" |\n            grep -Ev \"^(HOST|HOSTNAME|HOME|PATH|SHELL|USER|_)\"); do\n\n            result_command=\\$result_command --env=\"\\$i\"\n     done\n\n        exec \\${result_command} \"\\$@\"\n    '\n exec flatpak-spawn --host sh -c \"\\$script\" - \"\\$@\"\nelse\n exec flatpak-spawn --host podman \"\\$@\"\nfi\nEOF\n\n# ensure this file isn't writable, vscode has corrupted it before\nsudo chmod 0500 ~/.local/bin/podman-host\nsudo chown \"$USER:$USER\" ~/.local/bin/podman-host\n```\n\nThen in your Visual Studio Code settings set `podman-host` to the path.\n\n`\"dev.containers.dockerPath\": \"${HOME}/.local/bin/podman-host\",`\n\n# Other projects\n\nThere are other projects that are similar to folderbox but with different goals,\nfolderbox tries to keep your projects isolated while integrating with the host.\n\n| Project | Declarative | Sandbox | Custom Sandbox Control | Packaging System | Default Folder Access |\n|---------|-------------|---------|------------------------|------------------|---|\n| devbox | Yes | None | - | Nix | All |\n| distrobox | No | Weak | Minimal | OCI | Home |\n| folderbox | Yes | Partial | Raw | OCI | Directory |\n| x11docker | Yes | Strong | Yes | OCI | None |\n\n  * [devbox](https://github.com/jetpack-io/devbox) - \"Instant, easy, and predictable development environments\"\n    * Uses Nix packaging to provide packages but doesn't isolate file access from the host, whereas folderbox is isolated to project folders\n  * [distrobox](https://github.com/89luca89/distrobox/) - \"Use any linux distribution inside your terminal. Enable both backward and forward compatibility with software and freedom to use whatever distribution you're more comfortable with.\"\n    * Tries to create a terminal that has access to the whole of $HOME and feels like it is running as the host, whereas folderbox is isolated to project folders\n  * [x11docker](https://github.com/mviereck/x11docker/) - \"Run GUI applications and desktops in docker and podman containers. Focus on security.\"\n    * Tries to isolate applications with opt-in confinement escapes, whereas folderbox enables all confinement escapes by default\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fahayzen%2Ffolderbox","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fahayzen%2Ffolderbox","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fahayzen%2Ffolderbox/lists"}