What this is about
With Reverse SSH, you establish an outgoing, encrypted connection (tunnel) to PaperOffice yourself. No port forwarding in the router is required. PaperOffice AI then stores the encrypted documents of a Workspaces on your NAS.
Create the storage location before creating the Workspace. The storage mode of a Workspaces cannot be changed after creation.
Step 1: Prepare NAS (example: QNAP)
The menus in QTS may vary slightly depending on the QTS version.
- Create a dedicated shared folder, for example
paperoffice, not the folder belonging to PaperOffice Classic or MariaDB. - Enable SSH and SFTP under Control Panel › Network & File Services › Telnet / SSH.
- Under "Edit Access Permissions," enter the NAS user account you will use to log in. If this user is not listed, NAS will reject the SSH login attempt.
- Install Container Station (Docker). You may keep the suggested shared folder for containers as is.
Synology: Container Manager, enable User Home Service, add user to the administrators group. ASUSTOR: Docker Engine. UGREEN: Docker.
Step 2: Create storage in PaperOffice AI
- Open Document AI › Storage Mounts and click on Add Storage Mount.
- Fields marked with a red asterisk (*) are mandatory.
- Name for this Storage Mount: Choose any name.
- Payment reference: Use as BYOS-Storage.
- Connection Type: Connect local folder via Reverse-SSH.
- Your NAS: Select QNAP. The app will then suggest
/share/paperoffice(Synology, ASUSTOR, UGREEN:/volume1/paperoffice). - Local SSH user: Your user account on the NAS. This user must be a member of the administrators group.
- Local folder: The full path to the folder. On QNAP, use
/share/<Name des Freigabeordners>. Do not include quotation marks, backslashes, or* ? [ ]. Neither the folder nor the user can be changed later. - Encryption Password and Confirm Password: At least 16 characters, or click Generate secure password (key icon) to generate one.
- Click on Download as .txt. Only after this step can the storage be created. Store the file securely: without the password, there is no recovery option.
- Check the confirmation box and save.
Step 3: Select the correct setup block
After saving, the window Reverse-SSH setup opens with your Tunnel alias. At the top, select the variant:
- NAS with Docker: a block that starts a small tunnel container. This is the correct choice for QNAP with Container Station.
- NAS without Docker: Block 1 via SSH once, Block 2 in the autostart.
- Linux / macOS and Windows: for computers.
Copy the block with Copy setup. For NAS without Docker, each of the two blocks has its own button.
Step 4: Log in to the NAS and paste the block
For example, on Windows using PuTTY (labels may vary slightly depending on the version):
- Enter the IP address of your NAS in the home network under Host, port
22, and open the connection. - Log in with the NAS user from step 2. You will not see any characters when entering the password; this is normal.
- If QNAP displays a console menu after logging in (e.g., "Console Management"), exit it to return to the normal command line, typically using
Qand thenYdepending on your QTS version. - Right-click in the window to paste the block. Then press Enter.
On Mac: Open the Terminal application, then use ssh <Benutzer>@<IP-Adresse des NAS>.
The block belongs only in this window on the NAS. The NAS requires internet access: the tunnel is established from your NAS outward, and the container loads a small Linux package upon startup.
Step 5: Test the connection
- Open the storage under Storage Mounts with Edit.
- Click on Test Connection (only possible after saving).
- Success: "Tunnel active: NAS reachable and folder writable." Afterward, create the Workspace using Own Storage (BYOS).
If the test reports a rejected login, check the NAS user and access list from step 1. Then re-enter the setup as the registered NAS user and test again.
What the trace shows
In the overview, Test Connection starts the trace with a map for PaperOffice. For Reverse SSH, the destination is the tunnel server of PaperOffice, not your NAS. The location details refer to network nodes along this path, not the storage location of your files.
After a restart
The tunnel container starts automatically after every restart as soon as Docker is running. If the connection drops, it reconnects after 10 seconds. Without Docker, block 2 in the autostart ensures this.
Security: The setup block contains a private key
The block contains a private key and registers it as the login credential for your NAS user. Anyone with access to this block can impersonate your tunnel and, where the SSH service of your NAS is accessible to them, log in as your NAS user. Your encryption password is not included in the block.
- Never paste the block into chats, AI assistants, emails, or support tickets.
- Support does not need the block. Instead, provide the error message from the test.
Wenn es doch passiert ist:
- Delete the message where possible.
- There is no "Regenerate Key" button. When editing, the key remains unchanged.
- If Workspace is not yet using storage: Delete the Storage Mount. PaperOffice removes the key from the tunnel server; files on the NAS remain. Create new storage (new key, new tunnel alias) with the same encryption password or an empty folder.
- Remove the old key from the NAS: In the
.sshfolder of your NAS user, delete the line inauthorized_keysending with "PaperOffice" and the old tunnel alias, as well as the filepaperoffice_<alter Tunnel-Alias>. With Docker: Delete the old container in your Docker interface (QNAP: Container Station) whose name starts withpaperoffice-tunnel-. Without Docker: In the same folder.ssh, delete the scriptpaperoffice_tunnel_<alter Tunnel-Alias>.shand remove the old entry from the autostart. - If an Workspace is already using storage, it cannot be deleted. In this case, create a ticket in the app under Support and state that the key has been exposed externally. Do not include the block.