Create an auth profile

An auth profile is a named pointer to wherever a device’s credential lives — not the credential itself. The credential stays in its backing store; Transit AI reads it just long enough to authenticate an SSH session, then drops it from process memory.

Transit AI supports several credential sources. Most can be configured from the UI; a couple require editing the inventory TOML directly because they need file paths and nested passphrase references.

”Wait, why am I making a profile? I just type a username and password.”

Fair question. For decades the SSH workflow has been: open terminal, ssh user@host, type password, you’re in. Transit AI doesn’t change what happens on the wire — that’s still a stock SSH connection — but it changes where the password (or key) lives in between connects.

The reasons it’s worth a few extra clicks the first time:

You stop retyping the password every connect. Once it’s enrolled in your OS keychain (or SSH agent), Transit AI fetches it silently on each connect and drops it from memory after auth.
You stop pasting it into a config file. The inventory file records the reference — “look up transit/lab-pw in the keychain” — never the value. A leaked inventory leaks no passwords.
You reuse one profile across many devices. All your lab gear shares the same admin account? One profile, every device row points at it.
The AI can’t read it. The AI and the credential store are isolated components with no programmatic path between them — a property of the build, not a comment.

If this is your first time, start with OS keyring below. It’s the closest mental model to “save my password somewhere safe so I don’t retype it” — exactly what Keychain / Credential Manager / GNOME Keyring already do for your browser logins and Wi-Fi passphrases.

If you want to authenticate with keys instead of passwords — a good idea for anything reachable from the public Internet — skip to SSH agent or 1Password SSH agent, and see the appendix on generating a key if you don’t have one yet.

Open the auth profile manager

Click the key icon in the sidebar header. (Top of the left sidebar, between the refresh button and the collapse button.)
The Auth profile manager dialog opens, listing your existing profiles.
Click New profile to open the editor.

Common fields

Field	Notes
Name	Stable, human-readable identifier. Devices reference it by name. Example: `lab-pw`.
Username	The SSH login user. Example: `knox`.
Secret backend	Where the password / key actually lives. See the per-type sections below.

Backend: OS keyring (recommended for most people)

Stores the secret in your operating system’s native keystore:

macOS — Keychain
Windows — Credential Manager
Linux — Secret Service (GNOME Keyring, KWallet, KeePassXC, …)

This is the closest analogue to “save my password somewhere safe”: your OS already does this for Wi-Fi passphrases, browser logins, and saved app credentials. Transit AI hands the password directly to that same service on save, and never reads it back into the UI afterwards.

Fields:

Keyring key — the lookup name. Example: transit/lab-pw. Prefix with transit/ so you can spot Transit-owned entries when you browse Keychain Access / secret-tool later.
Secret value — the actual password. Written straight to the OS keychain on save; the input field clears the moment you click Save.

Steps:

Pick OS keyring from the Secret backend dropdown.
Enter a keyring key (e.g. transit/lab-pw).
Enter the secret value.
Click Save. Transit AI enrolls the secret into the keychain under the supplied key.

To rotate the password later, edit the profile and Save a new value — the OS keychain entry is overwritten in place.

Backend: SSH agent

Uses your running SSH agent as the credential source. An SSH agent is a long-running process that holds your private keys unlocked in memory so you don’t retype the key passphrase on every connect. Common implementations:

OpenSSH ssh-agent — ships with every Unix-y system; started by default on macOS, opt-in service on Windows 10+ (“OpenSSH Authentication Agent”).
1Password SSH agent — see the dedicated section below.
gpg-agent with enable-ssh-support — common in GnuPG-heavy setups.
keychain, ssh-ident, pageant — wrappers and Windows equivalents.

Transit AI doesn’t talk to any of them directly. It just dials the Unix domain socket (or Windows named pipe) named by the SSH_AUTH_SOCK environment variable. Whichever agent is at that socket — and however it stores its keys — Transit AI sees a list of identities and asks the agent to sign with one.

Fields:

Public-key fingerprint (optional) — pin to a specific key when the agent serves multiple. Example: SHA256:m3pYrW9pZpYrW9pZ…. Leave blank to let the agent offer keys in order until one is accepted.

Steps:

Make sure the agent is running and has at least one key loaded. On macOS / Linux:
```
ssh-add -l
```
If it prints “The agent has no identities”, load one:
```
ssh-add ~/.ssh/transit_ed25519
```
See the appendix if you don’t have a key yet.
Pick SSH agent from the Secret backend dropdown.
Optionally paste a SHA256 fingerprint to pin a specific key.
Click Save.

Finding `SSH_AUTH_SOCK`

From a terminal:

echo $SSH_AUTH_SOCK

What to expect by platform:

macOS (OpenSSH default) — /private/tmp/com.apple.launchd.XXXXXX/Listeners. Always set in GUI sessions; if empty, the launchd agent has been disabled.
macOS (1Password) — ~/Library/Group Containers/2BUA8C4S2C.com.1password/t/agent.sock. See the next section.
Linux (GNOME / KDE) — typically /run/user/<uid>/keyring/ssh, set by PAM at login.
Linux (manual ssh-agent started from .bashrc / .zshrc) — /tmp/ssh-XXXXXX/agent.<pid>.
Windows — the OpenSSH service uses the named pipe \\.\pipe\openssh-ssh-agent. The OS doesn’t expose a socket path via env var; Transit AI’s Windows build auto-detects the pipe. You do not need to set SSH_AUTH_SOCK on Windows for OpenSSH.

If echo $SSH_AUTH_SOCK is empty on macOS / Linux, no agent is configured for that shell. Either start one (eval "$(ssh-agent -s)" for OpenSSH; see below for 1Password) or pick a different backend.

If Transit AI is launched from the GUI (Finder, Spotlight, Activity Bar) rather than a terminal, it inherits the login shell’s environment, not whatever your interactive .zshrc sets. If your agent is configured by .zshrc and Transit AI doesn’t see it, export SSH_AUTH_SOCK from ~/.zprofile (loaded for login shells) or a launchd LaunchAgent so GUI launches inherit it too.

Backend: 1Password SSH agent

1Password’s SSH agent turns your 1Password vault into the source of truth for SSH keys. The private key never lives on disk — it stays in 1Password’s encrypted vault, and 1Password mediates each signing request with a Touch ID / Apple Watch / Windows Hello prompt (or a click in the 1Password app).

Transit AI talks to 1Password the same way it talks to any other SSH agent: through the SSH_AUTH_SOCK socket. So this section is half “configure 1Password to be your agent” and half “make sure Transit AI’s shell sees the socket”.

In the auth profile editor: pick SSH agent and (optionally) paste the SHA256 fingerprint of your 1Password key — the rest is configured outside Transit AI.

Step 1: Enable the 1Password SSH agent

Open the 1Password desktop app (the SSH agent is a desktop feature; the browser extension alone won’t do).
Go to Settings → Developer.
Tick Use the SSH agent.
Tick Display key names when authorizing connections so the approval prompts tell you which key is being requested.
(Optional) Tick Integrate with 1Password CLI if you’ll also use the op CLI for the 1Password CLI backend below.

Step 2: Add an SSH key to 1Password

Two ways:

Generate a brand-new key inside 1Password (recommended). The private key never touches disk:

In the 1Password app, + → SSH Key.
Click Add Private Key → Generate a New Key.
Pick Ed25519 (smallest, fastest, modern — see the appendix for the RSA fallback rationale).
Name it something memorable (e.g. Transit lab — ed25519).
Save. 1Password generates the key inside its vault; the public key is shown for copying.
Copy the public key block (ssh-ed25519 AAAA…) and install it on each device that should accept it (see the appendix for vendor-by- vendor syntax).

Import an existing key. If you already generated one on disk (per the appendix below) and want to move it into 1Password:

In the 1Password app, + → SSH Key.
Add Private Key → Import.
Pick the private key file (e.g. ~/.ssh/transit_ed25519).
Save.
Remove the on-disk copy so the only copy lives in 1Password:
```
rm ~/.ssh/transit_ed25519
```
On SSDs, file-level “secure erase” is largely a myth — the real protection is disk-wide encryption (FileVault, BitLocker, LUKS), which you should already have on a laptop.

Step 3: Make sure Transit AI sees the 1Password socket

The 1Password SSH agent listens on a fixed path:

macOS — ~/Library/Group Containers/2BUA8C4S2C.com.1password/t/agent.sock
Linux (1Password app, not the snap build) — ~/.1password/agent.sock
Windows — named pipe \\.\pipe\openssh-ssh-agent; 1Password installs a service that owns the pipe.

The 1Password app offers to write a snippet to your shell rc files that exports SSH_AUTH_SOCK to that path. Confirm it’s there:

echo $SSH_AUTH_SOCK

If you see the 1Password path, you’re set — restart Transit AI from that shell.

Add the export yourself (macOS)

If the 1Password helper didn’t write the snippet — or you want Transit AI to see the socket when launched from Finder / Spotlight / Dock, not just from a terminal — you need to put the value in three places, because each serves a different launch path.

Why three. Modern macOS does not automatically source any shell file (~/.zshrc, ~/.zprofile, ~/.zshenv) for GUI- launched apps. Each launch surface has its own environment source:

Terminal-launched apps inherit your shell’s environment (from ~/.zshrc).
Finder / Dock / Spotlight-launched apps inherit launchd’s environment AT THE TIME FINDER/DOCK STARTED — i.e., login time.
open -a Transit from a terminal goes through launchd directly, so it picks up changes immediately.

You need a setup that covers all three.

(a) Recommended: install a LaunchAgent — permanent, survives reboot

A LaunchAgent plist re-runs launchctl setenv at every login, before Finder/Dock spawn — so they (and every GUI app they launch) start with SSH_AUTH_SOCK already in their environment. This is the only configuration that “just works” indefinitely.

Generate and load the plist in one shot. The heredoc expands $HOME to your actual home path before the file is written (plists themselves don’t expand variables — so the absolute path gets baked in):

cat > ~/Library/LaunchAgents/com.transit.ssh-auth-sock.plist <<EOF
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key>
  <string>com.transit.ssh-auth-sock</string>
  <key>ProgramArguments</key>
  <array>
    <string>/bin/launchctl</string>
    <string>setenv</string>
    <string>SSH_AUTH_SOCK</string>
    <string>$HOME/Library/Group Containers/2BUA8C4S2C.com.1password/t/agent.sock</string>
  </array>
  <key>RunAtLoad</key>
  <true/>
</dict>
</plist>
EOF

launchctl load ~/Library/LaunchAgents/com.transit.ssh-auth-sock.plist

From the next login onward, every GUI app — Transit AI included — inherits SSH_AUTH_SOCK pointing at 1Password’s agent. No further config needed.

(b) Apply it to your current session right now — no logout

The LaunchAgent only fires at the next login. To get the same effect in your current session without rebooting, do all three steps below. (Skip this whole section if you’re willing to log out + back in.)

1. Set the env var in launchd’s running domain:

launchctl setenv SSH_AUTH_SOCK "$HOME/Library/Group Containers/2BUA8C4S2C.com.1password/t/agent.sock"

2. Verify it took:

launchctl getenv SSH_AUTH_SOCK
# should print the 1Password path

3. Restart Finder and Dock so they pick up the new env:

killall Finder Dock

Both restart automatically within a second or two. Without this step, double-clicking Transit AI in Finder spawns it with Finder’s environment (captured at login, before setenv), not launchd’s current environment — so the new socket value doesn’t propagate.

Once killall Finder Dock has done its work, double-clicking Transit AI from /Applications inherits SSH_AUTH_SOCK correctly.

(c) For terminal use (`ssh-add -l`, scripts) — append to `~/.zshrc`

The LaunchAgent only populates launchd’s environment for GUI apps. Terminal sessions inherit from your shell rc files, which are separate. To have ssh-add -l and other terminal commands talk to 1Password’s agent, append to ~/.zshrc:

echo 'export SSH_AUTH_SOCK="$HOME/Library/Group Containers/2BUA8C4S2C.com.1password/t/agent.sock"' >> ~/.zshrc \
  && source ~/.zshrc

Three details that matter in that line:

Single quotes around the whole export … string preserve the embedded double quotes — without them, the saved line breaks on the space in “Group Containers” when re-sourced.
>> (append), not > (overwrite) — > would truncate your existing .zshrc.
$HOME, not ~ — tilde doesn’t expand inside double quotes.

Step 4: Connect

Create an auth profile with backend SSH agent. Optionally paste the SHA256 fingerprint of your 1Password key (find it in the 1Password key item — Copy fingerprint).
Assign the profile to a device that has the matching public key installed.
Connect. 1Password’s authorization prompt appears (Touch ID on macOS, Windows Hello on Windows, biometric on supported Linux); approve it, and Transit AI receives the signature without ever seeing the private key.

Backend: 1Password CLI (vault item lookup)

Uses the 1Password CLI (op) to fetch a password value from a vault item at connect time. Distinct from the 1Password SSH agent above — this one is for plain-text secrets (router passwords, console-server passphrases, enable secrets), not for SSH keys.

Requires op on your PATH and a signed-in 1Password session.

Fields:

1Password reference — an op:// URL pointing at the field. Example: op://Personal/lab-pw/password.

Steps:

Install the 1Password CLI: brew install --cask 1password-cli (macOS) or follow 1Password’s docs.
Sign in: op signin.
Pick 1Password from the Secret backend dropdown.
Paste the op:// reference. You can copy one from the 1Password app by right-clicking a field → Copy Secret Reference.
Click Save.

Backend: environment variable

Reads the secret from a process environment variable. Intended for headless / CI installs only — interactive desktop installs should prefer the OS keyring.

Fields:

Environment variable name — the variable Transit AI will read. Example: TRANSIT_LAB_PW.

Steps:

Export the variable in the shell that launches Transit AI (e.g. in your .zshrc, .bashrc, or systemd unit).
Pick Environment variable from the Secret backend dropdown.
Enter the variable name.
Click Save.

The variable must be set before Transit AI starts; mid-session shell exports won’t be visible.

Backend: SSH key file (TOML-only)

Advanced — there’s no UI for this one. Open transit.toml in any text editor; see where this file lives for the path on your OS.

Loads a private key from a path on disk. The key may itself be passphrase-protected — the passphrase is configured as its own credential reference, so it can ride on a stronger backend like the OS keyring.

Edit your transit.toml directly:

[auth.lab-key]
username = "knox"
secret = { backend = "ssh_key", path = "/Users/knox/.ssh/lab_ed25519", passphrase = { backend = "keyring", key = "transit/lab-key-passphrase" } }

If the key has no passphrase, omit the passphrase field.

Backend: age-encrypted file (TOML-only)

Advanced — there’s no UI for this one. Open transit.toml in any text editor; see where this file lives for the path on your OS.

Loads the secret from an age-encrypted file, unlocked by a startup passphrase. Last-resort fallback for minimal Linux installs without Secret Service.

Edit your transit.toml directly:

[auth.lab-encrypted]
username = "knox"
secret = { backend = "encrypted_file", path = "/Users/knox/.config/transit/lab-pw.age" }

Appendix: Generate an SSH key

If you don’t have an SSH key yet — or you want a dedicated key for network gear instead of the personal one your laptop uses for GitHub — here’s the short version.

Pick a key type

Type	Use when	Notes
Ed25519	Anything modern (the default choice)	Tiny (256-bit), fast, secure. Native support in OpenSSH ≥ 6.5, Junos ≥ 18.3, Cisco IOS-XE ≥ 16.6, Arista EOS ≥ 4.21.
RSA 4096	Legacy gear that doesn’t recognize Ed25519	Wider compatibility (works back to OpenSSH 5.x and pre-2015 IOS). Slower to generate, larger files. Stay at 4096 bits or higher — 2048 is no longer considered hardened.
ECDSA	(Not recommended)	NIST curves; some environments mistrust them. Prefer Ed25519.
DSA	(Never)	Disabled in modern OpenSSH; Transit AI’s cipher floor rejects it.

Generate an Ed25519 key (recommended)

ssh-keygen -t ed25519 -C "transit-lab" -f ~/.ssh/transit_ed25519

You’ll be prompted for a passphrase. Set one unless you’re about to immediately move the key into 1Password (where it gets hardware-backed protection instead). The passphrase encrypts the key on disk — a stolen laptop with no passphrase is a stolen key.

This produces two files:

~/.ssh/transit_ed25519 — the private key. Treat it like a password.
~/.ssh/transit_ed25519.pub — the public key. Safe to copy anywhere; this is what you install on devices.

Generate an RSA 4096 key (fallback for legacy gear)

ssh-keygen -t rsa -b 4096 -C "transit-lab-rsa" -f ~/.ssh/transit_rsa

Same passphrase guidance. The .pub file is what you install on devices; the private key stays on your machine (or in 1Password).

Load the key into your SSH agent

OpenSSH agent (macOS / Linux):

ssh-add ~/.ssh/transit_ed25519

On macOS, add --apple-use-keychain (Monterey and later) so the passphrase is stored in Keychain and doesn’t prompt on every reboot:

ssh-add --apple-use-keychain ~/.ssh/transit_ed25519

To pre-load the key on every login, add to ~/.ssh/config:

Host *
  AddKeysToAgent yes
  UseKeychain yes               # macOS only
  IdentityFile ~/.ssh/transit_ed25519

To load the key into the 1Password SSH agent instead, follow Step 2 of the 1Password SSH agent section above and remove the on-disk copy afterwards.

Install the public key on a device

Copy the public key (.pub file) to the device’s authorized-key store:

cat ~/.ssh/transit_ed25519.pub
# ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI… transit-lab

Paste that string into the device CLI. The exact command varies by vendor — refer to the vendor’s admin guide for the current syntax. As examples:

Junos: set system login user knox authentication ssh-ed25519 "ssh-ed25519 AAAA…"
Cisco IOS-XE / NX-OS: configure terminal → ip ssh pubkey-chain → username knox → key-string → paste the base64 block (split into ≤72-char chunks on IOS) → exit back to exec mode.
Arista EOS: username knox ssh-key ssh-ed25519 AAAA….
Linux server: ssh-copy-id -i ~/.ssh/transit_ed25519.pub knox@host.

After the public key is installed, point the device’s auth profile in Transit AI at your SSH agent profile (or the 1Password SSH agent recipe) and Connect — no password prompt should appear.

Where the inventory file lives

OS	Path
macOS	`~/Library/Application Support/Transit/transit.toml`
Windows	`%APPDATA%\Transit\transit.toml`
Linux	`~/.config/Transit/transit.toml`

You can also override the path with the TRANSIT_INVENTORY environment variable.

What’s never in the inventory file

The secret value itself. The inventory only ever holds a reference (keyring key, op:// URL, environment variable name, file path). A pre-load scan rejects inventory files that contain anything that looks like an inline credential.

Create an auth profile

”Wait, why am I making a profile? I just type a username and password.”

Open the auth profile manager

Common fields

Backend: OS keyring (recommended for most people)

Backend: SSH agent

Finding SSH_AUTH_SOCK

Backend: 1Password SSH agent

Step 1: Enable the 1Password SSH agent

Step 2: Add an SSH key to 1Password

Step 3: Make sure Transit AI sees the 1Password socket

Add the export yourself (macOS)

(a) Recommended: install a LaunchAgent — permanent, survives reboot

(b) Apply it to your current session right now — no logout

(c) For terminal use (ssh-add -l, scripts) — append to ~/.zshrc

Step 4: Connect

Backend: 1Password CLI (vault item lookup)

Backend: environment variable

Backend: SSH key file (TOML-only)

Backend: age-encrypted file (TOML-only)

Appendix: Generate an SSH key

Pick a key type

Generate an Ed25519 key (recommended)

Generate an RSA 4096 key (fallback for legacy gear)

Load the key into your SSH agent

Install the public key on a device

Where the inventory file lives

What’s never in the inventory file

Finding `SSH_AUTH_SOCK`

(c) For terminal use (`ssh-add -l`, scripts) — append to `~/.zshrc`