# Royal TS/TSX

<figure><img src="/files/czhhCm3ebamTdzTk1Tx3" alt=""><figcaption></figcaption></figure>

Use **Keeper Secrets Manager (KSM)** with [Royal TS](https://www.royalapplications.com/ts/win) (Windows) and [Royal TSX](https://www.royalapplications.com/ts/mac) (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.                                                      |

{% hint style="info" %}
This integration requires **Keeper Secrets Manager** and the KSM client SDK libraries.
{% endhint %}

#### 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](/en/keeperpam/secrets-manager/quick-start-guide.md). |
| **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](/en/keeperpam/secrets-manager/quick-start-guide.md).
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](https://github.com/royalapplications/toolbox/tree/master/Dynamic%20Folder/Keeper).

***

### 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`:

```cmd
"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**.

<figure><img src="/files/FV9zXyrwQy4BnKs32J64" alt=""><figcaption></figcaption></figure>

#### 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`.

<figure><img src="/files/FOsIXwbzIl0HfDPTla6D" alt=""><figcaption></figcaption></figure>

**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](https://dev.mysql.com/downloads/installer/) (client tools / shell) or a standalone **MySQL Shell** build — use the resulting `mysql.exe` path in Custom Properties.                        |
| **PostgreSQL**           | [Windows installer](https://www.postgresql.org/download/windows/) — includes `psql.exe` (often under `C:\Program Files\PostgreSQL\<version>\bin\`).                                                          |
| **Microsoft SQL Server** | [sqlcmd](https://learn.microsoft.com/en-us/sql/tools/sqlcmd/sqlcmd-utility) and ODBC tools from Microsoft (often under `...\Microsoft SQL Server\Client SDK\ODBC\...\Binn\` — match your installed version). |
| **MongoDB**              | [mongosh](https://www.mongodb.com/try/download/shell) 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](https://www.oracle.com/database/technologies/instant-client/winx64-downloads.html) (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:

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

Verify:

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

{% hint style="warning" %}
If **Homebrew** Python returns **`externally-managed-environment`**, install with your actual Python path, for example:

```bash
/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.
{% endhint %}

#### 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](https://docs.keeper.io/en/keeperpam/secrets-manager/quick-start-guide)), 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**.

<figure><img src="/files/UP8wQE0XtIErZuh5Hup1" alt=""><figcaption></figcaption></figure>

#### 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`.

<figure><img src="/files/G6XuIhi6NY5QNdrw514d" alt=""><figcaption></figcaption></figure>

**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](https://brew.sh/), for example:

```bash
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.

{% hint style="warning" %}
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.
{% endhint %}

***

### 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`                                       |

{% hint style="warning" %}
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.
{% endhint %}

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**.

{% hint style="info" %}
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).
{% endhint %}

#### 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).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.keeper.io/en/keeperpam/secrets-manager/integrations/royalts.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.