{"id":50925972,"url":"https://github.com/sandbox-utils/sandbox-run","last_synced_at":"2026-06-16T23:02:09.699Z","repository":{"id":319806518,"uuid":"1074562149","full_name":"sandbox-utils/sandbox-run","owner":"sandbox-utils","description":"🔒🐧 Run command in a secure OS-native sandbox (0 deps)","archived":false,"fork":false,"pushed_at":"2026-03-16T13:47:14.000Z","size":97,"stargazers_count":75,"open_issues_count":2,"forks_count":4,"subscribers_count":1,"default_branch":"master","last_synced_at":"2026-03-17T01:44:47.230Z","etag":null,"topics":["bubblewrap","bubblewrap-scripts","bwrap","container","container-security","containerization","exec","firejail","jail","jails","namespaces","opsec","posix-sh","sandbox","sandbox-environment","sandboxing","secure","security","security-tools","shell"],"latest_commit_sha":null,"homepage":"https://github.com/sandbox-utils/sandbox-run","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sandbox-utils.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-12T03:13:15.000Z","updated_at":"2026-03-10T02:10:29.000Z","dependencies_parsed_at":"2025-10-31T04:17:25.340Z","dependency_job_id":null,"html_url":"https://github.com/sandbox-utils/sandbox-run","commit_stats":null,"previous_names":["sandbox-utils/sandbox-run"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/sandbox-utils/sandbox-run","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sandbox-utils%2Fsandbox-run","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sandbox-utils%2Fsandbox-run/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sandbox-utils%2Fsandbox-run/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sandbox-utils%2Fsandbox-run/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sandbox-utils","download_url":"https://codeload.github.com/sandbox-utils/sandbox-run/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sandbox-utils%2Fsandbox-run/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34426745,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-16T02:00:06.860Z","response_time":126,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["bubblewrap","bubblewrap-scripts","bwrap","container","container-security","containerization","exec","firejail","jail","jails","namespaces","opsec","posix-sh","sandbox","sandbox-environment","sandboxing","secure","security","security-tools","shell"],"created_at":"2026-06-16T23:02:07.458Z","updated_at":"2026-06-16T23:02:09.698Z","avatar_url":"https://github.com/sandbox-utils.png","language":"Shell","funding_links":["https://github.com/sponsors/kernc"],"categories":[],"sub_categories":[],"readme":"sandbox-run: run command in a secure OS sandbox\n===============================================\n\n[![Build status](https://img.shields.io/github/actions/workflow/status/sandbox-utils/sandbox-run/ci.yml?branch=master\u0026style=for-the-badge)](https://github.com/sandbox-utils/sandbox-run/actions)\n[![Language: shell / Bash](https://img.shields.io/badge/lang-Shell-peachpuff?style=for-the-badge)](https://github.com/sandbox-utils/sandbox-run)\n[![Source lines of code](https://img.shields.io/endpoint?url=https%3A%2F%2Fghloc.vercel.app%2Fapi%2Fsandbox-utils%2Fsandbox-run%2Fbadge?filter=sandbox-run%26format=human\u0026style=for-the-badge\u0026label=SLOC\u0026color=skyblue)](https://ghloc.vercel.app/sandbox-utils/sandbox-run)\n[![Script size](https://img.shields.io/github/size/sandbox-utils/sandbox-run/sandbox-run?style=for-the-badge\u0026color=skyblue)](https://github.com/sandbox-utils/sandbox-run)\n[![Issues](https://img.shields.io/github/issues/sandbox-utils/sandbox-run?style=for-the-badge)](https://github.com/sandbox-utils/sandbox-run/issues)\n[![Sponsors](https://img.shields.io/github/sponsors/kernc?color=pink\u0026style=for-the-badge)](https://github.com/sponsors/kernc)\n\n\n#### Problem statement\n\nRunning other people's programs is inherently insecure.\n[Rogue dependencies](https://www.google.com/search?q=malicious+python+packages\u0026tbm=nws)\\*\n🎯 or [hacked library code](https://www.google.com/search?q=(hacked+OR+hijacked+OR+backdoored+OR+\"supply+chain+attack\")+(npm+OR+pypi)\u0026tbm=nws\u0026num=100)\n:pirate_flag: ([et cet.](https://slsa.dev/spec/draft/threats-overview) :warning:)\n**can wreak havoc, including access all your private parts** :bangbang:—think\nall current user's credentials and more personal bits like:\n* `~/.ssh`,\n* `~/.pki/nssdb/`,\n* `~/.mozilla/firefox/\u003cprofile\u003e/key4.db`,\n* `~/.mozilla/firefox/\u003cprofile\u003e/formhistory.sqlite` ...\n\n\u003csub\u003e✱ Running any\n[Electron app](https://www.electronjs.org/apps)\nrelies on impeccability of hundreds or thousands of dependencies, NodeJS and Chromium to say the least! 😬\u003c/sub\u003e\n\n#### Solution\n\nRun scary software in separate secure containers:\n```shell\npodman run --rm -it -v \"$PWD:$PWD\" --net=host --workdir=\"$PWD\" debian:stable-slim ./scary-binary\n```\nor you can simply \n`sandbox-run scary-binary`\n(e.g. `sandbox-run npx @google/gemini-cli`)\nwhich uses [**bubblewrap**](https://github.com/containers/bubblewrap) (of\n[Flatpak](https://en.wikipedia.org/wiki/Flatpak) fame) to spawn your native OS container under the hood,\nand, after downloading almost 500 MB ❗ of JavaScript sources,\nexecutes this untrusted third-party's Node/NPM package anonymously and securely,\nwith its CWD in `$PWD` and new `$HOME` in `$PWD/.sandbox-home`.\n\n\nInstallation\n------------\nThere are **no dependencies other than a POSIX shell** with\n[its standard set of utilities](https://en.wikipedia.org/wiki/List_of_POSIX_commands)\n**and `bubblewrap`**.\nThe installation process, as well as the script runtime,\nshould behave similarly on all relevant compute platforms,\nincluding GNU/Linux and even\n[Windos/WSL](https://learn.microsoft.com/en-us/windows/wsl/install). 🤞\n\n```shell\n# Install the few, unlikely to be missing dependencies, e.g.\nsudo apt install coreutils binutils bubblewrap\n\n# Download the script and put it somewhere on PATH\ncurl -vL 'https://bit.ly/sandbox-run' | sudo tee /usr/local/bin/sandbox-run\nsudo chmod +x /usr/local/bin/sandbox-run  # Mark executable\n\nsandbox-run\n# Usage: sandbox-run ARG...\nsandbox-run ls /\n```\n\nUsage\n-----\nWhenever you want to run a scary executable, simply run:\n```shell\nsandbox-run scary-app args\n```\nto run `scary-app` in a secure sandbox.\n\n\n#### Extra Bubblewrap arguments\n\nYou can also pass additional bubblewrap arguments to individual\nprocess invocations via **`$BWRAP_ARGS` environment variable**. E.g.:\n\n```sh\nBWRAP_ARGS='--bind /opt /opt' \\\n    sandbox-run ./NVIDIA-Driver-Installer.run\n```\n\nFor details, see `bubblewrap --help` or [`man 1 bwrap`](https://manpages.debian.org/unstable/bwrap).\n\nNote, **[`.env` file](https://stackoverflow.com/questions/68267862/what-is-an-env-or-dotenv-file-exactly)\nat project root** is respected, and sourced for the sandbox environment.\n\nSee more specific examples below.\n\n\n#### Filesystem mounts\n\nThe **current working directory is mounted with read-write permissions**,\nwhile everything else required for a successful run (e.g. /usr)\nis mounted **read-only**. In addition:\n\n* `\"$PWD/.sandbox-home\"` is bind-mounted as `\"$HOME\"`,\n\nTo mount extra endpoints, use `BWRAP_ARGS=` with switches `--bind` or `--bind-ro`.\nAnything else not explicitly mounted by an extra CLI switch\nis **lost upon container termination**.\n\n\n#### Linux Seccomp\n\nSee `bwrap` switches [`--seccomp FD` and `--add-seccomp-fd FD`](https://manpages.debian.org/unstable/bubblewrap/bwrap.1.en.html#:~:text=Lockdown%20options%3A-,--seccomp%20fd,-Load%20and%20use).\n\n\n#### Runtime monitoring\n\nIf **environment variable `VERBOSE=`** is set to a non-empty value,\nthe full `bwrap` command line is emitted to stderr before execution.\n\nYou can list bubblewraped processes using the\n[command `lsns`](https://manpages.debian.org/unstable/lsns)\nor the following shell function:\n\n```sh\nlist_bwrap () { lsns -u -W | { IFS= read header; echo \"$header\"; grep bwrap; }; }\n\nlist_bwrap  # Function call\n```\n\nYou can run `sandbox-run bash` to spawn **interactive shell inside the sandbox**.\n\n\n#### Environment variables\n\n* `BWRAP_ARGS=`– Extra arguments passed to `bwrap` process; space or line-delimited (if arguments such as paths themselves contain spaces).\n* `SANDBOX_RO_BIND=`– List of additional path glob expressions to mount read-only inside the sandbox.\n* `VERBOSE=`– Print full `exec bwrap` command line right before execution.\n\n\n#### Debugging\n\nTo see what's failing, run the sandbox with something like `colorstrace -f -e '%file,%process' ...`.\n\n\nExamples\n--------\nTo pass extra environment variables, other than those filtered by default,\nuse `bwrap --setenv`, e.g.:\n```sh\nBWRAP_ARGS='--setenv OPENAI_API_KEY c4f3b4b3'  sandbox-run my-ai-prog\n# or pass via .env (dotenv) file\n```\n\nTo run the sandboxed process as **superuser**\n(while still retaining all the security functionality of the container sandbox),\ne.g. to open privileged ports, use args:\n```sh\nBWRAP_ARGS='--uid 0 --cap-add cap_net_bind_service' sandbox-run python -m http.server 80\n```\n\nTo run **GUI (X11) apps**, some prior success was achieved using e.g.:\n```sh\nBWRAP_ARGS='--bind /tmp/.X11-unix/X0 /tmp/.X11-unix/X8 --setenv DISPLAY :8' \\\n    sandbox-run python -m tkinter\n```\nSee [more examples on the ArchWiki](https://wiki.archlinux.org/title/Bubblewrap#Using_X11).\n\n\nContributing\n------------\nYou see a mistake—you fix it. Thanks!\n\n\nAlternatives\n------------\nSee a few alternatives discussed over at sister project\n[`sandbox-venv`](https://github.com/sandbox-utils/sandbox-venv/#Viable-alternatives).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsandbox-utils%2Fsandbox-run","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsandbox-utils%2Fsandbox-run","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsandbox-utils%2Fsandbox-run/lists"}