bash-stack: a web framework where the server is a shell script

The README is three commands long

bash-stack is described as a modern web framework in bash, and the README is refreshingly short. The quick start is one line:

curl -SsL create.bashsta.cc | bash

That command creates a new bash stack app. Then the README points at the developer docs at bashsta.cc for how it works, and answers the why question with two words: not sure.

What this tells you about the project is worth stating plainly. The README is a signpost, not documentation. The design intent is that a developer lands on the repository, runs the one-liner, and then learns the framework from the separate documentation site at bashsta.cc. There is no architecture diagram, no configuration reference and no API list in the README itself.

The repository topics are bash and htmx, and those two words describe the whole approach. The server side is shell, and the browser side is handled by htmx, so a page update is a server response rather than a client side application. The examples directory reinforces this: it contains a router example and a sessions example, which are the two things you would expect a web framework to have to get right before it is useful for anything.

The homepage of the project is bashsta.cc, and the README notes that the framework was built live on Twitch, which explains both the tone and the pace of the documentation.

Two ways to start: the curl installer and nix

There are two entry points, and they suit different people.

The first is the curl installer above, which is the fastest route for trying the framework. It fetches a script from create.bashsta.cc and pipes it into bash, so what it does to your machine is whatever that script does. For an educational project that is a reasonable trade, and for anything else it is worth reading the script first.

The second is Nix, and it is the cleaner option for anyone who already uses it. The README says that if you have nix, you can directly start a bash-stack from any compatible project directory:

nix run github:cgsdev0/bash-stack

The phrase that carries the weight is any compatible project directory. The framework is not a standalone server you run against an arbitrary folder; it expects a project laid out in a way it understands. The repository has a `flake.nix` and a `flake.lock`, which is how the Nix route is wired up, and the GitHub reference in the command means the flake is fetched straight from the repository at that revision.

The practical difference between the two paths is that the Nix route pins a revision and gives you a reproducible environment, while the curl route gives you whatever the installer serves at the moment you run it.

What the examples folder reveals about the feature set

The examples directory is more informative than the README, and it is worth reading as a feature list. It contains nine projects: `bg-task`, `docs`, `file-upload`, `jeopardy-buzzer`, `router`, `sessions`, `tailwind`, `template` and `todo-list`.

Several of these names tell you what the framework actually implements. `router` is routing. `sessions` is session handling, which is the other half of a web framework's minimum. `template` is templating. `file-upload` is multipart handling. `bg-task` is background work, which means long running tasks outside the request cycle. `tailwind` is styling integration with Tailwind CSS. `todo-list` and `docs` are ordinary applications built on the framework, and `jeopardy-buzzer` is a small interactive project that presumably exercises more than one feature at once.

What you will not find in that list is a test framework, a database layer, an ORM, a deployment story or a security module. That absence is consistent with the disclaimer in the README, and it tells you the scope: this is a demonstration of what a shell-based web framework can look like, not a set of components to assemble a production service from.

The `tests/` directory at the top level of the repository does exist, so the framework is not entirely untested, although the README does not describe how the tests are run.

Three shell files at the root tell you the startup path

The repository layout is small enough to read in full. At the top level there are `bootstrap.sh`, `core.sh` and `start.sh`, alongside `flake.nix`, `flake.lock`, the `examples/` directory and the `tests/` directory.

The naming suggests a three stage lifecycle. A bootstrap step that prepares the environment, a core file holding the framework itself, and a start step that brings the server up. That is the entire runtime of the project, and it is a fair indicator of how much of the framework you can read in an afternoon.

The `.github/` directory at the top level holds the workflows, and there is a `.gitignore`, a `LICENSE` and a `README.md`. The absence of a `package.json`, a `requirements.txt` or any other dependency manifest is the notable omission, because it means there is nothing to install. The dependencies of a shell framework are the shell and whatever the framework shells out to, and the examples directory suggests that set is small.

The examples directory also exists in the repository root rather than in a separate repository, so the reference implementations are versioned alongside the framework and will normally match the release you are running.

The maintainer says it is riddled with security issues

The disclaimer in the README is the most important paragraph in the project, so it is worth reading closely rather than skimming.

It states that the project is intended for educational and entertainment purposes only, that in its current implementation it is riddled with security issues, and that it would probably be extremely irresponsible to use this for any sort of production grade web service. It then adds that if you happen to use it for anything, the author would like to hear about it.

That is a clear-eyed statement, and it changes how the project should be evaluated. A shell web server handling HTTP requests is exactly the kind of program where the boundaries between request data, the filesystem and command execution are easy to get wrong, and the author is telling you not to trust it with anything that matters. The htmx pairing reduces the amount of client side code, but it does not reduce the server side attack surface.

For a learner this is a feature rather than a defect, since a framework small enough to read in one sitting is exactly where you can see where such problems come from. For anyone considering an actual deployment, the disclaimer settles the question before you spend time on it. It also means there is no point asking about hardening, configuration for exposure to the internet or a production support story, because the project has already answered that it is not one.

A separate note: the curl installer runs a remote script as your user with no checksum or signature in the command line, which is the same category of risk the disclaimer points at.

MIT licence and a release every year or so

The licence field on the repository says MIT, which is permissive and means you can read, copy and modify the code freely. For a project whose purpose is to be read, that is the right choice, and it also means the ideas here can be carried into another language or a different design without a licensing obstacle.

The release history shows a project that moves in bursts rather than steadily. The tagged releases are v0.7.0 on 2026-09-07, v0.6.1 on 2025-09-06 and v0.6.0 on 2024-07-08, and the last push was on 2026-09-07, the same day as v0.7.0. The version is still below 1.0, and the gaps between the v0.6 releases and the v0.7 release run from months to more than a year, so the framework's shape can change noticeably between releases without any promise of compatibility.

That gap also means the version number tells you less than it would in a project with a steady release train. If you are following the project, the commit history and the examples directory are more informative than the tag list.

One more project-level detail: the README says the framework was built live on Twitch, and it links a Twitch channel and a Star History chart. This is a project with a person attached to it rather than a foundation or a company, and the release cadence reflects that reality.

Editorial conclusion

Use bash-stack to learn how a web framework is put together, or to prototype a htmx driven page without a runtime to install, and treat it as a teaching tool rather than a deployment option. Skip it for anything reachable from the internet, because the maintainer's own disclaimer says the implementation is riddled with security issues and would be extremely irresponsible for a production grade web service. Verify first that your Nix setup can run `nix run github:cgsdev0/bash-stack` from a compatible project directory, and read the developer docs at bashsta.cc, since the README itself contains almost no detail. The licence field on the repository says MIT, and the last push was on 2026-09-07 with release v0.7.0 the same day.

Frequently asked questions

Official sources

1. cgsdev0/bash-stack on GitHub
2. License: MIT
3. Project website
4. README
5. Releases