Set up the printing platform and local agent

Workspace centrally manages templates, print policies, and jobs. The local nucleus-print-agent retrieves pre-rendered artifacts over HTTPS and submits them to printers on the local network. Stampede is no longer needed for this workflow.

This guide covers a Linux installation. When complete, Workspace, agent, station, and printer are connected without opening inbound access to the local network.

Before you start

You need:

• a Linux machine that can reach Workspace over HTTPS and the local printers;
• a current nucli with an authenticated tenant profile;
• the agent source package matching the Workspace version, plus Rust and Cargo;
• root access for the system account, directories, and systemd service;
• an existing CUPS/IPP queue or raw TCP address;
• a TLS certificate and its protected TLS key file for the local administration interface.

Check the tenant, permissions, and current printing status first:

nucli --tenant <tenant> whoami --scopes
nucli --tenant <tenant> printing status
nucli skills show printing

printing status reports missing formats, policies, agents, or stations. Every nucli printing command uses the authenticated, tenant-bound Workspace API.

1. Build the agent and create the system account

Extract the version-matched source package into a dedicated working directory and run the build there:

cd <extracted-agent-source-package>
cargo build --release --locked

Install the system account, binary, service unit, and directories:

sudo useradd --system --home-dir /var/lib/nucleus-print-agent \
  --shell /usr/sbin/nologin nucleus-print-agent
sudo install -m 0755 \
  target/release/nucleus-print-agent \
  /usr/bin/nucleus-print-agent
sudo install -m 0644 \
  nucleus-print-agent.service \
  /etc/systemd/system/nucleus-print-agent.service
sudo install -d -o root -g nucleus-print-agent -m 0750 \
  /etc/nucleus-print-agent
sudo install -d -o nucleus-print-agent -g nucleus-print-agent -m 0750 \
  /var/lib/nucleus-print-agent

If the system account already exists, skip only the useradd command. Do not change an existing UID or group assignment.

2. Register the agent securely in Workspace

Create a private handoff directory as the normal user. The token output path must be new:

install -d -m 0700 "$HOME/.config/nucleus-print-agent-bootstrap"
nucli --tenant <tenant> printing agent register \
  --name <site-agent> \
  --token-output "$HOME/.config/nucleus-print-agent-bootstrap/agent.token"

nucli prints the agent ID and file path, but never the token. It creates the file with mode 0600 and refuses to overwrite an existing file. Note the returned agent ID for the configuration.

Install the token for the service account:

sudo install -o nucleus-print-agent -g nucleus-print-agent -m 0600 \
  "$HOME/.config/nucleus-print-agent-bootstrap/agent.token" \
  /etc/nucleus-print-agent/agent.token

If the handoff file is lost or was exposed, do not register a second agent. Rotate the token after explicit approval:

nucli --tenant <tenant> printing agent rotate-token <agent-id> \
  --token-output "$HOME/.config/nucleus-print-agent-bootstrap/new-agent-token"

Rotation invalidates the previous token.

3. Configure the local administrator password and TLS

Generate the password hash without placing the password in a command argument:

systemd-ask-password "Local print-agent administrator password" \
  | nucleus-print-agent hash-password

Install a certificate trusted by the administration devices and its protected TLS key file. Only the service account may read the key:

sudo install -o root -g root -m 0644 <tls-certificate> \
  /etc/nucleus-print-agent/tls.crt
sudo install -o nucleus-print-agent -g nucleus-print-agent -m 0600 \
  <private-tls-key> /etc/nucleus-print-agent/tls.key

The local interface binds to 127.0.0.1 by default. Bind it to another local address only when it must be reachable from a trusted administration network. Never expose it publicly.

4. Configure the station and print targets

Copy the example into the private handoff directory and edit that copy first:

install -m 0600 config.example.yaml \
  "$HOME/.config/nucleus-print-agent-bootstrap/config.yaml"

Set at least:

• cloud.baseUrl: the Workspace HTTPS origin;
• cloud.agentId: the agent ID returned during registration;
• adminPasswordHash: the generated Argon2 hash;
• stations[].key: a stable key for the workstation;
• targets[].key: the semantic target, such as variant.label or shipping.label;
• outputFormat and, for ZPL, the correct dpi value;
• either a CUPS queue or a local raw TCP address for each target.

Install the completed configuration with private permissions:

sudo install -o nucleus-print-agent -g nucleus-print-agent -m 0600 \
  "$HOME/.config/nucleus-print-agent-bootstrap/config.yaml" \
  /etc/nucleus-print-agent/config.yaml

The Linux agent supports two local drivers:

• cups submits PDF normally and printer-language artifacts in raw mode to a CUPS/IPP queue. Media, tray, and other options remain local.
• raw_tcp sends the artifact directly to a local TCP address, commonly port 9100.

Workspace receives neither queue names nor printer addresses. The cloud sees only station, semantic target, output format, resolution, priority, and status.

5. Check the configuration and start the service

Run the check as the same system account used by the service:

sudo -u nucleus-print-agent nucleus-print-agent check \
  --config /etc/nucleus-print-agent/config.yaml

The check validates the configuration, administrator password hash, token assignment, and TLS files. It makes no network request and submits no print job. Start the service only after it reports Configuration valid:

sudo systemctl daemon-reload
sudo systemctl enable --now nucleus-print-agent.service
sudo journalctl -u nucleus-print-agent.service -n 50 --no-pager

Remove the handoff token only after the check succeeds with the installed copy:

rm "$HOME/.config/nucleus-print-agent-bootstrap/agent.token"

6. Verify the connection and warehouse assignment

Once running, the agent reports its stations and capabilities to Workspace:

nucli --tenant <tenant> printing status
nucli --tenant <tenant> printing list stations

Assign a station to a warehouse when needed:

nucli --tenant <tenant> printing station assign <station-id> \
  --warehouse <warehouse-id>

The setup is operational when printing status reports at least one renderable format, an active print policy, an active agent, and an online station with an online capability.

Keep templates independent of printer vendors

A logical template defines purpose, data contract, and dimensions. Separate renderings define content locale, output format, and optional resolution. Each rendering has immutable revisions.

There is deliberately no universal printer-language translator. The same logical template can have a 203 dpi ZPL rendering and later gain a separate rendering for another printer language. A format name does not make ZPL source portable. Each additional language needs a matching validator and renderer in Workspace.

In Inventory > Printing, create the logical template first. Then add a rendering and select content locale, output format, and resolution. ZPL placeholders are permitted only inside ^FD fields, preventing dynamic values from injecting control commands. Persistent configuration, network, storage, and quantity commands remain blocked; copy count belongs to the print job.

A print policy connects source type, template, semantic target, locale, and default quantity. Policies may be tenant-wide or warehouse-specific. Existing shipment labels can be sent through the same agent as unchanged PDF artifacts.

Troubleshooting

Current limits

• The supplied agent currently supports Linux with CUPS/IPP and raw TCP.
• A Windows service and Windows spooler are planned but not implemented. They will be added behind the same local driver boundary without changing the cloud API or template model.
• The current scope does not include an image preview or drag-and-drop designer.
• submitted confirms acceptance by CUPS or raw TCP. completed remains reserved for drivers with reliable completion acknowledgement.