---
title: 'Secrets and SSH hosts: let AI use credentials by reference'
description: >-
  Keep server, database, API and cloud credentials in Onevium, let AI use them
  by reference and run commands on SSH servers, and control every use with an
  authorization card.
canonical_url: 'https://onevium.com/docs/secrets-and-ssh'
language: en
updated_at: '2026-11-10'
publisher: Onevium
minimum_version: 1.3.3
---
> Source: Onevium official documentation
> Article: Secrets and SSH hosts: let AI use credentials by reference
> Original URL: https://onevium.com/docs/secrets-and-ssh
> Language: English
> Updated: 2026-11-10
> Applies to: 1.3.3+

---

# Secrets and SSH hosts: let AI use credentials by reference

Keep server, database, API and cloud credentials in Onevium, let AI use them by reference and run commands on SSH servers, and control every use with an authorization card.

## What the vault does

The vault keeps credentials for servers, databases, APIs and cloud accounts on your computer, encrypted with the system keychain, and organizes them by category and tag. AI only receives a reference such as `{{secret:shop-db-staging.password}}`. When a command runs, Onevium fills in the secret locally and replaces any known secret in the output with `[secret:name.field]`.

With SSH host items, AI can run commands and read or write files on a server once you allow it. Every use first shows an authorization card where you decide how long the allow lasts.

The vault works in the Onevium desktop app only; in web mode the page just shows a notice.

## 1. Open Secrets and hosts and turn on AI use

1. Open **Settings** and click **Secrets and hosts** in the **AI and connections** group (① in Figure 1). The page has four tabs: **Items**, **Access**, **Categories** and **Tags**.
2. If the top of the page says **AI use is off**, click **Turn on** (② in Figure 1). AI use is off by default. Turning it on adds 3 tools to each session (about 916 tokens); while it is off, sessions carry none of them.
3. Click **New** (③ in Figure 1) to add an item, or **Import** next to it to read configs already on this computer.

![Secrets and hosts in Settings: the navigation highlights Secrets and hosts, the page shows AI use is off with a Turn on button, and the item list holds SSH hosts, an SSH key, a database, an API credential and a website](https://onevium.com/assets/docs/secrets-ssh/en/secrets-ssh-01-settings.png "Figure 1: ① open Secrets and hosts, ② turn on AI use, ③ add an item. Isolated demo of real 1.3.2 components; items, hosts and times are simulated and no server is connected.")

Items, categories and tags stay manageable while AI use is off. When you no longer need it, click **Turn off AI use** at the bottom of the page: every grant is revoked at once, SSH connections close, and the items stay encrypted on this computer. The same switch is also in **Settings → Tools**.

## 2. Add an SSH key and an SSH host

Example: a cross-border e-commerce team's staging API server is `api.staging.example.com`, reached as the `deploy` user with a private key.

**First, add the SSH key (the sign-in):**

1. Click **New** and choose **SSH key** under **Servers and network**.
2. Enter `deploy-key` as the **Name**. Names use lowercase letters, numbers and hyphens, and are how AI refers to the item.
3. Set **Username** to `deploy` and **Sign-in method** to **Private key** (the default). Other methods are **SSH agent**, **Private key with passphrase**, **Password** and **Key file on this computer**.
4. Paste an OpenSSH, PEM or PKCS#8 key into **Private key**; a `.pem` file from EC2 or Alibaba Cloud works as is. To use a key file on this computer instead, pick **Key file on this computer** as the sign-in method. Click **Add**.

**Then add the SSH host:**

1. Click **New** and choose **SSH host**.
2. Fill it in as in Figure 2: **Name** `staging-api`, **Tags** `env: staging`, **Host** `api.staging.example.com`, **Port** `22`, **User** `deploy`, **SSH key** `deploy-key`, **Default directory** `/srv/shop`.
3. Keep **Approval** on **Timed grant (default)**, or choose **Ask every time** to confirm each command. For a jump host, save it as an SSH host first, then pick it under **Jump host**.
4. Click **Add**.

![New SSH host form: name staging-api, tag staging, host api.staging.example.com, port 22, user deploy, SSH key deploy-key, default directory /srv/shop, approval set to Timed grant](https://onevium.com/assets/docs/secrets-ssh/en/secrets-ssh-02-ssh-host.png "Figure 2: the fields a new SSH host needs. Demo of real 1.3.2 components with a fictional host and key; the item was not saved and no server was contacted.")

**Advanced** holds **Proxy command**, **Alias in \~/.ssh/config**, **Connect with** (**Automatic** or **System OpenSSH**) and **One-time code**. Fields that make this computer run a command or read a local file can only be changed on the Settings page; AI cannot write them.

**Allow the AI to read plain text** is off by default, so AI only uses references. When it is on, AI may ask to read a value; each read needs your approval, and the value is then sent to the model provider.

Once saved, hover over the item to **Copy reference** or **Test connection**. The first connection to a server shows a **First connection to …** card with the host fingerprint. Check it with the administrator or cloud console, then click **Trust and connect**.

**Use tags to separate environments.** A server tagged `env: prod` is treated as a production item: grants last at most 15 minutes, it is never allowed automatically when nobody answers, and it cannot be approved from a channel chat.

## 3. Import from configs on this computer

If you already use `~/.ssh/config` or cloud CLIs, you do not need to type each item:

1. On the **Items** tab, click **Import** to open **Import local configs**.
2. Under **Local configs**, tick what to import. Sources include SSH config (`~/.ssh/config`), Alibaba Cloud, AWS, Tencent Cloud, Kubernetes, GitHub CLI and Docker.
3. Click **Import N items**. Anything already saved shows **In the vault: name**.

The original files stay as they are; you can delete the plain-text secrets in them yourself afterwards. Accounts that sign in through the browser or single sign-on (SSO) have no fixed secret, so they show the reason and cannot be imported.

AI may also reach for credentials on its own:

- When it wants to read a credential file, an **AI wants to read a credential file** card appears, and the file's content would enter the AI's context. This card is answered on the computer only; click **Import it into the vault instead** to keep the credential in the vault.
- AI never asks you to paste a secret into the chat. When it creates or changes an item, a card asks you to type the secret there. If it names a file that holds the secrets, the card says it read the values from that file; check them, then allow to save.

## 4. Let AI run a command on the server

In a session, name the host and the task, for example:

```text
Use staging-api to check the status of the shop-api service and its last 50 error log lines.
Read only: do not change files or restart services.
```

When AI makes the SSH request, the authorization card appears where the composer is (Figure 3):

1. Check the title **AI wants to run a command on staging-api**, the sign-in address and the full command. Use the arrow on the right to expand a long command.
2. Click the duration at the lower left (① in Figure 3) and choose how long to allow: **Only this time**, **5 min**, **15 min**, **1 hour** or **This session**. With a timed allow you can also tick **Also for every session** or **Also for every secret (not production)**. **Stop asking in this session** allows this request and starts a no-approval window for the current session.
3. Click **Allow** (② in Figure 3), or **Deny**.

![Authorization card: AI wants to run a command on staging-api, with the sign-in address and command; the duration menu is open, listing Only this time, 5 min, 15 min, 1 hour, This session and the reach options](https://onevium.com/assets/docs/secrets-ssh/en/secrets-ssh-03-authorize.png "Figure 3: ① choose how long, ② allow. Isolated demo of the real 1.3.2 card with a fictional host and command; nothing ran. Because the menu was opened, the countdown at the top right shows as paused.")

If nobody answers an ordinary request, the card allows it once after 2 minutes. Clicking anywhere on the card pauses that countdown; the card then denies after 10 minutes instead.

**Expected result:** after you allow it, AI runs the command on the server and returns the output, with any known secret shown as `[secret:name.field]`. While the grant lasts, using the same host again in this session does not ask again.

Besides SSH, AI can run a local command with secrets injected as environment variables of that process only (for example `MYSQL_PWD`); the card then says "Injects MYSQL\_PWD". When a command would write a secret into a CLI's config file, turn off certificate checks, or put a secret in process arguments, the card flags it in amber. The first two can only be allowed once at a time and are refused outright for production items.

## 5. Manage access and skip approvals

Open **Settings → Secrets and hosts → Access** (Figure 4):

- **Skip approvals**: pick a duration under **For** (**15 minutes**, **1 hour** or **Until Onevium quits**) and click **Start skipping approvals**. While it runs, AI can use, change and delete secrets directly, connect to hosts and addresses not on record, and read credential files. Plain-text reads, values you must type and commands that save a secret into a CLI's config file still ask, and a host whose fingerprint changed is still refused. **Include production secrets** is ticked by default; untick it to keep production asking.
- **Active access**: every grant with its session and time left. **Revoke** one or **Revoke all**. Locking the screen or quitting Onevium revokes all grants and ends skipping approvals.
- **When nobody answers**: **Allow once automatically** by default, or **Deny automatically**. Host fingerprints, one-time codes, values you must type, deletes, plain-text reads, production secrets, credential files and requests from a channel or another session are always denied after 10 minutes.
- **Cards start on**: the duration a new card starts on. It changes when you pick another duration on a card and allow it; production cards stop at 15 minutes.

![Access tab of Secrets and hosts: Skip approvals with duration and Include production secrets, the Active access list, and the When nobody answers and Cards start on settings](https://onevium.com/assets/docs/secrets-ssh/en/secrets-ssh-04-access.png "Figure 4: the Access tab. Demo of real 1.3.2 components; the two grants and session titles are simulated, and skipping approvals was not started.")

**Channels and scheduled tasks:** a request from a channel bot's chat is labeled as coming from a channel. Ordinary list and use requests can be approved right in the chat, for at most 15 minutes; production secrets, credential files, requests with a warning and requests that need a typed value are answered on the computer. Scheduled tasks have nobody present to approve, so they cannot use the vault by default; they get through only while you skip approvals with **Also channel chats and scheduled tasks** ticked. Before ticking it, remember that anyone who can message your bot could then use your secrets.

## 6. One-time codes

Website, SSH host, SSH key, cloud account and several other items can hold a **One-time code**:

1. In the item's **One-time code** field, paste a setup link (`otpauth://…`) or setup key, or click **Read a QR code image** to read a screenshot.
2. Reopen the item after saving: the field shows the current code with its countdown, and **Copy code** copies it.
3. To move many accounts at once, open **Import**, switch to **One-time codes**, and paste a Google Authenticator export QR screenshot or `otpauth://` links.

Where codes are used:

- **SSH sign-in**: when the server asks for a code and the host or its SSH key holds one, Onevium answers automatically. Otherwise an **… asks for verification** card asks you for this one code, which is not saved.
- **Built-in browser**: when a sign-in page asks for a code, a website item matching the address offers **Fill verification code** among the saved-account suggestions. The system may ask for Touch ID or similar first.
- **Menu bar**: from 1.3.2, search and copy codes and passwords from the menu-bar hub; see [Menu-bar hub](https://onevium.com/docs/menu-bar-hub).

AI only ever gets a reference to the current code, `{{secret:name.totp}}`, never the seed.

## Troubleshooting

| Symptom                                                        | What to do                                                                                                                                                              |
| -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| The page says "The system keychain is unavailable"             | Unlock the keychain or sign in to your desktop session again, then click **Try again**                                                                                  |
| AI says it has no secret tools                                 | Make sure the page does not say **AI use is off**; after turning it on, try again in a new message                                                                      |
| A request was denied without a card you could answer           | Check whether it came from a scheduled task, or whether **Access → When nobody answers** is set to **Deny automatically**                                               |
| A longer duration is missing from the card                     | Items tagged `env: prod` stop at 15 minutes; deletes and plain-text reads are once only; channel requests stop at 15 minutes                                            |
| The connection is refused because the host fingerprint changed | Ask the administrator whether the server was reinstalled. Once confirmed, click **Forget fingerprint** on the item and check the new fingerprint on the next connection |
| Output contains `[secret:name.field]`                          | That is a masked secret, the expected result, not an error                                                                                                              |
| A request cannot be approved from the bot chat                 | Production secrets, credential files, requests with a warning or a typed value are answered on the computer only                                                        |

### Add and import verification codes

In Quick access, open the verification-code controls to add a setup key, read a QR image or review a supported batch import, including Google Authenticator exports. Check the account label and destination secret item for each selected entry before confirming. Keep unselected entries and existing sign-in fields intact. Open the saved code details and verify its issuer/account before using it; never paste setup keys into a public conversation or screenshot.

## Next steps

- Choose a session's work mode and tool permissions: [Modes & permissions](https://onevium.com/docs/permissions)
- Let AI sign in and check pages in the built-in browser: [Browser automation](https://onevium.com/docs/browser-automation)
- Keep working from a chat through a bot: [Channel overview](https://onevium.com/docs/team-channels)
- Get codes and passwords without opening the main window: [Menu-bar hub](https://onevium.com/docs/menu-bar-hub)
