fabriziosalmi/lws has 75 GitHub stars and 8 forks. GitHot measured 0 in 7 days. Last checked 2026-11-15 20:08 UTC. Last push 2026-11-03.
Measured star growth
- in 24h
- Update delayed
- in 7 days
- 0
- in 15 days
- Update delayed
- in 1 month
- Update delayed
Net star changes over overlapping periods, not daily totals. Missing measurements are left blank. Stars measure attention, not software quality.
About
Unified command line interface for Proxmox, LXC and Docker.
Developer ToolsREADME.md
OriginalLWS - Linux Web Services CLI
Documentation
Complete documentation is published on GitHub Pages.
- Getting Started - Installation and first steps
- Architecture - Modular design and structure
- CLI Reference - Complete command reference
- API Reference - REST API endpoints
- Configuration - Advanced configuration
- Contributing - How to contribute
Overview
LWS is a command-line interface (CLI) tool for managing LXC containers on Proxmox VE hosts. It performs common tasks - creating, starting, stopping, terminating, and managing LXC instances, as well as interacting with Proxmox hosts themselves - from a single command.
Recent changes:
- Modular core: config/SSH/Proxmox/utility functions are extracted into
lws_core/; the CLI command layer (lws.py) and the REST API (api.py) remain monolithic - see Architecture for the exact boundary - REST API: programmatic access to LWS functionality over HTTP (
api.py) - Web UI: a single-page interface (
ui.html) for interacting with the API - Swagger documentation: interactive API documentation at
/api/v1/docs - Security and reliability fixes: allow-listed input validation on remote-command arguments, SSH host key verification and env-var password passing, non-zero exit codes on failure, a production WSGI server for the API, and a fixed Docker image build - see Security Considerations
Table of Contents
- Introduction
- Features
- Getting Started
- Usage
- Security Considerations
- Best Practices
- Contributing
- Roadmap
- License
- Acknowledgements
Introduction
lws (Linux Web Services) is an open-source CLI tool for managing Proxmox hosts, LXC containers, and Docker services within those containers, through a single command set executed locally or over SSH.
Features
General
- Unified Interface: Manage Proxmox hosts, LXC containers, and Docker services with a single tool
- Remote Operations: Execute commands locally or remotely via SSH
- Error Handling: Robust error detection and reporting
- Logging: Comprehensive logging with both text and JSON formats
- Command Alias Support: Use short aliases for common commands
Proxmox Management
- Host Monitoring: Monitor CPU, memory, and disk usage of Proxmox hosts
- Cluster Operations: Manage Proxmox clusters (start, stop, restart)
- Template Management: Upload, create, and delete LXC templates
- Firewall Rules: Define and manage security groups and firewall rules
- Host Backups: Create and manage backups of Proxmox configurations
LXC Container Management
- Container Operations: Create, start, stop, reboot, and destroy containers
- Resource Scaling: Dynamically adjust CPU, memory, and storage resources
- Snapshot Management: Create, list, and delete container snapshots
- Network Configuration: Configure network settings for containers
- Volume Management: Attach and detach storage volumes to containers
- Container Migration: Migrate containers between Proxmox hosts
- Clone Containers: Create identical copies of existing containers
- Command Execution: Run arbitrary commands within containers
- Network Testing: Test network connectivity from containers
- Backup & Restore: Create and restore container backups
Docker Management
- Installation: Install Docker and Docker Compose within LXC containers
- Container Operations: Run, stop, and manage Docker containers
- Application Deployment: Deploy applications using Docker Compose
- Log Access: View logs from Docker containers
- Container Listing: List running Docker containers
- Application Updates: Update applications with new images
Security Tools
- Security Scanning: Perform security audits on containers
- Network Discovery: Discover reachable hosts in container networks
- Health Checks: Check CPU, memory, disk and DNS inside a container against fixed limits
- Monitoring: Monitor real-time resource usage with thresholds
Resource Reporting
- Advanced Container Reports: Generate comprehensive reports on container status and resources
- Resource Monitoring: Real-time monitoring of container CPU, memory, and disk usage
- Scaling Recommendations: Get intelligent scaling suggestions based on usage patterns
Getting Started
Prerequisites
- Python 3.10 or higher. The supported range is declared once, as
requires-pythoninpyproject.toml, and the CI matrix and the Docker image are checked against it. The published image ships 3.15. - Proxmox Virtual Environment 6.x or higher
- SSH access to Proxmox hosts
- The following Python packages:
- click
- pyyaml
- requests
- tqdm
Installation
- Clone the repository:
git clone https://github.com/fabriziosalmi/lws.git
cd lws
- Install required Python packages:
pip install -r requirements.txt
- Create a configuration file
config.yamlwith your Proxmox server details:
regions:
eu-south-1:
availability_zones:
az1:
host: proxmox1.example.com
user: root
ssh_password: your_password
az2:
host: proxmox2.example.com
user: root
ssh_password: your_password
instance_sizes:
small:
memory: 512
cpulimit: 1
storage: local:8
medium:
memory: 1024
cpulimit: 2
storage: local:16
large:
memory: 2048
cpulimit: 4
storage: local:32
default_storage: local
default_network: vmbr0
use_local_only: false
- Make the script executable and create an alias:
chmod +x lws.py && alias lws='python3 /path/to/lws.py'
- Verify the installation:
lws --version
Usage
Proxmox Host Management
List Proxmox Hosts
lws px list
Check Host Status
lws px status --region eu-south-1 --az az1
List Clusters
lws px clusters --region eu-south-1 --az az1
Backup Proxmox Configuration
lws px backup /path/to/backup/directory --region eu-south-1 --az az1
Start/Stop/Restart Cluster Services
lws px cluster-start --region eu-south-1 --az az1
lws px cluster-stop --region eu-south-1 --az az1
lws px cluster-restart --region eu-south-1 --az az1
Execute Command on Proxmox Host
lws px exec "free -m" --region eu-south-1 --az az1
Upload Template to Proxmox
lws px upload ./ubuntu-20.04-template.tar.gz ubuntu-20.04 --region eu-south-1 --az az1
LXC Container Management
Create and Start LXC Container
lws lxc run --image-id local:vztmpl/ubuntu-20.04-standard_20.04-1_amd64.tar.gz --size small --count 3 --hostname web-server
Start/Stop/Reboot Container
lws lxc start 100 101 102
lws lxc stop 100 101 102
lws lxc reboot 100
Show Container Details
lws lxc show 100
Show All Containers
lws lxc show
Scale Container Resources
lws lxc scale 100 --memory 2048 --cpulimit 2 --storage-size 32G
Monitor Container Resources
lws lxc status 100
Execute Command in Container
lws lxc exec 100 "apt-get update"
lws lxc exec 100 "sh -c 'apt-get update && apt-get -y upgrade'"
The command runs in the container without a shell. For &&, | or
redirections, wrap it in sh -c '...' as in the second line.
Create and Manage Snapshots
lws lxc snapshot-add 100 snap1
lws lxc snapshots 100
lws lxc snapshot-rm 100 snap1
Check Network Connectivity
lws lxc net 100 tcp 80
Show Container Info and IP
lws lxc show-info 100
lws lxc show-public-ip 100
Clone Container
lws lxc clone 100 101 --full
Scale Recommendations
lws lxc scale-check 100
Manage Container Services
lws lxc service status nginx 100
lws lxc service restart nginx 100
Advanced Health Check
lws lxc health-check 100 --fix
Resource Monitoring
lws lxc resources 100 --interval 5 --count 10
Generate Container Report
lws lxc report 100 --output json --file container_report.json
Container Backups & Restores
Create Container Backup
lws lxc backup-create 100 --download
Restore Container from Backup
lws lxc backup-restore 100 --backup-file /var/lib/vz/dump/vzdump-lxc-100-2026_10_10-02_00_00.tar.zst
Docker Management
Install Docker on Container
lws app setup 100
Run Docker Container
lws app run 100 -- -d -p 80:80 nginx
Deploy with Docker Compose
lws app deploy install 100 --compose-file docker-compose.yml --auto-start
Update Docker Compose Application
lws app update 100 docker-compose.yml
View Docker Logs
lws app logs 100 nginx --tail 100
List Docker Containers
lws app list 100
Remove Docker
lws app remove 100 --purge
Security Tools
Perform Security Scan
lws sec scan 100 --scan-type full
Network Discovery
lws sec discovery 100
Scaling Thresholds
lws lxc scale-check <id> reads the scaling section of config.yaml and
prints suggested CPU core, memory and disk values for a container. It compares
what the container is allocated (pct config) with the host's total cores and
memory. Nothing runs automatically: apply a suggestion with lws lxc scale.
scaling:
lxc_cpu:
min_threshold: 0.30 # suggest more cores below 30% of the host's cores
max_threshold: 0.80 # suggest fewer above 80%
step: 1
scale_up_multiplier: 1.5
scale_down_multiplier: 0.5
lxc_memory:
min_threshold: 0.40
max_threshold: 0.70
step_mb: 256
scale_up_multiplier: 1.25
scale_down_multiplier: 0.75
limits:
min_cpu_cores: 1
max_cpu_cores: 4
min_memory_mb: 512
max_memory_mb: 8192
min_storage_gb: 10
max_storage_gb: 500
Thresholds are fractions between 0 and 1. The full description of the keys is in the configuration reference.
API Server
The API server provides HTTP access to LWS functions.
Set a real
api_keyinconfig.yaml. The server refuses to start while it's empty or still the placeholder — generate one withpython3 -c 'import secrets; print(secrets.token_urlsafe(32))'.Run the API server:
python3 api.pyBy default it listens on
127.0.0.1:8080(loopback only). Changeapi.host/api.portinconfig.yamlif you need it reachable elsewhere — see the Security Considerations below before binding to anything but loopback.Interact with the API: Use tools like
curl, Postman, or the provided Web UI. Remember to include the API key in theX-API-Keyheader for protected endpoints.# Example: Health Check (no API key needed) curl http://localhost:8080/api/v1/health # Example: List LXC Instances (requires API key) curl -H "X-API-Key: your-secure-api-key" http://localhost:8080/api/v1/lxc/instances
Web UI
A simple web interface is provided to interact with the API.
- Ensure the API server (
api.py) is running. - Access the UI:
- Navigate your browser to the root URL of the running API server (e.g.,
http://localhost:8080/). The API server servesui.htmldirectly. - Opening
ui.htmlfrom disk (file:///.../ui.html) does not work: the page calls the API at a relative address.
- Navigate your browser to the root URL of the running API server (e.g.,
- Enter your API Key in the input field and use the buttons to trigger API calls. Responses will be displayed in a formatted view.
Swagger Documentation
Interactive API documentation is available via Swagger UI.
- Ensure the API server (
api.py) is running. - Access Swagger UI: Navigate your browser to
/api/v1/docsrelative to the API server's URL (e.g.,http://localhost:8080/api/v1/docs). - You can explore the available endpoints, view parameters, and even try API calls directly from the Swagger interface (remember to authorize using your API key via the "Authorize" button).
Security Considerations
Critical Security Recommendations
Secure Storage of Credentials:
- LWS currently only supports password-based SSH authentication (via
sshpass) — there is no SSH key-based auth, and no environment-variable or vault indirection forssh_password. Both are read as plain values straight out ofconfig.yaml - Until that changes, treat
config.yamlas a credentials file: keep it out of version control (it is.gitignored — seeconfig.yaml.examplefor the committed template) and don't reuse the passwords it holds elsewhere - Set restrictive file permissions on
config.yaml(600 or 640)
- LWS currently only supports password-based SSH authentication (via
Network Security:
- Use VPN or private networks for Proxmox host access
- Configure firewall rules to restrict SSH access to known IP addresses
- Change default SSH ports and disable password authentication when possible
API Security:
- Use strong, randomly generated API keys (minimum 32 characters)
- Enable HTTPS/TLS for all API communications in production
- Implement rate limiting to prevent abuse
- Regularly rotate API keys
Container Security:
- Run
lws sec scanregularly on your containers to detect security issues - Keep container images and software up to date
- Use security groups to restrict network access between containers
- Enable container logging and monitoring
- Run
Input Validation:
- Container/instance IDs are validated as numeric everywhere they're accepted (CLI arguments and the REST API)
- Security group names, template names, firewall protocol/port fields, source/destination IP/CIDR values, and
lxc run's free-text container-creation options (hostname, password, network config, DNS, lock) are validated against an allow-list, parsed as a real IP/CIDR, or shell-quoted for the remote command before being used - this closes the command-injection surface in the affected commands rather than attempting to escape it after the fact host/user/ssh_passwordcome fromconfig.yaml, which you control, and aren't user-supplied CLI input - see Secure Storage of Credentials above for how to protect that file instead
File Security:
- Temporary files are created using system temp directories
- HTTP requests include timeouts to prevent indefinite blocking
Security Properties Currently Implemented
- Allow-listed validation (or
shlex.quote) on every CLI value known to reach a remote shell/sed/grepcommand, instead of escaping output after construction - API key compared with
hmac.compare_digest(timing-safe); the server refuses to start with an empty or placeholder key - SSH password passed via the
SSHPASSenvironment variable, never in argv,ps, or logs - SSH host key verification (
StrictHostKeyChecking=accept-new): a changed key for an already-known host is rejected - CORS denies all cross-origin browser access by default; origins must be listed explicitly
api.pyruns behind a production WSGI server (waitress) unlessdebug: trueis explicitly set, and never enables Werkzeug's interactive debugger regardless of that setting- Failed commands exit with a non-zero process exit code instead of looking like a success
- The Web UI (
ui.html) renders API responses and error messages throughtextContent, notinnerHTML, so a value reflected in a response cannot execute as markup in the viewer's browser
Best Practices
- Resource Planning: Use
lws lxc scale-checkto get recommendations on optimal resource allocation. - Regular Backups: Create regular backups with
lws lxc backup-createto prevent data loss. - Monitoring: Use
lws lxc resourcesto monitor resource usage patterns. - Health Checks: Run
lws lxc health-checkperiodically to detect and fix issues. - Documentation: Generate reports with
lws lxc reportfor documentation and auditing purposes.
Contributing
lws is an open-source, single-maintainer project. Issues, feature requests, and pull requests are welcome.
How to Contribute
- Fork the Repository
- Create a Branch
git checkout -b feature-branch - Make Changes
- Submit a Pull Request
[!TIP] Include clear commit messages and documentation with your pull requests to make the review process smoother.
Roadmap
Unscheduled, not committed to a release:
- SSH key-based authentication, as an alternative to the current password-only model
- Configuration versioning for container configurations
- Kubernetes cluster management, alongside the current Proxmox/LXC scope
License
MIT License. See LICENSE.
Acknowledgements
- Proxmox VE, the virtualization platform this tool manages
- Click, the CLI framework this tool is built on