Getting started

Install

From a release. Download the file for your system from the latest release:

The files aren’t code signed. On Windows, SmartScreen may say “Windows protected your PC”: click More info, then Run anyway. On macOS, open the app once, then System Settings > Privacy & Security > Open Anyway.

Updating installs over the old version and stops the background service first. Uninstalling (Windows: Apps in Settings) also takes the sandboxes’ entries off your folders’ permissions; your settings and logs stay.

From source. You need Python 3.12 or later. The lock file pins every dependency with its hash, so you get exactly the versions that were tested and audited:

git clone https://github.com/cfunkz/Pythonator.git
cd Pythonator
python -m venv .venv
. .venv/bin/activate            # Windows: .venv\Scripts\activate
pip install --require-hashes -r requirements.lock
pip install --no-deps -e .
pythonator

pip install -e . on its own works too and picks the newest allowed versions.

On Linux, install bubblewrap (sudo apt install bubblewrap, sudo dnf install bubblewrap) for the strongest sandbox. Without it the sandbox still works with Landlock and seccomp, which every current kernel has. System check in the toolbar shows what your computer enforces.

Your first service

1. Press New service (Ctrl+N), drop a script or a folder on the window, or press From Git to clone a repository.
2. Choose the Folder of the project. Detect from folder picks the language and the file to run (main.py, index.js, main.go, a package.json, go.mod, Cargo.toml…).
3. Leave the mode on Sandbox. If the program is a server, open the Network tab and list its port, for example 8000.
4. Press Save, then Packages ▾ → Install packages if the project has dependencies (a requirements.txt, package.json, Gemfile…), then Start (F5).

The console shows the program’s output as it happens. The first lines say what the sandbox allows, for example:

[19:05:20] Sandbox (Landlock + seccomp + bubblewrap): folder read & write, network on, serves 8000 for this computer

Close the window and the service keeps running. Open Pythonator again to see it.

The window

• Services, top left: each one with its state, its isolation mode and what it runs, and CPU and memory while it runs. Right-click one for more.
• Files, under the services: the selected service’s folder. Double-click a file to open it. The buttons make a new file or folder, fold the tree, and open the folder in your file manager.
• Editor, in the middle: the open files, with highlighting for every language Pythonator runs.
• Console, under the editor: the program’s output, and a line to type into its input.
• Plugins, on the right: panels of the plugins that have one, such as Guard and Health checks.

Drag the lines between them to give any part more room.

Closing and quitting

When you close the window while services run, Pythonator asks:

• Keep them running: the background service carries on. Services with Start when Pythonator starts checked start again whenever the background service starts.
• Stop everything and quit: every service is stopped politely (Ctrl+C or SIGTERM, then a kill after its stop timeout), and the background service exits.

With nothing running, closing the window quits everything.

Where your data is kept

Set PYTHONATOR_HOME to use another folder. Inside it:

Everything in it is readable only by your account. No service can see this folder, in any mode but Full access.

Pythonator 0.0.9 kept services in pythonator.json. The first start of 0.0.10 imports them once; anything that doesn’t pass the new checks is skipped and listed.

Keyboard shortcuts

On macOS, Ctrl is ⌘.

Next

• Services: restarts, schedules, limits and environment variables.
• Isolation modes and Ports and APIs: what a service may reach.
• Plugins: alerts, rules and health checks.