Skip to main content

Alinux

Alinux is an AI orchestration shell for a minimal Debian 12 desktop running Fluxbox. It converts natural-language requests into a small, validated set of desktop actions.

Install

python3 -m venv .venv
. .venv/bin/activate
python -m pip install --upgrade --no-cache-dir --index-url https://pypi.org/simple 'alinux[openai]'
python -c "import alinux; print(alinux.__version__)"

On a fresh Debian 12 Fluxbox installation, the complete setup is:

python -m pip install alinux
alinux setup

alinux setup installs Firefox ESR, Tkinter, desktop control tools, Ollama, starts the Ollama service, and downloads the lightweight smollm2:360m model. It may ask for your sudo password.

The base package has no compiled model dependency. Use python -m pip install alinux when running without an LLM, or install the openai extra for OpenAI, Groq, and other OpenAI-compatible providers.

When no API key is configured, Alinux uses Ollama's local JSON-schema API instead of stopping. Install Ollama, start it, and download the lightweight default model:

curl -fsSL https://ollama.com/install.sh | sh
ollama pull smollm2:360m
alinux

Set ALINUX_LOCAL_MODEL to use another model already installed in Ollama.

Alinux's browser uses Firefox ESR with a separate ~/.config/alinux/browser profile. It is a full normal Firefox window with tabs, extensions, downloads, settings, and developer tools; no Python browser engine or additional package is required. Install it on Debian with:

sudo apt install firefox-esr

For model access, export a key and optionally choose a provider/model. Any OpenAI-compatible API can be configured with a custom endpoint:

export ALINUX_API_KEY='your-key'
export ALINUX_MODEL='gpt-4o-mini'
export ALINUX_API_BASE_URL='https://your-provider.example/v1'

To use the built-in Groq/Llama configuration from the command line, set your Groq key and pass the flag:

export GROQ_API_KEY='your-groq-key'
alinux --use-default-groq-api

The flag selects llama-3.3-70b-versatile and Groq's API endpoint. It does not embed or fetch a secret key.

Groq is supported directly, including Alinux's built-in open model preset:

export ALINUX_PROVIDER='groq'
export ALINUX_API_KEY='your-groq-key'
alinux

With ALINUX_PROVIDER=groq and no model override, Alinux uses llama-3.3-70b-versatile at Groq's OpenAI-compatible endpoint. You can also select it explicitly with ALINUX_MODEL=llama-3.3-70b-versatile.

The desktop hooks expect xdotool, amixer, free, and uptime. Missing tools are reported as readable responses rather than terminating Alinux.

Run

alinux

Open the graphical Alinux window from a terminal with:

alinux open

To add Open Alinux to the Fluxbox desktop context menu, run this once inside the Fluxbox session:

alinux install-fluxbox-menu

Remove the menu entry with:

alinux remove-fluxbox-menu

Then restart or reconfigure Fluxbox. The installer uses the active Python interpreter and writes GUI errors to ~/.cache/alinux/gui.log, so menu launches continue to work even when Fluxbox has a minimal PATH. It updates ~/.fluxbox/menu without replacing your existing entries. The GUI requires Debian's python3-tk package and a valid DISPLAY.

Type requests such as show system status, turn the volume down, or open the terminal. Enter quit or press Ctrl-D to exit.

Alinux never executes arbitrary shell text from the model. Only the operations listed in its system prompt and system_controls.py are routable.

Metadata

Release files for alinux 0.1.8

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for alinux 0.1.8
File Size Uploaded Provenance Actions
alinux-0.1.8.tar.gz 11.7 kB Without provenance Details for alinux-0.1.8.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for alinux 0.1.8
File Interpreter ABI Platform Actions
alinux-0.1.8-py3-none-any.whl Python 3 none any Details for alinux-0.1.8-py3-none-any.whl

Total release size: 25.5 kB

Release files / alinux-0.1.8.tar.gz

Download URL alinux-0.1.8.tar.gz
Size 11.7 kB
Tags Source
SHA-256 checksum
How to use checksums
37fc9ada46072c54b72f94bbddac045ee22fee140d293fc9c12bd754c3989659
BLAKE2b-256 checksum
How to use checksums
f0f19cca3af045e28ce1abf73e157ebab99bcfbf7a5bced736db94be64080067
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.2

Release files / alinux-0.1.8-py3-none-any.whl

Download URL alinux-0.1.8-py3-none-any.whl
Size 13.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
d161376f846412168db8b260a2657e1439b0b86cc083bbb736f5a14a0d1109f6
BLAKE2b-256 checksum
How to use checksums
2af0e6dc6f725828f30b3a4d9baea9f3299f0cf75674689415beaf63b32c2d04
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.2

Security for alinux 0.1.8

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page