# SaltGUI: a web front end for a Salt master, with no database to run

> SaltGUI is a browser interface for a SaltStack master and its minions, built in plain ES2021 as a wrapper around the rest_cherrypy server that ships with salt-api. It needs no database and no extra web server, which makes deployment simple, and the price is that its permissions are exactly whatever salt-api grants, including everything by default.

**erwindon/SaltGUI** — A web interface for managing SaltStack based infrastructure.

- Repository: https://github.com/erwindon/SaltGUI
- Stars: 632 · Forks: 62
- Language: JavaScript
- License: MIT
- Published: 2026-10-21 · Updated: 2026-10-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/erwindon-saltgui

## A wrapper around salt-api, and nothing more

SaltGUI is an open source web interface for managing a SaltStack server and its minions, and the implementation choice is stated in the first paragraph. It is built using plain ES2021 and implemented as a wrapper around the rest_cherrypy server that is also known as salt-api. That single sentence explains most of the project's character. There is no separate server tier, no API of its own, no database, and no build pipeline that produces a backend. The CherryPy server is part of the salt-api package, it is configured from the master configuration file, and when set up as documented, both the API calls and the HTML and JavaScript files are served by that same server, so no additional web application server is needed. The setup claim in the feature list follows directly, simple setup without the need to add a database. The audience is operators of an existing Salt infrastructure, not people looking for a configuration management system to adopt.

## What the interface actually exposes

The feature list reads like a summary of the Salt command surface, and that is the point of the tool. You can view minions and copy their IP addresses, run state.highstate for one minion or for all of them, and see the seven most recent jobs run on the master. You can manually run any Salt function and watch its output, view the highstate for all minions with details, and view issues across all minions with trivial solutions. The per-minion inspection views cover grains, pillars, schedules and beacons, and the interface can show live events from the salt-event bus. There is documentation for any salt command, both the internal documentation shipped with Salt and the external documentation, and you can define your own custom documentation for commands. Beyond the raw command surface there are workflow conveniences, viewing minions organised by node-group, matching a list of minions against a reference list, matching the status of minions against a reference list, viewing orchestrations and starting them, and acting on multiple minions, keys or nodegroups by selecting them first. For an operator who does not want to memorise the Salt CLI, that is a large amount of surface in one place.

## The quick start is a master config edit

The installation path is unusually short because the web application is just files. You install salt-api, which comes from the Salt repository, open the master configuration at /etc/salt/master, and configure the external_auth section. The README's own example is:

```yaml
external_auth:
    pam:
        saltuser1:
            - .*
            - '@runner'
            - '@wheel'
            - '@jobs'

# for SaltStack 3006 and higher
netapi_enable_clients:
    - local
    - local_async
    - runner
    - wheel
```

The netapi_enable_clients option is not optional in practice, and the README explains why, since Salt version 3006 it is needed for salt-api, and therefore SaltGUI, to work at all. The same passage notes that any Python packages the SaltStack installation also depends on must be installed with salt-pip, which includes authentication plugins such as yubico_client and execution modules such as boto3_sns. Two further warnings are worth repeating. The saltuser1 name is only an example, and the README recommends personal accounts or a user group rather than a generic account, because the integrity of the master and all the minions depends on the choices made here. And the note attached to the configuration is blunt, with this configuration the user has access to all salt modules available, which may not be what you want. The project points at a PERMISSIONS.md document for restricted configurations.

## Serving the interface from the same CherryPy process

The rest of the master configuration tells the same CherryPy server to serve the interface itself, so there is no second process to deploy:

```yaml
rest_cherrypy:
    port: 3333
    host: 0.0.0.0
    disable_ssl: true
    app: /srv/saltgui/index.html
    static: /srv/saltgui/static
    static_path: /static
```

Two details in that block carry consequences. The host is 0.0.0.0, which means the interface is reachable from the network, and disable_ssl is true, which means it is not encrypted. The README flags this directly, saying that for production deployments TLS encryption is strongly recommended and pointing at a dedicated TLS configuration section for the full setup, including enterprise practices. The other detail is the path. From the Git repository, only the saltgui directory forms the actual SaltGUI web application, so you either replace each /srv/saltgui path with the real location or create a symlink pointing at it. With a default PAM setup, the salt user may also need read access to /etc/shadow to authenticate people, which the README suggests granting with a command that adds the salt user to the shadow group. Once the configuration is in place you restart the master and the API, and the interface is reachable on the port you configured.

## Authentication choices are made in two places

SaltGUI supports the authentication methods that Salt supports, and the list in the README is pam, file, ldap, mysql and yubico. PAM is described as the standard one, partly because it is by itself already very powerful and by default provides access to the Linux password file. The activation of methods happens in a plain text file inside the web application directory, at saltgui/static/salt-auth.txt, with one method name per line, and the choice of which methods to enable is left to the administrator. The warning attached to that file is worth quoting in substance, since the integrity of the salt-master and all salt-minions depends on it. The file also supports a special line, CLEAR, which restricts the effective methods to those listed in the configuration file. So there are two layers to get right, the external_auth entries in the master configuration that map a user to a set of Salt roles, and the enabled authentication methods in the text file, and a mistake in either one changes who can run what on your infrastructure.

## A JavaScript codebase with a strict tooling budget

The repository is a plain front end with a real test and linting setup, and the manifest describes it as a linting and testing package. It is private, it is marked as an ES module package, and its version is a snapshot of 1.35.0 while the released tags are behind at 1.34.0, so the manifest version is the development version rather than a published one. The tooling is modern: ESLint 10 with a compatibility plugin, Stylelint with the standard config, Mocha for unit tests, Chai for assertions, nyc for coverage, Puppeteer for the functional tests, Babel for the transpilation,. The coverage thresholds are set at 85 percent for lines, statements, functions and branches, with watermarks marking the acceptable range between 70 and 90, and the coverage scope is limited to the scripts under saltgui/static/scripts. The scripts section shows the shape of the work, with separate eslint and stylelint tasks over the scripts and tests directories, a unit test task using Mocha with leak checking, a functional test task driven by a custom runner, and a coverage task that layers nyc over the unit tests. The top level of the repository also holds a docker/ directory, a docs/ directory, a runtests.sh script and an eslint config file.

## Version support, and the Salt releases that break it

The compatibility story is the part to read before planning a deployment. The README opens with an alert that SaltGUI does not work with Salt 3008.0 or 3008.1 because those releases are broken, and that 3008.2 is mostly ok. Separately, the project states it can only support SaltStack versions 3006 and higher, because earlier versions are no longer published by the SaltStack team, which makes proper testing of SaltGUI releases very hard, and it suggests upgrading an older Salt installation. On the JavaScript side there is a similar statement about time passing. From the start of SaltGUI in 2016 until early 2026 the team used ES6 and ES2015 only, which has now become old, so the project has been upgraded to the ES version that was current five years ago. The intent is that the latest browser is not forced, but the README warns that browsers older than that are not detected and failures may then occur. The release tags include 1.34.0 in August 2026, 1.33.0 in March 2026 and 1.32.1 in June 2025, and the README explains the difference between the release tag, which is the latest released version, and master, which may contain changes that are not yet in the release notes.

## Conclusion

SaltGUI suits a team that already runs Salt and wants a browser view of minions, jobs, grains, pillars and the event bus, and that would rather not hand every operator command line access to the master. It is the wrong tool if you need fine grained roles per operator, because the interface inherits salt-api's authorisation model wholesale, and the default configuration in the README grants access to all Salt modules. Before deploying it, read PERMISSIONS.md and tighten the external_auth entries, enable netapi_enable_clients as the Salt 3006 change requires, and decide whether the salt user really needs the shadow group, because with PAM the salt user must read the shadow file to authenticate people.

## FAQ

### Does SaltGUI need its own database or web server?

No. The setup is simple because there is no database to add, and the CherryPy server that serves SaltGUI is part of the salt-api package, configured from the master configuration file, so both the API calls and the HTML and JavaScript files are served by it and no additional web application server is needed.

### What has to change in the Salt master configuration?

You add an external_auth section mapping a PAM user to Salt roles, and since Salt 3006 you also need the netapi_enable_clients option with the local, local_async, runner and wheel clients, plus a rest_cherrypy section pointing at the saltgui directory. The README warns that the example configuration grants access to all Salt modules and points at PERMISSIONS.md for restricted setups.

### Which authentication methods can SaltGUI use?

pam, file, ldap, mysql and yubico, all of which come from Salt. PAM is the standard option, and the methods that are actually enabled are listed one per line in the file saltgui/static/salt-auth.txt, with a CLEAR line restricting the effective methods to those in the configuration file.

### Which Salt versions does SaltGUI support?

Versions 3006 and higher, because earlier Salt releases are no longer published and cannot be tested properly. The README also alerts that SaltGUI does not work with Salt 3008.0 or 3008.1 because those releases are broken, and that 3008.2 is mostly ok.

## Sources

- [erwindon/SaltGUI on GitHub](https://github.com/erwindon/SaltGUI)
- [Issues](https://github.com/erwindon/SaltGUI/issues)
- [License: MIT](https://github.com/erwindon/SaltGUI/blob/master/LICENSE)
- [README](https://github.com/erwindon/SaltGUI/blob/master/README.md)
- [Releases](https://github.com/erwindon/SaltGUI/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/erwindon-saltgui