Your plugin sends bytes
WooCommerce, Joomla, PrestaShop or any connector posts a PDF, image, ESC/POS, ZPL or other payload.
Open source · self-hosted · printer friendly
Web to printer.
Without the drama.
Pridge is the missing bridge between your software (apps, websites, servers and business systems) and the printer sitting in your office: a lightweight PHP + SQLite server, a secure desktop client, and a simple raw-print API.
✓No VPS required
✓Binary-safe raw jobs
✓Windows & macOS packages
Server online
PHP + SQLite · HTTPS
Client connected
3 printers mapped
Job #1248 printed
Raw payload · 184 ms
One tiny bridge, four simple steps
How Pridge moves a print job
Your application never needs direct access to the office network. The server queues the job; the client safely pulls it from inside.
Server queues the job
The PHP server authenticates the endpoint token, stores the original body and tracks the queue state in SQLite.
Client reserves it
The desktop client authenticates, heartbeats, reserves one pending job and decodes its binary-safe base64 payload.
The real printer prints
The job is sent to the mapped local printer and reported as printing, printed or failed, with history preserved.
Core repositories, one ecosystem
Explore the core of the bridge
Host the queue almost anywhere, then install the client on the computer that can see your local printers.
GPL-3.0 · additional terms
Pridge Server
A plain PHP and SQLite print job broker made for shared hosting and simple self-hosting.
- Admin UI for endpoints, clients, assignments and queue history
- Raw binary-safe job ingestion with bearer endpoint tokens
- Client authentication, temporary sessions and heartbeat tracking
- Clean cPanel-friendly installation with protected storage
GPL-3.0 · additional terms
Pridge Client
A secure desktop bridge that maps remote endpoints to installed local printers and runs quietly in the background.
- Multiple independent server profiles and background workers
- Automatic endpoint and installed-printer discovery
- Per-server printer mappings, polling and heartbeat intervals
- Self-contained Native and PyInstaller release packages
2Open-source components
11Documented API routes
0Required cloud services
∞Possible connectors
Official integrations
Pridge meets the software you already use
The ecosystem starts with Dolibarr and TakePOS, with room prepared for shops, ERPs, POS systems and custom applications.
FIRST INTEGRATION
Pridge Dolibarr Endpoint
Connect Dolibarr Receipt Printers and TakePOS to Pridge without patching Dolibarr core. Raw ESC/POS output is captured through a pridge:// stream wrapper and forwarded to Pridge Server over HTTPS.
- Works with Dolibarr Receipt Printers and TakePOS
- Keeps the built-in module enabled
- Supports endpoint tokens and server profiles
- Includes test receiver and print diagnostics
EXPANDING
More bridges are coming
The repository structure is ready for WooCommerce, ERP, POS, SDK, driver and community integrations as the Pridge ecosystem grows.
Endpoint explorer
A deliberately boring API
Simple HTTP, bearer tokens and predictable status transitions. Pick an endpoint to see what it does and copy a working example.
Submit a print job
Receives the original raw print payload for an authenticated virtual printer endpoint.
Request example
curl -X POST "https://print.example.com/api/plugin/jobs" \
-H "Authorization: Bearer ENDPOINT_TOKEN" \
-H "Content-Type: application/octet-stream" \
-H 'X-PrintBridge-Metadata: {"source":"woocommerce","order_id":"1001"}' \
--data-binary @receipt.bin
Response example
{
"job_id": 123,
"status": "pending"
}
The body is stored as raw bytes. Keep tokens out of URLs and query strings.
Documentation
From empty folder to first print
The essential instructions are built into this page. The repository links remain the source of truth for the full developer guides.
Documentation / Overview
What you need
Pridge has two independent components. Put the server on HTTPS hosting and run the client on a computer that can see the actual printer.
1
Deploy the server
Upload the PHP project, make storage writable and create the first administrator.
2
Create endpoint and client tokens
An endpoint accepts jobs. A client pulls jobs. Assign one or more endpoints to the client.
3
Configure the desktop client
Add the server URL and client token, then map each remote endpoint to an installed local printer.
4
Submit a raw payload
Post the document or printer bytes to /api/plugin/jobs using the endpoint token.
Terminology: an endpoint is a virtual print destination; a client is the office-side app or computer that pulls and prints its assigned jobs.
Documentation / Server
Install Pridge Server
The server is intended to run directly from a cPanel subdomain folder or from a stricter custom public document root.
Requirements
- PHP with PDO SQLite support
- HTTPS for production use
- A writable
storagedirectory - Optional PHP
mail()support for password recovery
cPanel-style installation
Example document root
public_html/printbridge # or the folder created for: printbridge.yourdomain.com
Upload the complete repository to that folder. The root index.php and .htaccess handle requests without requiring the document root to point at public/.
Writable paths
Storage paths
storage/ storage/database/
The SQLite database is created automatically at storage/database/printbridge.sqlite.
First administrator
Open the site. When no administrator exists, setup redirects to /setup. Create the first account with a password of at least 12 characters.
Documentation / Client
Install Pridge Client
For end users, choose a packaged release. The destination computer does not need Python, pip or manually installed packages.
1
Download a release
Choose the Native or PyInstaller package for Windows or macOS from GitHub Releases.
2
Launch the settings window
The client can run with a visible settings interface or quietly in the background after configuration.
3
Allow local printer access
The client discovers printers installed in the operating system and sends jobs through the platform print API.
Running from source is also supported with Python 3.9 or newer:
python3 -m pip install -e .Documentation / Configuration
Connect a client and map printers
- Create a client in the server admin UI and assign the required endpoints.
- Copy the client token when it is shown. Tokens are intentionally displayed once.
- In the desktop app, click Add Server.
- Enter a friendly name, HTTPS server URL and the client token.
- Set polling and heartbeat intervals, then click Test Connection.
- Wait for remote endpoints and installed local printers to load.
- Select a local printer for each endpoint, or choose Disabled.
- Save the server profile and start its background worker.
Every server profile has independent mappings and worker controls, so one desktop client can serve several Pridge Server instances.
Documentation / Integration
Build a CMS or shop connector
A connector needs only a server URL, one endpoint token and the raw bytes to print.
Submit the original payload
HTTP request
POST /api/plugin/jobs
Authorization: Bearer ENDPOINT_TOKEN
Content-Type: application/octet-stream
X-PrintBridge-Metadata: {"source":"woocommerce","order_id":"1001"}
RAW_PRINT_PAYLOAD_BYTES- Do not put tokens in query strings.
- Do not JSON-encode or base64-encode the request body unless your payload format specifically requires it.
- Use the real content type when known; otherwise use
application/octet-stream. - Metadata is optional JSON stored in the
X-PrintBridge-Metadataheader.
Documentation / Client protocol
Build another client agent
The protocol is language-neutral. A replacement client can be written in C++, Rust, C#, Go or any environment that can make HTTPS requests and use the local print system.
Recommended worker loop
Pseudocode
while running:
authenticate_if_needed()
maybe_send_heartbeat()
job = reserve_next_job()
if not job:
sleep(poll_interval)
continue
try:
mark_printing(job.id)
payload = base64_decode(job.payload_base64)
send_original_bytes_to_mapped_printer(payload)
mark_printed(job.id)
except Exception as error:
mark_failed(job.id, safe_message(error))The agent should never log full client tokens, session tokens, passwords or raw print payloads.
Documentation / Operations
Security and backup checklist
- Use HTTPS in production and never send secrets in URLs.
- Keep endpoint and client tokens out of logs and display them only once during creation.
- Ensure direct web access to
storage,appandviewsremains blocked. - When hosting permits it, keep the storage directory outside the public web root.
- Back up
storage/database/printbridge.sqliteand the completestorage/directory. - Stop write traffic before copying SQLite when possible and test restoration separately.
Never expose
printbridge.sqlite through HTTP. Treat it as application data containing queue and configuration history.Documentation / Packaging
Native and PyInstaller release builds
The client repository defines two independent packaged release targets:
- Native: Nuitka standalone compilation
- PyInstaller: PyInstaller onedir application bundles
Both include Python, runtime dependencies, pywebview files, frontend HTML/CSS/JavaScript, icons, assets, the license and additional terms. End users do not install Python.
Local build commands
# Windows PowerShell ./scripts/build-windows.ps1 -Variant All -SelectOutputDir # macOS bash scripts/build-macos.sh All --select-output-dir
Request builder
Generate your first cURL command
This stays entirely in your browser. Nothing is sent anywhere.
Request settings
Enter a sample base URL and choose the request you want to build.
Generated request
Copy it, replace the placeholders and run it in your terminal.
cURL
curl -X POST "https://print.example.com/api/plugin/jobs" \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/octet-stream" \ --data-binary @document.bin
Frequently asked questions
The sensible questions
Everything you need to decide whether Pridge fits your setup.
Does Pridge require a VPS?
No. The server is designed for ordinary PHP hosting with PDO SQLite support, HTTPS and a writable storage directory.
Does the office computer need Python?
Not when using packaged releases. Native and PyInstaller packages include the required runtime and dependencies.
Can it print ESC/POS, ZPL, PDF and images?
Yes. The server preserves raw request bytes. The client forwards them to the mapped local printer through the operating system.
Can one client connect to several servers?
Yes. Each server profile has independent tokens, endpoint mappings, polling intervals, heartbeat intervals and worker controls.
What happens when printing fails?
The client reports the job as failed with a safe error message. Failed jobs remain visible in the active queue for review or retry logic.
Is Pridge open source?
Yes. The server and client are both GPL-3.0-or-later licensed, with additional terms in their repositories.
Ready to cross the bridge?
Deploy the server. Install the client. Print.
Start from the source repositories, open the built-in quick-start guide, or use GitHub Issues to report a problem or propose a feature.