Cross-Py-Builder

Cross-Py-Builder is a remote build tool for compiling Python projects with PyInstaller on different platforms (Linux, macOS, Windows) across a local network.

It has two parts:

• Controller — a small web service with a browser UI for submitting builds (upload a zip or point at a git repo), tracking live progress, and downloading the resulting binaries.
• Agent (worker) — one per target OS/CPU. Runs the actual PyInstaller builds and exposes them over HTTP; the controller dispatches builds to an agent matching the requested OS + CPU.

System Requirements

• Ubuntu/Debian & macOS: 2GB+ RAM
• Windows: 4GB+ RAM
• Python 3.10 or later installed on each host
• Local network between the controller and the agents

---

How it's packaged

This is a Python package installed with setuptools (setup.py). Installing it (editable, for development) makes two commands available on your PATH:

Command	Runs	Purpose
cross-py-controller	ctrl.app:main	Web UI + scheduler (the machine you browse to)
cross-py-agent	agent.build_agent:main	Worker agent (one per target OS/CPU)

Start by installing the package into a virtualenv on every machine that will act as a controller or agent:

cd cross-py-builder
python3 -m venv venv
source venv/bin/activate

pip install -e .          # editable install: installs deps + links to your working dir

-e (editable) links the install to your checkout, so code changes take effect without reinstalling. On the LXC workers you can alternatively copy the source and just run the .py files (see below).

---

Running a worker (agent)

On each target OS/CPU machine (e.g. each Ubuntu LXC):

cd cross-py-builder
python3 -m venv venv
source venv/bin/activate
pip install -e .

cross-py-agent

The agent binds on port 9001 and announces itself on the local network. To run it directly without the package command:

pip install -r requirements.txt
python agent/build_agent.py

---

Running the controller

On the machine that will serve the browser UI:

cd cross-py-builder
python3 -m venv venv
source venv/bin/activate
pip install -e .

Set the port (defaults to 8080) and start it:

CROSS_PY_PORT=8080 cross-py-controller

Then open http://<controller-ip>:8080 in a browser and add your agents from the Workers section of the UI (in host:port form, e.g. 192.168.1.40:9001). Each row shows live status (ready/down) and the agent's OS/CPU/version. Configured workers persist in the controller's SQLite DB, so they survive restarts — no environment variables needed after setup.

Controller environment variables

Variable	Default	Purpose
CROSS_PY_PORT	8080	HTTP port the controller UI listens on
CROSS_PY_MAX_CONCURRENT	1	Max simultaneous builds (across distinct agents)
CROSS_PY_DATA	<repo>/data	Data dir (SQLite jobs + workers DB, uploaded sources)
CROSS_PY_BUILDS	<data>/builds	Dir where finished build artifacts are saved
CROSS_PY_DEBUG	off	Use Flask dev server instead of waitress

---

Using the UI

1. Add your agents in the Workers section (host:port). Each shows live status (ready/down) and OS/CPU once reachable.
2. Open the controller in a browser.
3. Pick the target OS and CPU (or "any").
4. Either upload a .zip of your project (PyInstaller spec + source) or paste a git repo_url.
5. Submit. The job is queued → dispatched to a matching agent → built → artifacts fetched.
6. Watch live per-step progress, then download the built binaries from the job detail.

A submitted project only needs the source plus at least one *.spec file; each spec file in the archive produces a build.

---

Retired CLI

The original single-command CLI (./cross-py-builder.py --build ..., agent_manager.py) has been removed and replaced by the controller + agent model above.