Royal TS/TSX

Launch SSH, RDP, SFTP, and database sessions with secrets protected by your Keeper vault.

Use Keeper Secrets Manager (KSM) with Royal TS (Windows) and Royal TSX (macOS) to connect to servers and databases. Vault records appear as dynamic credentials; secrets are retrieved from Keeper when you connect.

This page describes how to install and use the Keeper KSM (Python) Dynamic Folder, which uses the official Python package keeper-secrets-manager-core to communicate with Keeper.

---

Overview

What it does	Imports Server and Database records from your Keeper vault into a Royal Dynamic Folder so you can link connections to Keeper-backed credentials.
Where secrets live	Passwords and other sensitive fields remain in Keeper. Royal TS(X) resolves them at connection time via KSM.
Platforms	Royal TS v7+ on Windows; Royal TSX v6+ on macOS.
Authentication	A KSM configuration file tied to a Secrets Manager application in your Keeper organization.

This integration requires Keeper Secrets Manager and the KSM client SDK libraries.

What you can do

• Use Server records for SSH, SFTP, and RDP workflows by creating the connection in Royal and selecting a matching dynamic credential.

• Use Database records to open MySQL, PostgreSQL, Microsoft SQL Server, Oracle, MongoDB, or Redis client sessions from a generated connection tree. You configure paths to database client executables on the machine where Royal runs; the database server addressed in each record can be local or remote (host and port come from Keeper).

• Configure KSM with a JSON or Base64 file from the Vault on both platforms, or additionally with an INI file from ksm init on macOS.

---

Requirements

Requirement	Details
Keeper subscription	Access to Secrets Manager (Consumer, Business, or Enterprise per your organization’s plan).
KSM application	A Secrets Manager application in the Keeper Admin Console, with vault records shared to that application. See the Secrets Manager Quick Start Guide.
Royal TS (Windows)	Version 7 or later.
Royal TSX (macOS)	Version 6 or later.
Python	3.9 or later (3.13 recommended). Must be the same Python executable that Royal TS(X) uses to run Dynamic Folder scripts.
Python package	keeper-secrets-manager-core installed into that Python environment.
Configuration file	A JSON or Base64 file downloaded from the Vault (Windows and macOS), or an .ini from ksm init (macOS only).

Optional — only if you use Keeper Database records

What you install	The database client programs (for example mysql, psql, sqlcmd, mongosh, redis-cli, sqlplus) on the same computer where Royal TS or Royal TSX is installed — not on the database server.
What you configure in Royal	In the Dynamic Folder Custom Properties, the MySQL Path, PostgreSQL Path, and so on point to those local client executables. Set a path only for each database engine you actually use (for example configure MySQL Path only if you have MySQL Database records).
Where the database runs	The database server can be on this machine or anywhere on the network (cloud, datacenter, another office). Host and port in each Keeper Database record identify that server; the local client connects to them over the network.

If you use only Server records (SSH, RDP, SFTP) and no Database records, you do not need database clients or these paths.

---

Before you begin

1. Create or use an existing KSM application, then obtain a config file: download JSON or Base64 from the Vault (Windows and macOS), or run ksm init to create an INI file (macOS only). See Secrets Manager Quick Start Guide.

2. Share vault records with that KSM application. Records that are not shared will not appear or will fail to resolve at connection time.

3. Download the Dynamic Folder package Keeper KSM (Python).rdfx from the Royal Applications Toolbox.

---

Install on Windows (Royal TS)

1. Install Python

Install Python 3.9+ (3.13 recommended). Use the build that Royal TS will call for scripts.

2. Install the KSM Python package

Royal TS uses the interpreter configured under File → Options → Plugins (script interpreter). Install the package with that python.exe:

"C:\Path\To\Python\python.exe" -m pip install keeper-secrets-manager-core

Replace the path with the exact interpreter shown in Royal TS.

3. Add a KSM configuration file on disk

In Keeper Vault, go to Secrets Manager → Add Device → Configuration File → Download. This gives you a JSON or Base64 config file. Save it to a known location on your PC (for example C:\Users\YourName\keeper-config.json).

4. Create or open a Royal document

Create a new document and save it (for example My Connections.rtsz).

5. Import the Dynamic Folder

File → Open → Import → choose file type Dynamic Folder → select Keeper KSM (Python) → OK.

6. Set Custom Properties

Right-click Keeper Secrets Manager (Python) → Properties → Custom Properties:

• KSM Config Path (Windows) — Full path to your KSM config file (.json or .base64). Example: C:\Users\YourName\keeper-config.json.

Database client paths (only if you use Database records): Each path is the client tool on this Windows PC. The remote host and port of the database are not entered here—they come from each Keeper Database record. Set only the rows for engines you use.

Custom property	Example
MySQL Path (Windows)	C:\Program Files\MySQL\MySQL Server 8.0\bin\mysql.exe
PostgreSQL Path (Windows)	C:\Program Files\PostgreSQL\16\bin\psql.exe
MSSQL Path (Windows)	C:\Program Files\Microsoft SQL Server\Client SDK\ODBC\170\Tools\Binn\SQLCMD.EXE
Oracle Path (Windows)	C:\oracle\instantclient\sqlplus.exe
MongoDB Path (Windows)	C:\Program Files\MongoDB\mongosh.exe
Redis Path (Windows)	C:\Program Files\Redis\redis-cli.exe or C:\Program Files\Memurai\memurai-cli.exe

7. Reload the folder

Right-click the Dynamic Folder → Reload. Expand the tree to confirm that credentials appear.

Optional: install database clients (Windows)

These programs run on your PC so Royal can launch them; they connect to local or remote databases per the Host field in each Keeper record. Install only the clients you need, using each vendor’s official Windows installer or package:

Engine	Typical approach
MySQL	MySQL Installer (client tools / shell) or a standalone MySQL Shell build — use the resulting mysql.exe path in Custom Properties.
PostgreSQL	Windows installer — includes psql.exe (often under C:\Program Files\PostgreSQL\<version>\bin\).
Microsoft SQL Server	sqlcmd and ODBC tools from Microsoft (often under ...\Microsoft SQL Server\Client SDK\ODBC\...\Binn\ — match your installed version).
MongoDB	mongosh for Windows.
Redis	redis-cli or Memurai’s memurai-cli.exe (same -h / -p / -a / --user flags). Set Redis Path to your actual redis-cli.exe or memurai-cli.exe.
Oracle	Oracle Instant Client (or full client) — sqlplus.exe path depends on your install folder.

Point Custom Properties at the exact .exe paths after installation (see the examples in step 6).

---

Install on macOS (Royal TSX)

1. Install Python

Install Python 3.9+ (3.13 recommended).

2. Install the KSM Python package

Royal TSX selects Python under Settings → Plugins → Python (or Settings → Python), often via a version menu. Install keeper-secrets-manager-core into that interpreter—the same one you get from which python3 in Terminal if that matches your selection:

python3 -m pip install keeper-secrets-manager-core

Verify:

python3 -c "import keeper_secrets_manager_core; print('ok')"

If Homebrew Python returns externally-managed-environment, install with your actual Python path, for example:

/opt/homebrew/bin/python3 -m pip install keeper-secrets-manager-core --break-system-packages

Or use a virtual environment and point Royal TSX to that Python if your version supports it.

3. Add a KSM configuration file on disk

There are two supported ways to obtain a config file. Use one only:

• Option A — Configuration file from the Vault (JSON or Base64) — Vault → Secrets Manager → Add Device → Configuration File → Download. (JSON is recommended on macOS.)

• Option B — INI file from the Keeper CLI — Run ksm init default --token YOUR_TOKEN after obtaining a token (Quick Start), producing an .ini such as keeper.ini.

4. Create or open a Royal document

File → New Document → File → Save.

5. Import the Dynamic Folder

File → Import → Dynamic Folder → Keeper KSM (Python) → Import.

6. Set Custom Properties

Right-click Keeper Secrets Manager (Python) → Properties → Custom Properties:

• KSM Config Path (macOS) — Full path to one file: .json, .base64, or .ini. Examples: /Users/yourname/keeper-config.json or /Users/yourname/keeper.ini.

Database client paths (only if you use Database records): Each path is the client tool on this Mac. The database host and port are defined in each Keeper Database record, not in Custom Properties. Set only the rows for engines you use.

Custom property	Example
MySQL Path (macOS)	/opt/homebrew/opt/mysql-client/bin/mysql
PostgreSQL Path (macOS)	/opt/homebrew/opt/libpq/bin/psql
MSSQL Path (macOS)	/opt/homebrew/opt/mssql-tools18/bin/sqlcmd
Oracle Path (macOS)	/usr/local/bin/sqlplus
MongoDB Path (macOS)	/opt/homebrew/bin/mongosh
Redis Path (macOS)	/opt/homebrew/bin/redis-cli

7. Reload the folder

Right-click the Dynamic Folder → Reload (or press Cmd+R).

Optional: install database clients (macOS)

These programs run on your Mac so Royal can launch them; they connect to local or remote databases per the Host field in each Keeper record. Many users install CLIs with Homebrew, for example:

brew install mysql-client libpq mongosh redis
brew tap microsoft/mssql-release https://github.com/Microsoft/homebrew-mssql-release
brew install mssql-tools18

Oracle Instant Client paths depend on your installation.

---

Use Server records (SSH, SFTP, RDP)

Server records supply host, port, login, and password. You create the connection object in Royal (Terminal, File Transfer, or Remote Desktop) and bind it to the dynamic credential that corresponds to that record.

For SSH, choose a credential from the server credential group exposed by the Dynamic Folder (not SSH-key-only listings, unless your deployment documents otherwise).

Example: SSH

Keeper — Server record

Field	Example
Title	Production web
Login	deploy
Password	(in vault)
Host	203.0.113.10
Port	22

Royal TS / Royal TSX

1. Reload the Dynamic Folder.

2. Add → Terminal.

3. Set Connection type to SSH Connection; Computer name 203.0.113.10; Port 22.

4. On Credentials, choose Specify a credential name and select the matching Keeper dynamic credential.

5. Save and connect.

Example: SFTP

Use the same Server record shape as SSH. Install the File Transfer plugin (Settings → Plugins). Then Add → File Transfer → SFTP, set host/port, and attach the same style of dynamic credential.

Example: RDP

Keeper — Server record

Field	Example
Title	Finance workstation
Login	CORP\jdoe
Password	(in vault)
Host	192.168.50.100
Port	3389

Install the Remote Desktop plugin. Add → Remote Desktop, enter host and port, attach the credential.

The destination Windows edition must allow inbound Remote Desktop (Pro, Enterprise, Education, or Windows Server). Windows 11/10 Home does not host the RDP server role.

---

Use Database records

Database records drive automatic connection entries under databaseCredentials in the Dynamic Folder. After you set database CLI paths and reload, open the subfolder for your engine (for example MySQL Connections) and double-click an entry. Royal starts the client on your workstation; that client connects to the host and port stored in the Keeper record (same machine or remote—your network path must allow access, for example VPN or firewall rules).

Set the database type in Keeper

When you create or edit a Database record in the vault, set the Type field (in the standard Keeper Database template this is the field used to identify the engine). The integration reads that value and places the record under the matching folder (MySQL Connections, PostgreSQL Connections, and so on).

Use one of the following Type values (case is ignored). Common synonyms are accepted:

You want	Examples of valid Type text
MySQL	MySQL, MariaDB
PostgreSQL	PostgreSQL, Postgres, PG
Microsoft SQL Server	MSSQL, SQL Server, Microsoft SQL Server
Oracle	Oracle, OracleDB
MongoDB	MongoDB, Mongo
Redis	Redis

If Type is empty or does not match any supported value, the integration treats the record as MySQL. Always set Type explicitly for non-MySQL databases.

Each example uses the same Keeper Database record shape. Host and Port are whatever your database listens on (local or remote). After Custom Properties include the matching client path, reload the Dynamic Folder and open databaseCredentials → the folder for that engine (for example MySQL Connections, PostgreSQL Connections). On Windows, database clients usually launch via External Application; on macOS, a helper script runs the client in a terminal session.

Example: MySQL

Field	Example
Record type	Database
Type	MySQL
Title	Staging MySQL
Login	appuser
Password	(in vault)
Host	127.0.0.1
Port	3306

Set MySQL Path for your OS in Custom Properties, reload the Dynamic Folder, then open databaseCredentials → MySQL Connections.

Example: PostgreSQL

Field	Example
Record type	Database
Type	PostgreSQL
Title	Staging Postgres
Login	postgres (or your DB user)
Password	(in vault)
Host	127.0.0.1
Port	5432

Set PostgreSQL Path for your OS in Custom Properties, reload the Dynamic Folder, then open databaseCredentials → PostgreSQL Connections. On Windows, psql runs via cmd /k so the console stays open.

Example: Microsoft SQL Server

Field	Example
Record type	Database
Type	MSSQL
Title	Local SQL
Login	sa (or your SQL login)
Password	(in vault)
Host	127.0.0.1
Port	1433 (or your TCP port — see hint)

Set MSSQL Path for your OS in Custom Properties, reload the Dynamic Folder, then open databaseCredentials → MSSQL Connections.

Use 127.0.0.1 instead of localhost if connections time out (IPv6 resolution). SQL Express often uses a non-default port — check SQL Server Configuration Manager → TCP/IP → IPAll for TCP Port or TCP Dynamic Port; put that value in Port. Current sqlcmd (ODBC Driver 18) encrypts by default; the integration passes -C -No (trust server certificate, optional encryption), similar to Trust server certificate in SSMS. For SQL logins, the server must use mixed mode (SQL + Windows authentication).

Example: Oracle

Field	Example
Record type	Database
Type	Oracle
Title	Local XE
Login	system (or your app user)
Password	(in vault)
Host	127.0.0.1 (or remote listener host)
Port	1521

Set Oracle Path to sqlplus (or your installed path) in Custom Properties, reload the Dynamic Folder, then open databaseCredentials → Oracle Connections. The integration uses Easy Connect …/XEPDB1 by default (Oracle 21c XE PDB). Other SERVICE_NAME values (XE, ORCL) may require editing the Dynamic Folder script. On Windows, sqlplus runs via cmd /k.

Example: MongoDB

Field	Example
Record type	Database
Type	MongoDB
Title	Dev Mongo
Login	(empty for no auth) or your user
Password	(in vault), or leave empty if the server has no auth
Host	127.0.0.1
Port	27017

Set MongoDB Path to mongosh in Custom Properties, reload the Dynamic Folder, then open databaseCredentials → MongoDB Connections. On Windows, mongosh runs via cmd /k.

Example: Redis

Field	Example
Record type	Database
Type	Redis
Title	Local Memurai
Login	(empty for no auth) or ACL username
Password	(empty for no auth) or (in vault)
Host	127.0.0.1
Port	6379

Set Redis Path to redis-cli.exe or memurai-cli.exe in Custom Properties, reload the Dynamic Folder (reload after changing Login / Password so the script can detect auth), then open databaseCredentials → Redis Connections. No auth: leave Login and Password empty. Requirepass: set Password only. ACL: set Login and Password. On Windows, the client runs via cmd /k.

---

Feature summary

Workflow	Windows (Royal TS)	macOS (Royal TSX)
SSH / SFTP / RDP	Manual connection + dynamic credential	Same
Database CLIs	Auto-listed connections, double-click	Same

---

Troubleshooting

Python and the Dynamic Folder

What you see	Likely cause	What to do
ImportError or prompt to run pip install keeper-secrets-manager-core	Package installed for a different Python than Royal uses	Install with the exact python.exe or python3 from Royal’s settings. Confirm: python3 -c "import keeper_secrets_manager_core" (macOS) or the Windows path from File → Options → Plugins.
externally-managed-environment (macOS)	PEP 668 restriction on system Python	Use --break-system-packages for that interpreter, or a venv if Royal TSX can use it.

KSM configuration and vault access

What you see	Likely cause	What to do
KSM Config Path is not configured	Missing Custom Property	Set KSM Config Path (Windows) or KSM Config Path (macOS).
Config file not found	Wrong path or permissions	Verify the file path and that your user can read the file.
Record not found	Record not shared with the KSM application	In Keeper, share the record with the Secrets Manager application tied to your config file.

Database clients

What you see	Likely cause	What to do
No such file or directory	Database executable path missing or wrong	Set the correct MySQL / PostgreSQL / … Path in Custom Properties and reload.
Connection refused	Service down or network	Confirm the database is listening and reachable on the host/port in the Keeper record.
MSSQL login timeout / server not found	Wrong host/port or TCP disabled	Use 127.0.0.1. For Express, enable TCP/IP and set Port to the value from Configuration Manager → TCP/IP → IPAll (often not 1433).
MSSQL certificate / SSL errors	ODBC 18 + self-signed cert	Reload the latest Dynamic Folder (-C -No). Manual sqlcmd: add -C -No; SSMS: Options → Trust server certificate.
MSSQL Login failed (SQL user)	Windows-only auth or disabled login	Enable mixed mode in SSMS → server Properties → Security, restart SQL Server; ensure the login exists and is enabled.
Oracle no listener / timeout	Listener host or stopped service	Use Host that matches listener (often 127.0.0.1 locally). Start Oracle listener + DB services; align LOCAL_LISTENER with listener.ora if you changed from a LAN-only IP.
Oracle ORA-12514	Service not registered	ALTER SYSTEM REGISTER as SYSDBA; confirm lsnrctl status lists xepdb1 / XE.
Redis AUTH errors	Password set when server has none	Clear the password in the Keeper record.

SSH on macOS (local testing)

What you see	Likely cause	What to do
Connection closed or repeated auth failure to this Mac	Remote Login restrictions	System Settings → Sharing → Remote Login → Options — allow your user or All users.

Remote Desktop

What you see	Likely cause	What to do
Cannot RDP to a Home edition PC	No RDP server	Use Pro or higher, Windows Server, or another target.

---

Security and compliance

• Secrets remain under Keeper control; resolved dynamic credentials are not written into the Royal document as stored passwords.

• Protect the KSM configuration file as you would any secret with access to your vault. Restrict file permissions and device access according to your organization’s policy.

How database passwords are passed

On macOS, the helper script passes passwords to database clients via environment variables or restricted temp files rather than command-line arguments where the client supports it:

Client	Method
MySQL	MYSQL_PWD environment variable
PostgreSQL	PGPASSWORD environment variable
Microsoft SQL Server	SQLCMDPASSWORD environment variable
Oracle	Mode-0600 temp SQL file with sqlplus -L /nolog @file; file removed on exit
MongoDB	URI passed as argument (mongosh has no native env-var mechanism)
Redis	REDISCLI_AUTH environment variable

On Windows, database connections use External Application with Royal credential tokens ($$EffectivePassword$$). Royal substitutes values into the command line at launch time. This means:

• Resolved secrets may be visible in process listings — this is inherent to the External Application model.

• Passwords containing &, %, ", or ! may break command-line parsing and cause authentication failures. If you encounter this, consider updating the Keeper record password to avoid these characters for database connections launched via External Application.

macOS helper file safety

• Launcher and helper scripts under ~/.config/royal-keeper/ are written using atomic writes (temp file → chmod → replace) with directory permissions set to 0700.

• All arguments interpolated into launcher scripts are escaped with shlex.quote() to prevent shell injection from paths containing quotes or metacharacters.

Base64 configuration cleanup

• When using a .base64 KSM config file, the decoded content is written to a mode-0600 temp file, used for the KSM session, and deleted when the script finishes (via a finally block).