Print your assignment. Skip the per-printer setup.
Prefer printing from Word? On macOS and Linux, run print-soc virtual-printer install
to add a Print@SoC printer through a guided setup. Setup requirements →
Download · Features · Agent skill · System printer setup · Demo · First print · User guide · Report an issue
Dark / light comparison · two actual macOS captures joined diagonally · local development build.
Preview before you print. Review the page, choose your binding edge, and keep the printer settings in view. Try the sample PDF or inspect the screenshot provenance.
See the reverse-side preview
The same two-page document, viewed from the back. This is a preview, not proof of physical duplex output.
I started my master’s at NUS in 2025 and struggled to set up SoC printing on my Mac. SSH printing helped, but my ICA Student’s Pass (STP) documents came out enlarged and cut off. Non-PDF files needed extra conversion, and I had no easy way to look up past print jobs.
So I built Print@SoC: a place to preview documents, choose a printer and keep a printing history.
Now I’m a PhD student, and I still see new students struggling with the same setup. I hope this saves you some of the trouble I went through.
Why I built this · Problem statement · Design rationale · Install · Architecture · Development
- One-command virtual printer setup: run
print-soc virtual-printer installto add Print@SoC to the macOS/Linux system printer list through an interactive Rust wizard. Print from your application's normal Print dialog. - Preview before submission: import PDFs, images and Office documents, inspect the prepared pages, and review front/back layout with the print settings alongside.
- Long-edge and short-edge duplex: choose how the paper turns, see the binding edge and front/back guide in preview, and keep that choice when printing.
- Paper and layout controls: choose copies, paper size, orientation, duplex binding, n-up or booklet layout. Conversion and advanced-layout dependencies are listed below.
- One account across entry points: desktop, CLI, MCP and native printing use the shared SoC account and operating-system credential store.
- Job tracking and history: inspect desktop and system-originated jobs, see the number of jobs ahead when queue evidence is available, and distinguish queue departure from confirmed paper output.
- Guided maintenance: interactive installation, update checks, download verification, recovery and an uninstall preview with data-retention choices.
- Agent skill support: let Codex or Claude Code help set up printing, find an accessible printer, prepare the settings and follow your job. The bundled print-soc skill uses CLI, desktop and MCP where available.
- Light and dark themes: use the same document workspace in either appearance, with English and Chinese interface options.
print-soc virtual-printer installOn macOS/Linux, after installing the CLI and a desktop build with the Rust driver, save your SoC account in the desktop first. This command opens a guided installer: choose the destination queue, paper and duplex defaults, review the proposed changes, and authenticate locally when administrator access is required. It registers the local CUPS printer, installs the Rust backend and configures the user-session service.
After setup, select PrintAtSoC in another application's Print dialog. The Rust service submits through your shared SoC account and retains the job PDF for GUI history and preview. Keep your login session, credential store and SoC network connection available while printing. The native print-processing path does not depend on Python.
# Inspect the plan without installing or printing:
print-soc virtual-printer install --dry-run
# Check the installed integration:
print-soc virtual-printer statusThis is one command to start guided configuration, not a promise of unattended installation without credentials or administrator authorization. The CUPS installer does not provide a Windows system driver. Full setup and removal guide.
You can hand the setup to Codex, Claude Code or another local agent. The print-soc skill covers finding a printer you can access, preparing the file, choosing paper and binding, adding the system printer, and following the result. It also covers updates and removal.
Copy this prompt to your agent:
Read https://github.com/Qingbolan/Print-SoC/blob/main/AGENTS.md and use its print-soc skill to set up SoC printing on my computer, find an accessible printer near me, and prepare my document and print settings; show me the preview and selected settings before printing, and let me enter passwords locally.
Install the skill for Codex or Claude Code · MCP setup
Use $print-soc in Codex or /print-soc in Claude Code once installed. The agent
needs local access to Print@SoC and your documents; the skill itself does not
provide credentials or send a test print. Native system-printer setup is available
on macOS/Linux, while direct desktop printing also supports Windows.
Watch the real Word printing recording (MP4) · Open the Word sample
Recorded on macOS with a public two-page sample: open Word's Print dialog, select Print@SoC Virtual Printer, review copies and page controls, then click Print. This is a continuous screen recording at original speed, trimmed to remove the recording toolbar at the end. It does not show driver installation or changing duplex binding. A separate live test verified A4 short-edge duplex output; see the validation record.
A student trying to print an assignment needs to make several independent choices: which printer is accessible, which queue reaches it, how to authenticate, and how to express paper and duplex settings. A conventional network-printer setup exposes these choices through operating-system-specific configuration screens and printer drivers.
Setup means finding the right address, protocol, queue and driver, then checking the defaults. The steps vary by operating system and printer.
Three concrete use cases motivated Print@SoC:
- An assignment from a personal laptop: the user wants to preview a PDF and choose a nearby accessible printer without creating a separate local printer entry for every destination.
- Slides or documents from another application: the user wants familiar Print-dialog controls, with the resulting PDF and effective settings visible in the same job history.
- An apparently stalled submission: the user needs to distinguish a failed upload, a queued job and a job that has left the server queue before deciding whether to retry.
The third case makes observability part of the printing problem. A successful submission command is useful evidence, but it does not establish that the document has physically printed. Retrying on that assumption can produce duplicate output.
SoC users already have an account for accessing university Unix services. Print@SoC uses that authenticated SSH connection to submit documents through the server's existing lpr interface and inspect its queues. The university infrastructure continues to own queue access and printer delivery; the application owns document preparation, submission tracking and the user interface.
Conventional network-printer setup
Application → OS print system + printer configuration
→ campus print service → physical printer
Print@SoC document workflow
Document → desktop preview + preparation
→ authenticated SSH → SoC Unix server → lpr → physical printer
Optional Print@SoC system-printer workflow
Application → OS print dialog → local CUPS + Rust backend
→ Rust service → authenticated SSH → SoC lpr → physical printer
The direct document workflow avoids per-destination local driver setup. The optional system printer addresses a different need: printing from applications that already render their own documents. It adds a local integration point while retaining the shared submission and history model.
| Design choice | What it gives the user | Remaining constraint |
|---|---|---|
| Reuse SoC SSH authentication | One account for the desktop and native print service | The account must be authorized and the server reachable. |
| Submit through the server's print commands | Select a remote queue without configuring each printer locally | Queue capabilities and access restrictions remain server-specific. |
| Prepare a PDF before submission | Inspect the document that will be sent | Office conversion and advanced layout need additional local tools. |
| Share a job lifecycle across entry points | Inspect system-originated and desktop jobs in one workspace | A queue observation cannot prove physical output. |
| Use a standalone Rust CUPS backend | System printing does not depend on the user's Python environment | CUPS integration applies to macOS/Linux and needs installation. |
Print@SoC uses the university’s existing printing infrastructure. Queue access and supported options still depend on the destination printer.
You need a SoC account and network access to your SoC Unix server, through the campus network or NUS VPN as appropriate. This is an independent community project, not an official NUS service.
Choose the installer for your machine from GitHub Releases.
| Platform | Download |
|---|---|
| macOS | Apple Silicon or Intel application archive |
| Windows | x86-64 setup executable |
| Linux | x86-64 AppImage |
The release page is the authority for available assets. This README describes the current source tree; changes under development may not yet be in the published desktop or package launchers.
The Python launcher exposes print-soc, print-at-soc, and psoc.
# Python launcher (Python 3.8+)
python3 -m pip install print-at-soc
print-soc --install
print-socnpm publication has ended; use PyPI or GitHub Releases for current versions.
If migrating from the global npm launcher, remove it with npm uninstall -g print-at-soc before installing the Python launcher to avoid command-name conflicts.
The launcher installs the desktop separately. The Rust system-printing path does not require Python. See installation, update and recovery details.
- Open Print@SoC and select your SoC server, such as
stuorstf. - Connect with your SoC account. Saving the password in the operating system’s credential store is optional.
- Choose Browse Files or drop a document into the workspace.
- Review the converted PDF, choose an accessible printer, and check paper size, copies and binding edge.
- Submit once, then follow the job in Jobs. History is ordered newest first.
The printer catalogue is filtered against the connected server’s queues. A listed printer may still have room-access restrictions. Check the printer catalogue sources before choosing an unfamiliar location.
| Task | Support and requirements |
|---|---|
| Preview and print PDF | Imported documents are retained as local copies; preview and submission use the same prepared PDF. |
| Print images | Static PNG, JPEG, WebP and BMP; transparency is composited onto white paper. |
| Print slides and Office files | PPT/PPTX/ODP, DOC/DOCX/ODT and XLS/XLSX/ODS, plus RTF/TXT/CSV, require local LibreOffice. Review conversion before printing. |
| Arrange pages | Page selection, n-up and booklet layout require pdfjam with TeX Live. |
| Print from another application | Optional macOS/Linux CUPS printer with a standalone Rust backend and user-session service. See system printer setup. |
| Track jobs | Queue association uses lpq -l, the account and the unique submitted filename; fresh, complete snapshots provide the number of jobs ahead. |
| Automate | CLI launchers and a bundled stdio MCP server; real print submission requires explicit confirmation. |
Long-edge and short-edge choices are retained in job settings. Physical binding depends on the remote queue and its lpr implementation. A live macOS test through Word, the installed Rust driver and psc111 verified A4 short-edge duplex output, with the user confirming the physical result. The system job appeared in GUI history and preview, and queue tracking advanced from printing to left queue. This result is specific to that printer and environment. See the live validation record. See the interface investigation and live test record.
- Submitted / awaiting confirmation: the submission was accepted, but its outcome is not yet established.
- Queued / printing: the job was matched in the remote queue. A reliable snapshot can show how many jobs are ahead; stale or unavailable information is identified explicitly.
- Left queue: the job is no longer in a successfully queried queue. This does not prove that paper physically emerged.
- Output confirmed: the user has confirmed the physical output.
A failed query does not mark a job completed. An interrupted submission that may already have reached the server is reconciled instead of automatically printed again.
print-soc self update --check
print-soc self update
print-soc self update --rollback
print-soc self uninstall --dry-run
print-soc self uninstallThe uninstall wizard previews owned components and offers data retention or cleanup. Updates verify downloads and retain a previous installation for recovery. macOS/Linux support opt-in installation on CLI launch; Windows uses its native installer and has different rollback limits.
CLI launch-time checks are not a background updater. Opening the desktop directly does not invoke that check. Python/npm package upgrades and installed CUPS service refreshes are separate operations. Read the maintenance guide for automatic-update settings, recovery and purge options.
The desktop and native printing service share one account identity. When enabled, saved passwords live in macOS Keychain, Windows Credential Manager or Linux Secret Service; they are not stored in the account JSON or returned to the webview. A locked credential store produces an error rather than a plaintext fallback.
Documents are converted locally, then transferred to the selected SoC server for printing. Imported PDFs and job history remain locally for preview and recovery. Review account storage and document handling before using a shared computer.
Desktop document → local PDF preparation ──────────────┐
├→ Rust print service → SSH → SoC lpr → printer
Application Print → local CUPS → Rust backend → PDF ───┘
↑
queue tracking via lpq -l
The React interface and Rust backend are packaged with Tauri. The optional CUPS integration uses a standalone Rust executable and a login-session service; it does not require Python in the printing path. Windows system-driver integration is not provided by this CUPS installer.
For a document such as assignment.pdf, the workflow has four responsibilities:
- Prepare: retain a local copy, convert supported input formats to PDF, and apply requested layout transformations before submission. Native CUPS output may already contain page selection, orientation and n-up; those transformations must not be applied twice.
- Submit: transfer the prepared document under a unique attempt filename and invoke the selected server queue through SSH. A receipt records submission progress so an interrupted operation can be reconciled without blindly resending it.
- Observe: inspect
lpq -l, associate the account and unique filename with a queue job, and retain its remote identifier. A complete, fresh queue snapshot can establish how many jobs precede it; a failed or partial query cannot. - Reconcile: update local history from the available evidence. Queue departure and user-confirmed paper output remain distinct outcomes.
For context, the remote command interface used in the documented SoC investigation is:
# On the SoC Unix server; submitting consumes a real print job.
# Replace both placeholders with an accessible queue and a prepared PDF.
lpr -P <queue> <prepared-document.pdf>
# Read the queue, including long-format job and filename information.
lpq -l -P <queue>These commands explain the server boundary; the application also manages credentials, file transfer, local persistence and interrupted submissions. They are not a replacement installation script.
The desktop interface handles document selection, preview and settings. Rust owns SSH access, document preparation and the job lifecycle. The native CUPS backend accepts the OS-rendered document and passes it to a user-session service, which uses the shared account and persists system jobs for the GUI. Package launchers handle distribution and maintenance separately from the native printing path.
This separation serves a specific recovery requirement: closing the GUI must not make a system-originated job disappear from history, and a desktop restart must not turn an uncertain submission into an automatic duplicate print.
The remote SoC tools are not assumed to be CUPS-compatible simply because their commands share names. Protocol details, queue matching and observed limitations are recorded in the printing interface investigation.
Install Node.js/npm, Rust and the Tauri platform prerequisites. Read VERSIONING.md and install the pinned Tide CLI before building: scripts/version.py owns every version projection.
git clone https://github.com/Qingbolan/Print-SoC.git
cd Print-SoC/app
npm ci
npm run tauri:dev# From app/
npm run check
cargo test --manifest-path src-tauri/Cargo.toml --lib
npm run tauri:build| Location | Responsibility |
|---|---|
| app/src | React workspace, preview, settings and job views |
| app/src-tauri/src | Rust document pipeline, SSH, job lifecycle and native integration |
| release | Python/npm launchers and distribution tooling |
| plugins/print-soc | Codex plugin scaffold and MCP registration |
| VERSIONING.md | Tide versions and shared release receipts |
Questions or something not working? Check the user guide, or open an issue. Include your OS, app version and what happened; leave out passwords and private documents.
PRs are welcome—whether it’s a bug fix, clearer docs or a better printing workflow. See AGENTS.md for development guidelines, and tell us how you tested your change.
Made by Silan Hu. Find me at silan.tech or email silan.hu@u.nus.edu. I’d love to hear whether this helped you print your first assignment at SoC.


