diff --git a/.docs/user-guide-site/brief.md b/.docs/user-guide-site/brief.md new file mode 100644 index 0000000..a2d550b --- /dev/null +++ b/.docs/user-guide-site/brief.md @@ -0,0 +1,5 @@ +# Brief: YourSSH documentation site on Mintlify + +What: move the YourSSH user and developer guides (app repo `docs/wiki/`) into this Mintlify site, refreshed for the 0.4.0 redesign with screenshots from the isolated docs journey, and build/deploy it from GitHub Actions. + +Why: the owner wants a public documentation site for YourSSH maintained in YoursshLabs/docs. diff --git a/.docs/user-guide-site/changelog.md b/.docs/user-guide-site/changelog.md new file mode 100644 index 0000000..70dce74 --- /dev/null +++ b/.docs/user-guide-site/changelog.md @@ -0,0 +1,4 @@ +# Changelog + +- 2026-11-13: Starter replaced (branding, navigation, screenshots), CI workflow added, writers dispatched. +- 2026-11-13: 25 pages written by 6 writers, fact-checked against develop by 2 reviewers (app copy bugs fixed in YourSSH PRs #126, #128; plugin globals made real in #127; app lock over every route in progress). validate + broken-links pass. 125 screenshots kept (unused ones pruned). diff --git a/.docs/user-guide-site/context.md b/.docs/user-guide-site/context.md new file mode 100644 index 0000000..8cab5e8 --- /dev/null +++ b/.docs/user-guide-site/context.md @@ -0,0 +1,6 @@ +# Context + +- The repo was created from Mintlify's hosted starter ("Initial commit from Mintlify hosted docs"), so a Mintlify project is connected to it. +- Static export (`mint export`) is Enterprise-only, so self-hosting on GitHub Pages is not an option. CI therefore validates the build and triggers the hosted deployment through the Mintlify API (`POST /v1/project/update/{projectId}`, then poll `GET /v1/project/update-status/{statusId}`: queued | in_progress | success | failure | skipped). +- Screenshots: 209 PNGs from the app repo's `tool/docs_journey.sh` run at v0.4.0 (demo containers, isolated HOME); the mobile pair QR was re-encoded to 192.0.2.10. +- Old content: app repo `docs/wiki/User-Guide-*.md`, `Developer-Guide-*.md`, `docs/SYNC_SETUP.md`, `docs/plugin-authoring-guide.md`. diff --git a/.docs/user-guide-site/plan.md b/.docs/user-guide-site/plan.md new file mode 100644 index 0000000..43b3aca --- /dev/null +++ b/.docs/user-guide-site/plan.md @@ -0,0 +1,6 @@ +# Plan + +1. Replace the starter: branding (amber palette, logo, favicon), navigation for 25 pages (User guide + Developer guide tabs), screenshots under images/. +2. CI: `.github/workflows/docs.yml` — validate + broken links on PRs and main; deploy job on main via the Mintlify API (secrets MINTLIFY_API_KEY, MINTLIFY_PROJECT_ID; skipped when absent). +3. Write the pages (4 writers in parallel, one per section group), then the developer guide after the plugin API fix lands in the app repo. +4. Validate locally, prune unreferenced images, open the PR, merge after CI, ask the owner for the two secrets. diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 0000000..6f9ce09 --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,69 @@ +name: Docs + +on: + pull_request: + push: + branches: [main] + workflow_dispatch: + +permissions: + contents: read + +concurrency: + group: docs-${{ github.ref }} + cancel-in-progress: true + +jobs: + build: + name: Build and check + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-node@v4 + with: + node-version: 22 + - name: Install the Mintlify CLI + run: npm i -g mint + - name: Validate the build + run: mint validate + - name: Check links + run: mint broken-links + + deploy: + name: Deploy to Mintlify + needs: build + if: github.event_name != 'pull_request' && github.ref == 'refs/heads/main' + runs-on: ubuntu-latest + env: + MINTLIFY_API_KEY: ${{ secrets.MINTLIFY_API_KEY }} + MINTLIFY_PROJECT_ID: ${{ secrets.MINTLIFY_PROJECT_ID }} + steps: + - name: Trigger the deployment and wait for it + run: | + set -euo pipefail + if [ -z "${MINTLIFY_API_KEY}" ] || [ -z "${MINTLIFY_PROJECT_ID}" ]; then + echo "::warning::MINTLIFY_API_KEY / MINTLIFY_PROJECT_ID are not set; skipping the API deployment." + exit 0 + fi + api=https://api.mintlify.com/v1 + resp=$(curl -fsS -X POST "$api/project/update/${MINTLIFY_PROJECT_ID}" \ + -H "Authorization: Bearer ${MINTLIFY_API_KEY}") + status_id=$(echo "$resp" | jq -r '.statusId // empty') + if [ -z "$status_id" ]; then + echo "::error::Mintlify did not return a statusId: $resp" + exit 1 + fi + echo "Deployment queued: $status_id" + for i in $(seq 1 60); do + sleep 10 + st=$(curl -fsS "$api/project/update-status/${status_id}" \ + -H "Authorization: Bearer ${MINTLIFY_API_KEY}" | jq -r '.status // empty') + echo "status: ${st:-unknown}" + case "$st" in + success) echo "Deployed."; exit 0 ;; + skipped) echo "::notice::Mintlify skipped the update (nothing to deploy)."; exit 0 ;; + failure) echo "::error::Mintlify deployment failed"; exit 1 ;; + esac + done + echo "::error::Timed out waiting for the Mintlify deployment" + exit 1 diff --git a/.mintignore b/.mintignore index 9922f06..314d0ae 100644 --- a/.mintignore +++ b/.mintignore @@ -5,3 +5,6 @@ # Draft content drafts/ *.draft.mdx + +# Task notes for maintainers (not published) +.docs/ diff --git a/AGENTS.md b/AGENTS.md index cebd973..3963b1b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,33 +1,38 @@ -> **First-time setup**: Customize this file for your project. Prompt the user to customize this file for their project. -> For Mintlify product knowledge (components, configuration, writing standards), -> install the Mintlify skill: `npx skills add https://mintlify.com/docs` - -# Documentation project instructions +# YourSSH documentation — instructions for writers and agents ## About this project -- This is a documentation site built on [Mintlify](https://mintlify.com) -- Pages are MDX files with YAML frontmatter -- Configuration lives in `docs.json` -- Run `mint dev` to preview locally -- Run `mint broken-links` to check links +- The documentation site for [YourSSH](https://github.com/YoursshLabs/yourssh), built on [Mintlify](https://mintlify.com). +- Pages are MDX files with YAML frontmatter (`title`, `description`, optional `icon` from Lucide/Font Awesome). +- Configuration and navigation live in `docs.json`. A page that is not listed there is not published. +- Preview: `npx mint dev`. Before a pull request: `npx mint validate` and `npx mint broken-links` (CI runs both). +- Screenshots live in `images//.png`. They come from the app repo's isolated docs journey (`tool/docs_journey.sh` in YoursshLabs/yourssh) and are resized to at most 1440 px wide. Reuse those names; don't add screenshots of real servers, real IPs or real user data. ## Terminology -{/* Add product-specific terms and preferred usage */} -{/* Example: Use "workspace" not "project", "member" not "user" */} - -## Style preferences - -{/* Add any project-specific style rules below */} - -- Use active voice and second person ("you") -- Keep sentences concise — one idea per sentence -- Use sentence case for headings -- Bold for UI elements: Click **Settings** -- Code formatting for file names, commands, paths, and code references +- **YourSSH** (one word, capital Y, S, S, H). "The app" is fine after the first mention. +- **Host**: a saved connection profile (SSH, RDP or VNC). Not "server" when you mean the saved profile. +- **Session** / **tab**: a connected terminal, RDP or VNC view in the top tab bar. +- **Hosts dashboard**: the Home screen with group cards and host cards. +- **Host editor**: the side panel that opens from **New host** or **Edit**. +- **Connection chain**: jump hosts (bastions) in front of a host. Not "proxy jump" in headings. +- **Keychain**: the SSH key manager screen. The macOS Keychain / Windows Credential Manager is the **system credential store**. +- **Known hosts**: pinned host keys. **Host key**: the server's SSH key. Don't call it a fingerprint unless you mean the SHA-256 string. +- **Plugins**: built-in plugins (Snippets, DevOps Hub, Web Tools) and script plugins (JavaScript in `~/.yourssh/plugins`). + +## Style + +- Active voice, second person ("you"), present tense. One idea per sentence. +- Sentence case for headings and titles. +- Bold for UI labels exactly as the app shows them: click **New host**, then **Save**. +- Code formatting for file names, paths, commands, keys and settings values: `~/.ssh/config`, `Ctrl+Shift+I`. +- Keyboard shortcuts: show macOS first, then Windows/Linux when they differ (`Cmd+K` / `Ctrl+K`). +- Use Mintlify components where they help: `` for procedures, ``/``/`` sparingly, `` around screenshots with a short caption, `` on overview pages, `` for per-OS instructions. +- Every screenshot has meaningful alt text. +- Document what the app does today. If you're unsure whether a feature exists or how it behaves, check the app repo (`CLAUDE.md`, `app/lib`) instead of guessing. ## Content boundaries -{/* Define what should and shouldn't be documented */} -{/* Example: Don't document internal admin features */} +- User guide: what a user sees and does, plus the security behaviour they need to understand (host key pinning, credential storage, what syncs and how it's encrypted). +- Developer guide: building from source, architecture, plugin system and plugin authoring. +- Don't document internal process docs (`docs/superpowers/` in the app repo), unreleased features or roadmap items as if they shipped. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8863ee4..df3cc4a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,5 +1,3 @@ -> **Customize this file**: Tailor this template to your project by noting specific contribution types you're looking for, adding a Code of Conduct, or adjusting the writing guidelines to match your style. - # Contribute to the documentation Thank you for your interest in contributing to our documentation! This guide will help you get started. @@ -15,14 +13,14 @@ Thank you for your interest in contributing to our documentation! This guide wil ### Option 2: Local development 1. Fork and clone this repository -2. Install the Mintlify CLI: `npm i -g mint` +2. Install Node.js 20.17+ (the CLI runs with `npx mint`) 3. Create a branch for your changes 4. Make changes -5. Navigate to the docs directory and run `mint dev` +5. Run `npx mint dev` 6. Preview your changes at `http://localhost:3000` 7. Commit your changes and submit a pull request -For more details on local development, see our [development guide](development.mdx). +Run `npx mint validate` and `npx mint broken-links` before opening a pull request; CI runs both. Follow [AGENTS.md](AGENTS.md) for style and terminology. ## Writing guidelines diff --git a/README.md b/README.md index 4552fbc..ed7ab63 100644 --- a/README.md +++ b/README.md @@ -1,55 +1,32 @@ -# Mintlify Starter Kit +# YourSSH documentation -Use the starter kit to get your docs deployed and ready to customize. +Source of the YourSSH documentation site, built with [Mintlify](https://mintlify.com). The app lives in [YoursshLabs/yourssh](https://github.com/YoursshLabs/yourssh). -Click the green **Use this template** button at the top of this repo to copy the Mintlify starter kit. The starter kit contains examples with - -- Guide pages -- Navigation -- Customizations -- API reference pages -- Use of popular components - -**[Follow the full quickstart guide](https://starter.mintlify.com/quickstart)** - -## AI-assisted writing - -Set up your AI coding tool to work with Mintlify: +## Preview locally ```bash -npx skills add https://mintlify.com/docs -``` - -This command installs Mintlify's documentation skill for your configured AI tools like Claude Code, Cursor, Windsurf, and others. The skill includes component reference, writing standards, and workflow guidance. - -See the [AI tools guides](/ai-tools) for tool-specific setup. - -## Development - -Install the [Mintlify CLI](https://www.npmjs.com/package/mint) to preview your documentation changes locally. To install, use the following command: - -``` -npm i -g mint +npx mint dev # http://localhost:3000 +npx mint validate # the same build check CI runs +npx mint broken-links ``` -Run the following command at the root of your documentation, where your `docs.json` is located: - -``` -mint dev -``` +Requires Node.js 20.17 or newer. -View your local preview at `http://localhost:3000`. +## Structure -## Publishing changes +- `docs.json` — site config and navigation. A page must be listed here to be published. +- `index.mdx`, `installation.mdx`, `quickstart.mdx` — getting started. +- `user-guide/` — one page per feature. +- `developer-guide/` — building from source, architecture and plugins. +- `images//` — screenshots from the app repo's isolated docs journey (`tool/docs_journey.sh`), resized to at most 1440 px wide. -Install our GitHub app from your [dashboard](https://dashboard.mintlify.com/settings/organization/github-app) to propagate changes from your repo to your deployment. Changes are deployed to production automatically after pushing to the default branch. +Writing rules and terminology: [AGENTS.md](AGENTS.md). -## Need help? +## Build and deploy -### Troubleshooting +`.github/workflows/docs.yml`: -- If your dev environment isn't running: Run `mint update` to ensure you have the most recent version of the CLI. -- If a page loads as a 404: Make sure you are running in a folder with a valid `docs.json`. +- Every pull request and every push to `main` run `mint validate` and `mint broken-links`. +- After those pass on `main`, the workflow asks Mintlify to deploy the site and waits for the result. It uses the repository secrets `MINTLIFY_API_KEY` (an admin API key, `mint_…`) and `MINTLIFY_PROJECT_ID`, both from the Mintlify dashboard's API keys page. Without them the deploy step is skipped with a warning. -### Resources -- [Mintlify documentation](https://mintlify.com/docs) +To make CI the only way the site deploys, turn off automatic deployments for this repository in the Mintlify dashboard after adding the secrets. diff --git a/ai-tools/claude-code.mdx b/ai-tools/claude-code.mdx deleted file mode 100644 index a59ca25..0000000 --- a/ai-tools/claude-code.mdx +++ /dev/null @@ -1,43 +0,0 @@ ---- -title: "Claude Code setup" -description: "Configure Claude Code for your documentation workflow" -icon: "asterisk" ---- - -Set up Claude Code to help you write and maintain your Mintlify documentation. - -## Prerequisites - -- Active Claude subscription (Pro, Max, or API access) - -## Setup - - - - ```bash - npm install -g @anthropic-ai/claude-code - ``` - - - - In your docs directory, run: - - ```bash - npx skills add https://mintlify.com/docs - ``` - - This gives Claude Code Mintlify's component reference, writing standards, - and workflow guidance. - - - - Edit `AGENTS.md` in your project root to add project-specific terminology, - style preferences, and content boundaries. - - - - ```bash - claude - ``` - - diff --git a/ai-tools/cursor.mdx b/ai-tools/cursor.mdx deleted file mode 100644 index 80bab56..0000000 --- a/ai-tools/cursor.mdx +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: "Cursor setup" -description: "Configure Cursor for your documentation workflow" -icon: "arrow-pointer" ---- - -Set up Cursor to help you write and maintain your Mintlify documentation. - -## Prerequisites - -- Cursor editor installed - -## Setup - - - - Open the root of your documentation repository where `docs.json` is located. - - - - In the integrated terminal, run: - - ```bash - npx skills add https://mintlify.com/docs - ``` - - This gives Cursor Mintlify's component reference, writing standards, - and workflow guidance. - - - - Edit `AGENTS.md` in your project root to add project-specific terminology, - style preferences, and content boundaries. - - - - Open a file and use Cursor's AI features to draft and edit documentation. - - diff --git a/ai-tools/windsurf.mdx b/ai-tools/windsurf.mdx deleted file mode 100644 index 0776cca..0000000 --- a/ai-tools/windsurf.mdx +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: "Windsurf setup" -description: "Configure Windsurf for your documentation workflow" -icon: "water" ---- - -Set up Windsurf's Cascade AI assistant to help you write and maintain your Mintlify documentation. - -## Prerequisites - -- Windsurf editor installed - -## Setup - - - - Open the root of your documentation repository where `docs.json` is located. - - - - In the integrated terminal, run: - - ```bash - npx skills add https://mintlify.com/docs - ``` - - This gives Windsurf Mintlify's component reference, writing standards, - and workflow guidance. - - - - Edit `AGENTS.md` in your project root to add project-specific terminology, - style preferences, and content boundaries. - - - - Open a file and use Cascade to draft and edit documentation. - - diff --git a/api-reference/endpoint/create.mdx b/api-reference/endpoint/create.mdx deleted file mode 100644 index 5689f1b..0000000 --- a/api-reference/endpoint/create.mdx +++ /dev/null @@ -1,4 +0,0 @@ ---- -title: 'Create Plant' -openapi: 'POST /plants' ---- diff --git a/api-reference/endpoint/delete.mdx b/api-reference/endpoint/delete.mdx deleted file mode 100644 index 657dfc8..0000000 --- a/api-reference/endpoint/delete.mdx +++ /dev/null @@ -1,4 +0,0 @@ ---- -title: 'Delete Plant' -openapi: 'DELETE /plants/{id}' ---- diff --git a/api-reference/endpoint/get.mdx b/api-reference/endpoint/get.mdx deleted file mode 100644 index 56aa09e..0000000 --- a/api-reference/endpoint/get.mdx +++ /dev/null @@ -1,4 +0,0 @@ ---- -title: 'Get Plants' -openapi: 'GET /plants' ---- diff --git a/api-reference/endpoint/webhook.mdx b/api-reference/endpoint/webhook.mdx deleted file mode 100644 index 3291340..0000000 --- a/api-reference/endpoint/webhook.mdx +++ /dev/null @@ -1,4 +0,0 @@ ---- -title: 'New Plant' -openapi: 'WEBHOOK /plant/webhook' ---- diff --git a/api-reference/introduction.mdx b/api-reference/introduction.mdx deleted file mode 100644 index c835b78..0000000 --- a/api-reference/introduction.mdx +++ /dev/null @@ -1,33 +0,0 @@ ---- -title: 'Introduction' -description: 'Example section for showcasing API endpoints' ---- - - - If you're not looking to build API reference documentation, you can delete - this section by removing the api-reference folder. - - -## Welcome - -There are two ways to build API documentation: [OpenAPI](https://mintlify.com/docs/api-playground/openapi/setup) and [MDX components](https://mintlify.com/docs/api-playground/mdx/configuration). For the starter kit, we are using the following OpenAPI specification. - - - View the OpenAPI specification file - - -## Authentication - -All API endpoints are authenticated using Bearer tokens and picked up from the specification file. - -```json -"security": [ - { - "bearerAuth": [] - } -] -``` diff --git a/api-reference/openapi.json b/api-reference/openapi.json deleted file mode 100644 index da5326e..0000000 --- a/api-reference/openapi.json +++ /dev/null @@ -1,217 +0,0 @@ -{ - "openapi": "3.1.0", - "info": { - "title": "OpenAPI Plant Store", - "description": "A sample API that uses a plant store as an example to demonstrate features in the OpenAPI specification", - "license": { - "name": "MIT" - }, - "version": "1.0.0" - }, - "servers": [ - { - "url": "http://sandbox.mintlify.com" - } - ], - "security": [ - { - "bearerAuth": [] - } - ], - "paths": { - "/plants": { - "get": { - "description": "Returns all plants from the system that the user has access to", - "parameters": [ - { - "name": "limit", - "in": "query", - "description": "The maximum number of results to return", - "schema": { - "type": "integer", - "format": "int32" - } - } - ], - "responses": { - "200": { - "description": "Plant response", - "content": { - "application/json": { - "schema": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Plant" - } - } - } - } - }, - "400": { - "description": "Unexpected error", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - } - } - }, - "post": { - "description": "Creates a new plant in the store", - "requestBody": { - "description": "Plant to add to the store", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/NewPlant" - } - } - }, - "required": true - }, - "responses": { - "200": { - "description": "plant response", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Plant" - } - } - } - }, - "400": { - "description": "unexpected error", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - } - } - } - }, - "/plants/{id}": { - "delete": { - "description": "Deletes a single plant based on the ID supplied", - "parameters": [ - { - "name": "id", - "in": "path", - "description": "ID of plant to delete", - "required": true, - "schema": { - "type": "integer", - "format": "int64" - } - } - ], - "responses": { - "204": { - "description": "Plant deleted", - "content": {} - }, - "400": { - "description": "unexpected error", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - } - } - } - } - }, - "webhooks": { - "/plant/webhook": { - "post": { - "description": "Information about a new plant added to the store", - "requestBody": { - "description": "Plant added to the store", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/NewPlant" - } - } - } - }, - "responses": { - "200": { - "description": "Return a 200 status to indicate that the data was received successfully" - } - } - } - } - }, - "components": { - "schemas": { - "Plant": { - "required": [ - "name" - ], - "type": "object", - "properties": { - "name": { - "description": "The name of the plant", - "type": "string" - }, - "tag": { - "description": "Tag to specify the type", - "type": "string" - } - } - }, - "NewPlant": { - "allOf": [ - { - "$ref": "#/components/schemas/Plant" - }, - { - "required": [ - "id" - ], - "type": "object", - "properties": { - "id": { - "description": "Identification number of the plant", - "type": "integer", - "format": "int64" - } - } - } - ] - }, - "Error": { - "required": [ - "error", - "message" - ], - "type": "object", - "properties": { - "error": { - "type": "integer", - "format": "int32" - }, - "message": { - "type": "string" - } - } - } - }, - "securitySchemes": { - "bearerAuth": { - "type": "http", - "scheme": "bearer" - } - } - } -} \ No newline at end of file diff --git a/developer-guide/architecture.mdx b/developer-guide/architecture.mdx new file mode 100644 index 0000000..ad17781 --- /dev/null +++ b/developer-guide/architecture.mdx @@ -0,0 +1,140 @@ +--- +title: Architecture +description: How the YourSSH monorepo is organized, how data flows through the app, and which design decisions matter for security. +icon: sitemap +--- + +YourSSH is a Flutter app for macOS, Windows, Linux and Android. The desktop app is the main product; a smaller mobile UI (SSH only) ships on Android. This page is a map of the code, not a class reference. Follow the links to the source when you need detail. + + +The repository's [`CLAUDE.md`](https://github.com/YoursshLabs/yourssh/blob/develop/CLAUDE.md) is the detailed, always-current reference for every subsystem. Use this page to find your way, then read `CLAUDE.md` for the specifics. + + +## Monorepo layout + +```text +yourssh/ +├── app/ # The Flutter app +│ └── lib/ +│ ├── main.dart # Entry point: builds services and providers, wires callbacks +│ ├── models/ # Host, sessions, port forwards, ... +│ ├── providers/ # ChangeNotifier state +│ ├── services/ # SSH, storage, sync, CLI endpoint, recording, ... +│ ├── screens/ # MainScreen, tab bar and sidebar (screens/shell/) +│ ├── widgets/ # UI, one folder or file per feature area +│ ├── mobile/ # Android UI +│ └── plugins/ # plugin_registry.dart (built-in Dart plugins) +├── packages/ +│ ├── dartssh2/ # Local fork: SSH, SFTP, forwarding, agent forwarding +│ ├── xterm/ # Local fork: terminal emulator widget +│ ├── flutter_pty/ # Local fork: local terminal PTY +│ ├── yourssh_ui/ # Design system (forui wrapper, Ys* tokens and components) +│ ├── yourssh_cli/ # Pure-Dart `yourssh` command-line client +│ ├── yourssh_rdp/ # Rust RDP client (IronRDP) bridged with flutter_rust_bridge +│ ├── yourssh_vnc/ # Rust VNC client bridged with flutter_rust_bridge +│ ├── yourssh_plugin_api/ # YourSSHPlugin interface for Dart plugins +│ ├── yourssh_snippets/ # Built-in plugin: Snippets +│ ├── yourssh_devops/ # Built-in plugin: DevOps Hub +│ ├── yourssh_web_tools/ # Built-in plugin: Web Tools +│ └── yourssh_script_engine/ # JavaScript plugin runtime (QuickJS) +├── tool/ # Scripts: UI lint, icon generation, docs journey +└── .github/workflows/ # pr-test.yml, release.yml +``` + +The three forks (`dartssh2`, `xterm`, `flutter_pty`) and every `yourssh_*` package are wired in through `dependency_overrides` in `app/pubspec.yaml`. A change in `packages/` shows up in the app immediately; there is nothing to publish. Each fork carries specific patches, listed in `CLAUDE.md`. If you change a fork, explain in your pull request why the fix can't live in `app/`. + +## Data flow + +```text +Flutter UI (screens/, widgets/) + └── Providers (ChangeNotifier, via the provider package) + └── Services + ├── SshService ──► dartssh2 (fork) ──► remote SSH host + ├── RDP / VNC clients ──► Rust libraries (FFI) + ├── StorageService ──► system credential store, SharedPreferences + └── SyncService ──► Supabase +``` + +`main.dart` creates the services and long-lived providers once, connects them with callbacks (key lookup, host-key verification, sync on change), then mounts `MainScreen` under a `MultiProvider`. Widgets read state from providers and never talk to services directly. + +## Providers and services + +These are the ones you meet first. Browse [`app/lib/providers/`](https://github.com/YoursshLabs/yourssh/tree/develop/app/lib/providers) and [`app/lib/services/`](https://github.com/YoursshLabs/yourssh/tree/develop/app/lib/services) for the rest. + +| Piece | Responsibility | +|---|---| +| `HostProvider` | Saved hosts (SSH, RDP, VNC). Fires a mutation callback that triggers a sync push, and tears down dependents when a host is deleted. | +| `SessionProvider` | The unified tab list: SSH sessions, local shells, RDP and VNC tabs. Handles auto-reconnect, host-key verification callbacks and key lookup. | +| `KeyProvider`, `KnownHostsProvider` | SSH keys and pinned host keys. | +| `PortForwardProvider`, `TunnelProvider` | Persistent forwarding rules and runtime tunnel state. | +| `SettingsProvider` | App-wide preferences. | +| `SyncProvider` | Supabase sync configuration and status. | +| `RecordingProvider` | The recording library (`.cast` files). | +| `AiChatProvider` | AI chat state for Anthropic, OpenAI and Gemini. | +| `PluginProvider`, `PluginEngineProvider` | Built-in Dart plugins and JavaScript script plugins. | +| `SshService` | Owns the SSH clients and sessions: connect, shell, exec, SFTP, disconnect. | +| `StorageService` | Credential storage (system credential store first). | +| `SyncService`, `P2PSyncService` | Cloud sync and LAN sync. | +| `RecordingService` | Writes Asciinema v2 recordings. | +| `ShareSessionService` | Terminal sharing over Supabase Realtime. | + +## Navigation + +`MainScreen` ([`app/lib/screens/main_screen.dart`](https://github.com/YoursshLabs/yourssh/blob/develop/app/lib/screens/main_screen.dart)) renders a top tab bar and a left sidebar, both under [`app/lib/screens/shell/`](https://github.com/YoursshLabs/yourssh/tree/develop/app/lib/screens/shell). The sidebar maps each `NavSection` (hosts, keychain, port forwarding, SFTP, known hosts, recordings, audit, settings, plugins) to a top-level screen under `app/lib/widgets/`. The host editor is a single side panel, `HostDetailPanel`, with an SSH / RDP / VNC switch at the top. + +## Remote desktop + +RDP and VNC run in Rust and are loaded as native libraries through `flutter_rust_bridge`: + +- `packages/yourssh_rdp` wraps IronRDP. The first connection to an unpinned host stops before credentials are sent, so the user can pin the certificate first. +- `packages/yourssh_vnc` is the VNC client. + +The libraries load lazily on the first RDP or VNC connection. They are not tracked in git; see [Build from source](/developer-guide/build#native-rdp-and-vnc-libraries). + +## Plugins + +Two kinds coexist: Dart plugins compiled into the app, and JavaScript plugins loaded from disk at runtime. See [Plugin system](/developer-guide/plugin-system). + +## Security-relevant design + +These behaviours are part of the product's security model. Keep them intact when you change nearby code. + + + + `KnownHostsProvider` pins one key per host, port and key type. An unknown endpoint is accepted on first use after the user confirms it. If a host already pinned under one key type presents a key of a new type, the app shows a blocking "Host key type changed" prompt, so a man-in-the-middle can't slip past by offering a different algorithm. RDP works the same way with certificate fingerprints, checked before any credentials are sent. The dialogs live in [`tofu_dialogs.dart`](https://github.com/YoursshLabs/yourssh/blob/develop/app/lib/widgets/tofu_dialogs.dart) and focus the safe choice by default. The `dartssh2` fork also implements strict key exchange (the Terrapin mitigation). + + + `StorageService` writes passwords, key passphrases and the sync passphrase to the system credential store first (macOS Keychain or Windows Credential Manager). Only if that fails does it fall back to `SharedPreferences`, and the fallback is visible in **Settings** and the notification bell. On every launch the app tries to move leftover plaintext secrets into the store, confirming each write before it removes the old copy. + + + Cloud sync is opt-in. A 12-character sync code is the only secret: it derives the AES-256-GCM key through PBKDF2-HMAC-SHA256, and the Supabase row id is a one-way hash of it, so the code is never stored server-side. A pulled payload is applied only if its authenticated inner timestamp is newer than the last push and the last applied payload, which prevents rollback. LAN sync uses a random 32-byte key carried in a QR code, and the one-shot server closes after one transfer. Terminal sharing encrypts every message with a key derived from the share code. + + + The `yourssh` command talks to the running app over a Unix socket (macOS, Linux) or a named pipe (Windows). The run directory is private to the user, the app rejects any peer with a different user id or SID, and a fresh random token is written at every launch and compared in constant time. A lock file makes the app single-instance. The `yourssh://connect/...` URL scheme only opens saved hosts. + + + JavaScript plugins run in an isolated QuickJS context with declared permissions, user consent bound to file hashes, execution limits and a circuit breaker. Details are in [Plugin system](/developer-guide/plugin-system). + + + +## Design system + +The app is dark only. `packages/yourssh_ui` wraps [forui](https://forui.dev) (the "Amber Brand" theme) and re-exports it, so app code imports `package:yourssh_ui/yourssh_ui.dart` and gets the `F*` widgets, Lucide icons and the `Ys*` tokens (`YsColors`, `YsSpace`, `YsRadius`) and components (`YsHostCard`, `YsFileTable`, `YsStatusBar`, `YsTab`, `YsPluginHost`). + +The rules for contributors: + +- Build new or rebuilt UI from forui widgets or `Ys*` components, not hand-styled Material. +- Use `showYsToast` for toasts and `showYsDialog` or `showYsConfirm` for dialogs. +- Use `YsColors` tokens, not `Color(0x...)` literals in widgets. +- `tool/check_ui_lint.sh` enforces this in CI. See [Contributing](/developer-guide/contributing#ui-lint-gate). + +## Where to go next + + + + Toolchain, run, test and CI. + + + Dart and JavaScript plugins. + + diff --git a/developer-guide/build.mdx b/developer-guide/build.mdx new file mode 100644 index 0000000..03899df --- /dev/null +++ b/developer-guide/build.mdx @@ -0,0 +1,136 @@ +--- +title: Build from source +description: Set up the toolchain, run and build YourSSH, build the native RDP and VNC libraries, and understand the CI workflows. +icon: hammer +--- + +## Prerequisites + +- **Flutter 3.50.0.** CI pins this version (`FLUTTER_VERSION` in `pr-test.yml` and `release.yml`), so use the same one locally. Run `flutter doctor` and fix what it reports. +- A platform toolchain: + - macOS: Xcode. + - Windows: Visual Studio with the **Desktop development with C++** workload. + - Linux: `clang`, `cmake`, `ninja-build`, `pkg-config` and `libgtk-3-dev`. The CI job also installs `liblzma-dev`, `libsecret-1-dev`, `libjsoncpp-dev`, `libkeybinder-3.0-dev` and `libnotify-dev`. + - Android: JDK 17 and the Android SDK. +- A Rust toolchain, only if you want RDP or VNC (see [below](#native-rdp-and-vnc-libraries)). + +## Run in development + +```bash +git clone https://github.com/YoursshLabs/yourssh.git +cd yourssh/app +flutter pub get +flutter run -d macos # or: -d windows / -d linux +``` + +A debug build (`flutter run`) uses its own CLI endpoint and run directory, so it never takes over an installed YourSSH. See the CLI notes in [`CLAUDE.md`](https://github.com/YoursshLabs/yourssh/blob/develop/CLAUDE.md). + +## Build a release + +```bash +cd app +flutter build macos # app/build/macos/Build/Products/Release/ +flutter build windows # app/build/windows/x64/runner/Release/ +flutter build linux # app/build/linux/x64/release/bundle/ +flutter build apk # Android +``` + +## Native RDP and VNC libraries + +RDP and VNC are Rust crates (`packages/yourssh_rdp`, `packages/yourssh_vnc`). The compiled libraries (`.dylib`, `.so`, `.dll`) are **not tracked in git**. Build them once after cloning, and again after you change the Rust code: + +```bash +bash packages/yourssh_rdp/build.sh # macOS / Linux +pwsh packages/yourssh_rdp/build.ps1 # Windows +bash packages/yourssh_vnc/build.sh # same pattern for VNC +``` + +The script builds the crate and copies the library into `packages//assets/native/`. In development the app loads it from there; in a release build it is bundled next to the app. Without the library, the app runs normally and only RDP or VNC connections fail. + +Run the crate's own tests without Flutter: + +```bash +cargo test --manifest-path packages/yourssh_rdp/rust/Cargo.toml +``` + + +The Android build is SSH only and builds no Rust libraries. + + +## JavaScript plugin runtime + +JavaScript plugins run on QuickJS through a small C bridge in `packages/yourssh_script_engine/native/`. Only the macOS arm64 `libqjsbridge.dylib` is prebuilt and committed. After you change the C bridge, rebuild it with: + +```bash +bash packages/yourssh_script_engine/native/build_macos.sh +``` + +## Analyze, test and lint + +```bash +cd app +flutter analyze --no-fatal-infos # what CI runs +flutter test # all app tests +flutter test test/services/sync_service_test.dart # one file +flutter test --name "pattern" # by test name +``` + +Packages have their own suites. Run `flutter test` (or `dart test` for `yourssh_cli`) inside the package directory. + +From the repository root, run the UI lint gate: + +```bash +bash tool/check_ui_lint_selftest.sh +bash tool/check_ui_lint.sh +``` + + +`--no-fatal-infos` is deliberate. On Flutter 3.50, a few hundred infos are deprecations of `package:flutter/material.dart` that a separate migration will clear. Warnings and errors still fail the build. + + +## Android toolchain + +Each Flutter release raises the minimum Gradle, Android Gradle Plugin (AGP) and Kotlin versions that its Gradle plugin accepts, and the Android build fails below them. When you bump Flutter, bump the Android toolchain with it. The versions live in `app/android/gradle/wrapper/gradle-wrapper.properties` and the `plugins {}` block of `app/android/settings.gradle.kts`. The `android` job in `pr-test.yml` (a debug APK build) is the check. + +## Regenerate the docs screenshots + +The screenshots in this documentation come from an isolated journey that drives the real app against local demo servers. It needs macOS and Docker. + +```bash +tool/docs_journey.sh setup # build the demo image and start the demo containers +tool/docs_journey.sh all # build the app, run the journey, write PNGs +tool/docs_journey.sh teardown # remove only what setup created +``` + +`setup` generates a throwaway client key (outside the repository), builds a demo SSH image and starts five containers: a demo server, a bastion, an internal database host behind the bastion, an RDP desktop and a VNC desktop. `all` builds the integration-test app once, then launches it with a temporary `HOME`, so your real settings, hosts and `~/.yourssh` are never touched. It runs a desktop pass and a mobile pass and writes the PNGs and an `INDEX.md` to `screenshots/docs/`. Set `SECTIONS="01,02"` to limit sections or `DOCS_OUT` to change the output directory. + +## CI workflows + +Both workflows are in [`.github/workflows/`](https://github.com/YoursshLabs/yourssh/tree/develop/.github/workflows). + +**`pr-test.yml`** runs on pull requests to `develop` and `master`: + +| Job | What it checks | +|---|---| +| `app` | `flutter analyze` and `flutter test` for the app (Linux). | +| `ui` | The UI lint gate, then analyze and test for `yourssh_ui`. | +| `plugins` | Analyze and test for Snippets, DevOps and Web Tools. | +| `bridge` | For `yourssh_rdp` and `yourssh_vnc`: cargo tests, the native build, then the Dart tests. | +| `android` | A debug APK build, which proves the Gradle, AGP and Kotlin versions. | +| `cli` | Tests and a compile smoke test for `yourssh_cli`. | +| `windows-cli` | The CLI endpoint and the app's CLI tests on a Windows runner. | +| `test` | The required check named `test`. It fails unless `app`, `ui`, `bridge`, `android`, `cli` and `windows-cli` all succeed. | + +**`release.yml`** runs when a commit lands on `master`. It runs analyze and tests first, then builds every platform in parallel: + +- macOS: universal build, signed with a Developer ID certificate, notarized and stapled, shipped as a DMG and a ZIP. +- Windows: portable ZIP and an Inno Setup installer, for x64 and ARM64. +- Linux: `.deb` package and portable `tar.gz`, for x86_64 and arm64. +- Android: a release APK. + +A final `release` job, the only one with a write token, creates the GitHub release and attaches the artifacts. + +## Next steps + +- [Architecture](/developer-guide/architecture) to learn the codebase. +- [Contributing](/developer-guide/contributing) for the pull request workflow. diff --git a/developer-guide/contributing.mdx b/developer-guide/contributing.mdx new file mode 100644 index 0000000..43da4a7 --- /dev/null +++ b/developer-guide/contributing.mdx @@ -0,0 +1,91 @@ +--- +title: Contributing +description: How to propose changes to YourSSH, from branching and commit style to the checks every pull request must pass. +icon: git-pull-request +--- + +Contributions of every kind are welcome: bug reports, feature ideas, documentation and code. For a larger change, open an issue first so you can agree on the approach before you invest time. The project follows its [Code of Conduct](https://github.com/YoursshLabs/yourssh/blob/develop/CODE_OF_CONDUCT.md). + +## Ways to contribute + +- Report a bug or suggest a feature in the [issue tracker](https://github.com/YoursshLabs/yourssh/issues/new/choose). +- Ask a question in an issue or in [Discussions](https://github.com/YoursshLabs/yourssh/discussions). +- Submit code, as described below. + + +Report security vulnerabilities privately through [GitHub private vulnerability reporting](https://github.com/YoursshLabs/yourssh/security/advisories/new). Never open a public issue, discussion or pull request for one. See the [security policy](https://github.com/YoursshLabs/yourssh/blob/develop/SECURITY.md). Fixes are applied to the latest release only. + + +## Set up + + + + Fork [YoursshLabs/yourssh](https://github.com/YoursshLabs/yourssh) and clone your fork. + + + Follow [Build from source](/developer-guide/build). + + + ```bash + git checkout develop + git pull origin develop + git checkout -b feat/my-feature + ``` + + + +## Branches + +- `develop` is the working branch. **Open your pull requests against `develop`.** +- `master` is the release branch. Maintainers cut releases by merging `develop` into `master`, and every push to `master` publishes a release. + +## Pull requests + +Before you open a pull request: + +- [ ] `flutter analyze` reports no new warnings or errors. +- [ ] `flutter test` passes, plus the tests of any package you changed. +- [ ] `bash tool/check_ui_lint.sh` passes (see [below](#ui-lint-gate)). +- [ ] New or changed behavior has tests. Keep pure logic separate from Flutter and I/O so you can unit-test it; look in `app/test/` for patterns. +- [ ] UI changes include a screenshot. The app is dark only. +- [ ] No secrets, credentials, hostnames or personal data in code, tests or screenshots. + +CI runs the same checks on every pull request (see [CI workflows](/developer-guide/build#ci-workflows)). Write code, comments and documentation in English, and fill in the pull request template. + +### Titles and commits + +Pull request titles and commit messages follow [Conventional Commits](https://www.conventionalcommits.org/): + +```text +feat(sftp): add drag-and-drop upload to remote panel +fix(terminal): preserve scrollback on reconnect +docs: clarify the build steps +refactor(sync): simplify the retry loop +test(ssh): cover host-key type changes +``` + +### Local forks + +`dartssh2`, `xterm` and `flutter_pty` are local forks that carry specific patches. If your change touches one, explain in the pull request why it can't be solved in `app/`, and link the upstream issue when there is one. + +## Code style + +- Match the surrounding code: naming, structure and comment density. +- Keep widgets, providers and services in their established folders under `app/lib/`. +- State management uses `provider` with `ChangeNotifier`. Follow the existing patterns. + +## UI and the design system + +New or rebuilt UI is built from forui widgets or `Ys*` components from `packages/yourssh_ui`, not hand-styled Material. Use `YsColors` tokens instead of color literals, `showYsToast` for toasts and `showYsDialog` or `showYsConfirm` for dialogs. See the [design system](/developer-guide/architecture#design-system) section. + +### UI lint gate + +`tool/check_ui_lint.sh` scans `app/lib` and the Snippets, DevOps and Web Tools packages. It fails on the Material widgets the design system replaced: `IconButton(`, `AlertDialog(`, `SnackBar(`, `Icons.`, `ScaffoldMessenger`, `showDialog(`, `showModalBottomSheet` and `TextField(`. The forui equivalents, such as `FTextField(` and `showYsDialog(`, pass. A justified exception goes in `tool/ui_lint_allowlist.txt` as `path:pattern # reason`, and needs a good reason. + +## Documentation + +This documentation lives in its own repository, [YoursshLabs/docs](https://github.com/YoursshLabs/docs), separate from the app. If your change alters user-visible behavior, update the matching page there or mention it in your pull request. To preview the docs locally, run `npx mint dev` in that repository; CI runs `mint validate` and `mint broken-links` on every pull request. + +## Releases + +Maintainers handle releases: a `CHANGELOG.md` entry, a version bump in `app/pubspec.yaml`, and the merge from `develop` to `master`. Contributors don't need to do any of this. diff --git a/developer-guide/plugin-authoring.mdx b/developer-guide/plugin-authoring.mdx new file mode 100644 index 0000000..2d7fe38 --- /dev/null +++ b/developer-guide/plugin-authoring.mdx @@ -0,0 +1,346 @@ +--- +title: Plugin authoring +description: Write a JavaScript script plugin for YourSSH, from a minimal example to the full manifest, hooks, globals, panels and limits reference. +icon: code +--- + +A script plugin is a folder with a `plugin.json` manifest and a JavaScript entry file. You drop it into `~/.yourssh/plugins/`. There is no build step and no app rebuild. For how the runtime loads plugins, enforces permissions and contains failures, see [Plugin system](/developer-guide/plugin-system). + +Each plugin runs in its own isolated QuickJS runtime. The app injects a `plugin` object plus the `ui`, `ssh`, `storage` and `console` globals. You register handlers with `plugin.on(event, handler)`, and the app calls them when something happens: terminal output, a session connecting, a command running. + +## Your first plugin + +This plugin colors `ERROR` red in terminal output. It needs one permission, `terminal.transform`. + + + + ```bash + mkdir -p ~/.yourssh/plugins/log-highlighter + ``` + + + Save this as `~/.yourssh/plugins/log-highlighter/plugin.json`: + + ```json + { + "id": "dev.example.log-highlighter", + "name": "Log Highlighter", + "version": "1.0.0", + "entry": "index.js", + "minAppVersion": "1.0.0", + "permissions": ["terminal.transform"] + } + ``` + + + Save this as `~/.yourssh/plugins/log-highlighter/index.js`: + + ```js + plugin.on("terminal.output", function (ctx) { + return ctx.data.replace(/\bERROR\b/g, "\x1b[31;1mERROR\x1b[0m"); + }); + ``` + + + Open **Plugins** in the sidebar, or restart YourSSH. A dialog titled **Install "Log Highlighter"** lists the requested permissions. Click **Allow selected**. + + + Open a session and run `echo ERROR`. The word is red. Edit `index.js` and save: the plugin reloads on its own. + + + + +![The plugin manager with the built-in Snippets, DevOps Hub and Web Tools plugins and an empty Script plugins section](/images/15-plugins/01-manager.png) + + + +If you change any file in the plugin folder after approving it, the app asks for consent again. See [Consent](#consent). + + +## Folder layout + +```text +~/.yourssh/plugins/ + my-plugin/ + plugin.json required: manifest + index.js required: entry file (named by "entry") + lib/helpers.js optional helper files + panel/index.html optional: HTML for a panel +``` + +A plugin is a directory. The app identifies it by `plugin.json`. The `entry` path and a panel's `webviewEntry` must stay inside the plugin folder. Paths with `../`, absolute paths and symlinks that escape the folder are rejected. + +## Manifest + +| Field | Required | Description | +|---|---|---| +| `id` | Yes | Unique id, matching `^[a-z0-9][a-z0-9._\-]{0,63}$`. Use reverse-domain style, for example `dev.yourname.myplugin`. | +| `name` | Yes | Display name in the plugin manager and consent dialog. | +| `version` | Yes | Plugin version, `MAJOR.MINOR.PATCH`. | +| `entry` | Yes | JavaScript entry file, relative to the plugin folder. | +| `minAppVersion` | Yes | Minimum YourSSH version the plugin needs. | +| `permissions` | No | List of permissions the plugin asks for. Defaults to none. An unknown permission makes the manifest invalid. | + +An invalid manifest means the plugin doesn't load. + + +The ids of the built-in plugins are reserved. A script plugin can't use `dev.yourssh.snippets` or any other built-in id; the loader skips it without prompting. + + +## Permissions + +Declare only what you need. A plugin can call only the APIs whose permission the user approved. + +| Permission | Grants | +|---|---| +| `terminal.read` | Observe `terminal.output` and `terminal.input`. The return value is ignored. | +| `terminal.transform` | Modify terminal output. | +| `terminal.intercept` | Cancel or modify keystrokes before they reach the SSH server. | +| `terminal.inject` | Type text into a session's shell with `ssh.inject()`. | +| `session.observe` | `session.connect` and `session.disconnect` events, and `ssh.sessions()`. | +| `session.control` | `session.connect.before`, which can cancel a connection. | +| `ssh.exec` | The `ssh-exec` panel message, and `ssh.sessions()`. | +| `sftp.read` | The `sftp-list` and `sftp-read` panel messages. | +| `sftp.write` | Reserved. No API uses it yet. | +| `command.intercept` | `command.before` and `command.after` hooks for commands run through SSH exec. | +| `ui.notify` | `ui.notify()`. | +| `ui.statusbar` | `ui.statusbar.*`, and `ui.addCommand()`. | +| `ui.panel` | `ui.panel.register()`, and `ui.addCommand()`. | +| `ui.clipboard` | `ui.clipboard.copy()`. | + +`storage` and `console` need no permission. + +### Consent + +The first time a plugin loads, the app shows the consent dialog. You can untick individual permissions before you click **Allow selected**, and the plugin gets only the ticked ones. **Deny** keeps it from running. + +- Consent is bound to a SHA-256 hash of every file in the plugin folder. Change any file and the app asks again. +- Stored grants are intersected with the manifest's current permissions, so editing the manifest can't add a permission silently. + +## Hooks and events + +Register a handler with `plugin.on(event, handler)`. The handler receives one `ctx` object. + +| Event | Permission | Can cancel | Can transform | +|---|---|---|---| +| `terminal.output` | `terminal.transform` (or `terminal.read` to observe) | No | Yes | +| `terminal.input` | `terminal.intercept` (or `terminal.read` to observe) | Yes | Yes | +| `session.connect` | `session.observe` | No | No | +| `session.disconnect` | `session.observe` | No | No | +| `session.connect.before` | `session.control` | Yes | No | +| `command.before` | `command.intercept` | Yes | Yes | +| `command.after` | `command.intercept` | No | No | + +Return values: + +- Return a string to replace the data (or the command). +- Return `false` to cancel, where the event can be cancelled. +- Return nothing (`null` or `undefined`) to pass the data through unchanged. + +### Terminal events + +```js +plugin.on("terminal.output", function (ctx) { + // ctx.sessionId: string + // ctx.data: string, raw output, may contain ANSI escape codes + return ctx.data.replace(/WARN/g, "\x1b[33mWARN\x1b[0m"); +}); + +plugin.on("terminal.input", function (ctx) { + // ctx.data: the keystrokes about to be sent + if (ctx.data.trim() === "rm -rf /") return false; // block +}); +``` + +`terminal.output` and `terminal.input` run for every chunk. Keep them synchronous and fast. Don't do heavy work in them. + +### Session events + +```js +plugin.on("session.connect", function (ctx) { + // ctx.sessionId, ctx.host, ctx.username, ctx.port + console.log("Connected to " + ctx.username + "@" + ctx.host); +}); + +plugin.on("session.disconnect", function (ctx) { + ui.statusbar.remove("my-item-" + ctx.sessionId); +}); + +plugin.on("session.connect.before", function (ctx) { + if (ctx.host === "blocked.example.com") return false; // cancel the connection +}); +``` + +### Command events + +`command.before` and `command.after` fire for commands run through SSH exec (for example by a panel's `ssh-exec` message). They don't fire for what you type in the terminal. + +```js +plugin.on("command.before", function (ctx) { + // ctx.sessionId, ctx.command + if (/mkfs\./.test(ctx.command)) return false; // cancel + return ctx.command; // or return a replacement +}); + +plugin.on("command.after", function (ctx) { + // ctx.sessionId, ctx.command, ctx.stdout, ctx.stderr, ctx.exitCode + if (ctx.exitCode !== 0) console.error("Failed: " + ctx.command); +}); +``` + +## Globals + +### `ssh` + +| Call | Permission | Description | +|---|---|---| +| `ssh.sessions()` | `session.observe` or `ssh.exec` | Returns an array of `{ sessionId, host, username, port, connected }`. | +| `ssh.inject(sessionId, text)` | `terminal.inject` | Types `text` into the session's shell as if the user typed it. End with `\n` to run it. | + +There is no JavaScript `ssh.exec`. To run a command and read its output, use the `ssh-exec` [panel message](#panels). + +### `storage` + +Persistent key-value store. It needs no permission and is namespaced per plugin id. Values are strings. + +```js +storage.set("note", "hello"); +var item = storage.get("note"); // { value: "hello" }, or null if the key is missing +if (item !== null) console.log(item.value); +storage.delete("note"); +``` + +Top-level variables reset when the plugin reloads. Use `storage` for anything that must survive. + +### `ui` + +| Call | Permission | Description | +|---|---|---| +| `ui.notify(message, { type })` | `ui.notify` | `type` is `info` (default), `warning` or `error`. The app writes it to the plugin console. | +| `ui.statusbar.add(id, { label, tooltip })` | `ui.statusbar` | Adds a status bar item. | +| `ui.statusbar.update(id, { label, tooltip })` | `ui.statusbar` | Updates an item. | +| `ui.statusbar.remove(id)` | `ui.statusbar` | Removes an item. | +| `ui.panel.register(config)` | `ui.panel` | Registers a panel. See [Panels](#panels). | +| `ui.clipboard.copy(text)` | `ui.clipboard` | Copies text to the system clipboard. | +| `ui.addCommand({ id, label, keybinding })` | `ui.statusbar` or `ui.panel` | Adds a command palette entry. Its handler isn't invoked yet. | + +### `console` + +`console.log`, `console.warn` and `console.error` write to the plugin console. See [Debugging](#debugging). + + +There is no `sftp` global in plugin JavaScript. A plugin with `sftp.read` can list and read remote files from panel HTML only. Writing, deleting and creating remote files isn't supported. + + +## Panels + +A panel is an HTML page your plugin shows inside the app. Register it from `index.js`: + +```js +ui.panel.register({ + title: "My Panel", + icon: "note", + webviewEntry: "panel/index.html", // relative to the plugin folder + onMessage: function (msg) { + if (msg.type === "save-note") { + storage.set("note-" + msg.host, msg.content); + return { type: "saved" }; + } + } +}); +``` + +This needs `ui.panel`. The `onMessage` handler runs in the plugin's JavaScript, so it must be synchronous. + +From the panel HTML, call `pluginBridge.send(message)`. It returns a promise with the reply. A panel's own messages go to `onMessage`. The four native message types below are handled by the app, so they can run async SSH and SFTP work: + +| Message | Permission | Reply | +|---|---|---| +| `{ type: 'ssh-exec', sessionId, command }` | `ssh.exec` | `{ type: 'exec-result', stdout, stderr, exitCode }` | +| `{ type: 'ssh-sessions' }` | `session.observe` or `ssh.exec` | `{ type: 'sessions', data: [{ sessionId, host, username, port, connected }] }` | +| `{ type: 'sftp-list', sessionId, path }` | `sftp.read` | `{ type: 'sftp-entries', data: [{ name, isDir, size, modified }] }` | +| `{ type: 'sftp-read', sessionId, path }` | `sftp.read` | `{ type: 'sftp-content', content }` | + +A failed call returns `{ type: 'error', message }`. A panel is plugin-controlled HTML, so the app checks the same permissions on these messages as on the JavaScript APIs. Declare the permission in `plugin.json`, or the call is refused. + +```js +// panel/index.html +async function poll() { + const s = await pluginBridge.send({ type: 'ssh-sessions' }); + if (!s.data.length) return; + const r = await pluginBridge.send({ + type: 'ssh-exec', + sessionId: s.data[0].sessionId, + command: 'uname -a' + }); + document.getElementById('out').textContent = r.exitCode === 0 ? r.stdout : r.stderr; +} +setInterval(poll, 10000); // timers exist in panel HTML +poll(); +``` + +## Lifecycle and hot reload + +On start, the app scans `~/.yourssh/plugins/`, validates each `plugin.json`, asks for consent if needed, then runs the entry file, where `plugin.on(...)` registers handlers. + +The app watches the folder. When a `.js` file or `plugin.json` changes, it unloads the plugin and runs it again from scratch. No restart. A reload also resets the plugin's error count. You can also reload from the plugin manager. + +## Limits + +The runtime enforces these on every plugin. + +| Limit | Value | +|---|---| +| Time per hook call or panel message | 250 ms | +| Time to load | 5 s | +| Memory | 64 MiB | +| Stack | 512 KiB | + +A call that goes over its time limit is aborted. + +### Circuit breaker + +An error counts 1, a timeout counts 5, and a success resets the count. At 10 the app skips the plugin's hooks and unloads it. Save a file to reload it and reset the count. + +## Debugging + +Open **Plugins** in the sidebar and click **View logs** on your plugin. The console shows `console.log`, `console.warn` and `console.error` output, `ui.notify()` messages and JavaScript runtime errors. + +Test a plugin by creating the folder, approving it once, then editing `index.js`. Each save reloads it. + +### Common errors + +| Message | Cause | Fix | +|---|---|---| +| `Permission denied: ui.panel not granted` | The permission is missing from the manifest, or you unticked it in the consent dialog. | Add it to `permissions` and approve again. | +| `ManifestException: plugin.json missing required field: name` | A required field is missing. | Add the field. | +| `ManifestException: Unknown permissions: ...` | A permission name isn't recognized. | Use a name from the [permissions table](#permissions). | +| `QuickJsException: SyntaxError` | Syntax error in the entry file. | Fix `index.js`. | +| Plugin doesn't load | `plugin.json` isn't valid JSON. | Validate the JSON. | + +## Known limitations + +| Limitation | Workaround | +|---|---| +| Hook handlers are synchronous. They can't run SSH commands or await a result. | Run async work from panel HTML with the native panel messages. | +| `setInterval` and `setTimeout` don't exist in the plugin context. | Trigger logic from hooks. Run timers in panel HTML, which has native timers. | +| The command palette handler for `ui.addCommand` isn't invoked. The entry appears but does nothing. | None yet. | +| No JavaScript `ssh.exec` and no `sftp` global. | Use the panel messages, or `ssh.inject(sessionId, "cmd\n")` to run a command in the user's shell. | +| `ui.notify` writes to the plugin console, not a toast. | Use `ui.statusbar` for visible status. | +| A panel loads from `file://`, so `fetch()` may be blocked. | Use the native panel messages instead of `fetch()`. | +| Plugins can't share state in a supported way. | None. | + +## Before you share a plugin + +- Request only the permissions you use. +- Keep `terminal.output` and `terminal.input` handlers synchronous and fast. +- Keep persistent state in `storage`, not in variables. +- Remove status bar items in `session.disconnect`. +- Test with no active sessions: `ssh.sessions()` returns an empty array. +- Remove noisy `console.log` calls. +- Add a `README.md` that says what the plugin does and why it needs each permission. + +## Related pages + +- [Plugin system](/developer-guide/plugin-system) +- [Architecture](/developer-guide/architecture) diff --git a/developer-guide/plugin-system.mdx b/developer-guide/plugin-system.mdx new file mode 100644 index 0000000..003ffde --- /dev/null +++ b/developer-guide/plugin-system.mdx @@ -0,0 +1,138 @@ +--- +title: Plugin system +description: How YourSSH loads built-in Dart plugins and JavaScript script plugins, and how permissions, consent and limits keep script plugins contained. +icon: puzzle +--- + +YourSSH has two kinds of plugins. They coexist at runtime and appear together under **Plugins** in the sidebar. + +| | Built-in Dart plugins | JavaScript script plugins | +|---|---|---| +| Loaded | Compiled into the app | From disk at runtime, no rebuild | +| Language | Dart and Flutter | JavaScript (QuickJS) | +| Examples | Snippets, DevOps Hub, Web Tools | Anything a user drops into `~/.yourssh/plugins` | +| Trust | Part of the app | Sandboxed, permission-gated, user consent | +| Who writes them | App contributors | Anyone | + +To write a script plugin, see [Plugin authoring](/developer-guide/plugin-authoring). + +## Built-in Dart plugins + +Dart plugins are registered in [`app/lib/plugins/plugin_registry.dart`](https://github.com/YoursshLabs/yourssh/blob/develop/app/lib/plugins/plugin_registry.dart) in the `kRegisteredPlugins` list. The three that ship today are: + +| Package | Plugin | +|---|---| +| `yourssh_snippets` | Snippets: a reusable command library | +| `yourssh_devops` | DevOps Hub: containers, network tools, Cloudflare tunnel, mail catcher, MCP server | +| `yourssh_web_tools` | Web Tools: an in-app browser over port-forwarded HTTP | + +### Add a Dart plugin + + + + Add it to the dependencies in `app/pubspec.yaml` (and to `dependency_overrides` if it is a local package under `packages/`). + + + Import it in `plugin_registry.dart` and add an instance to `kRegisteredPlugins`. + + + +### The YourSSHPlugin interface + +Every Dart plugin implements `YourSSHPlugin` from `packages/yourssh_plugin_api`: + +- `buildUI(context, pluginContext)` returns the plugin's widget. Wrap it in `YsPluginHost` (from `yourssh_ui`) so it keeps the app's forui theme even when it is mounted outside the app's root builder, as Snippets, DevOps and Web Tools do. +- `onActivate(ctx)` and `onDeactivate()` are lifecycle hooks. +- `minApiVersion` is checked at runtime against the app's API version. + +`YourSSHPluginContext` gives a plugin controlled access to the app: the active sessions, `execCommand(sessionId, cmd)`, `sendInput(sessionId, text)` to type into a session's terminal (Snippets uses it to insert a snippet), and namespaced `savePreference` and `getPreference`. + +Dart plugins can be switched on and off with feature flags in **Settings**. + +## JavaScript script plugins + +Script plugins live in `~/.yourssh/plugins/`, one folder each, with a `plugin.json` manifest. The runtime is the `packages/yourssh_script_engine` package. + +### Components + +```text +PluginLoader scans the plugins folder, loads plugins, hot-reloads on change + └── QuickJsRuntime one isolated QuickJS context per plugin (Dart FFI) + ├── JsRuntimeRegistrar exposes the Dart bridge APIs to JS + ├── HookBus routes events to plugin handlers + └── PermissionGuard checks every call against the manifest +``` + +- **`PluginManifest`** parses and validates `plugin.json`: id, name, version, entry file, minimum app version and permissions. An unknown permission is rejected. +- **`PluginUiRegistry`** lets a plugin register UI through `ui.register(id, spec)`; the app renders it in the plugin manager. A plugin can also declare a **panel**, an HTML view shown in the app. A panel is plugin-controlled HTML, so its messages to the app (running a command, listing sessions, reading a file) go through the same permission checks as the JavaScript bridges. +- The plugin manager screens let users enable or disable a plugin, reload it and read its `console.log` output. + +### Hooks + +The `HookBus` delivers typed events to plugin handlers in three styles: + +| Style | What the handler can do | +|---|---| +| Transform | Modify the data, for example rewrite terminal output. | +| Intercept | Block the event entirely. | +| Observe | Run side effects only; it can't change the data. | + +The app wires the bus into `SshService`, so plugins see `terminal.output`, `terminal.input`, session connect and disconnect events, and `ssh.exec` command events. The complete list of events and the permission each one needs is in [Plugin authoring](/developer-guide/plugin-authoring). + +### Bridges + +Bridges are the Dart APIs a plugin can call from JavaScript: + +| Bridge | Calls | +|---|---| +| `ssh` | `ssh.exec(sessionId, cmd)`, `ssh.write(sessionId, data)` | +| `sftp` | `sftp.list`, `sftp.readFile`, `sftp.writeFile` | +| `storage` | `storage.get`, `storage.set`, `storage.delete`, namespaced per plugin | +| `ui` | `ui.showNotification(msg)`, `ui.register(id, spec)` | + +### Permissions + +A plugin must declare each permission in its manifest. The recognized permissions are: + +`terminal.read`, `terminal.transform`, `terminal.intercept`, `terminal.inject`, `session.observe`, `session.control`, `ssh.exec`, `sftp.read`, `sftp.write`, `command.intercept`, `ui.notify`, `ui.statusbar`, `ui.panel`, `ui.clipboard`. + +`PermissionGuard` checks the manifest before it dispatches any bridge call. Observing is separate from changing: `terminal.read` observes output only, and rewriting it needs `terminal.transform`. + +### Consent + +The first time a plugin loads, the app shows a consent dialog listing the permissions it asks for. The user must accept before the plugin runs. + +- Consent is bound to a SHA-256 hash of **every file** in the plugin folder. Change any file and the user is asked again. +- Stored grants are intersected with the manifest's current permissions, so a plugin can't gain a permission by editing its manifest. +- Pending consent requests queue in order. +- `manifest.entry` and a panel's HTML entry must stay inside the plugin folder. Paths with `../`, absolute paths and symlinks that escape are rejected. + +### Execution limits + +The C bridge (`packages/yourssh_script_engine/native/bridge/qjs_bridge.c`) enforces hard limits on every plugin: + +| Limit | Value | +|---|---| +| Time per hook or panel message | 250 ms | +| Time to load | 5 s | +| Memory | 64 MiB | +| Stack | 512 KiB | + +A call that exceeds its deadline raises `QuickJsTimeoutException`. + +### Circuit breaker + +`PluginErrorTracker` protects the app from a misbehaving plugin. An error counts 1, a timeout counts 5 and a success resets the count. At 10, the plugin's hooks are skipped and the plugin is unloaded. The user can see what happened in the plugin's console. + +### Reserved built-in ids + +The ids of the built-in Dart plugins are reserved. `PluginLoader` never loads or prompts for a script plugin with a reserved id, so a script plugin can't impersonate Snippets, DevOps Hub or Web Tools. + + +Only the macOS arm64 QuickJS library (`libqjsbridge.dylib`) is prebuilt. See [Build from source](/developer-guide/build#javascript-plugin-runtime) to rebuild it after changing the C bridge. + + +## Related pages + +- [Plugin authoring](/developer-guide/plugin-authoring) +- [Architecture](/developer-guide/architecture) diff --git a/development.mdx b/development.mdx deleted file mode 100644 index ac633ba..0000000 --- a/development.mdx +++ /dev/null @@ -1,94 +0,0 @@ ---- -title: 'Development' -description: 'Preview changes locally to update your docs' ---- - - - **Prerequisites**: - - Node.js version 19 or higher - - A docs repository with a `docs.json` file - - -Follow these steps to install and run Mintlify on your operating system. - - - - -```bash -npm i -g mint -``` - - - - -Navigate to your docs directory where your `docs.json` file is located, and run the following command: - -```bash -mint dev -``` - -A local preview of your documentation will be available at `http://localhost:3000`. - - - - -## Custom ports - -By default, Mintlify uses port 3000. You can customize the port Mintlify runs on by using the `--port` flag. For example, to run Mintlify on port 3333, use this command: - -```bash -mint dev --port 3333 -``` - -If you attempt to run Mintlify on a port that's already in use, it will use the next available port: - -```md -Port 3000 is already in use. Trying 3001 instead. -``` - -## Mintlify versions - -Please note that each CLI release is associated with a specific version of Mintlify. If your local preview does not align with the production version, please update the CLI: - -```bash -npm mint update -``` - -## Validating links - -The CLI can assist with validating links in your documentation. To identify any broken links, use the following command: - -```bash -mint broken-links -``` - -## Deployment - -If the deployment is successful, you should see the following: - - - Screenshot of a deployment confirmation message that says All checks have passed. - - -## Code formatting - -We suggest using extensions on your IDE to recognize and format MDX. If you're a VSCode user, consider the [MDX VSCode extension](https://marketplace.visualstudio.com/items?itemName=unifiedjs.vscode-mdx) for syntax highlighting, and [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) for code formatting. - -## Troubleshooting - - - - - This may be due to an outdated version of node. Try the following: - 1. Remove the currently-installed version of the CLI: `npm remove -g mint` - 2. Upgrade to Node v19 or higher. - 3. Reinstall the CLI: `npm i -g mint` - - - - - Solution: Go to the root of your device and delete the `~/.mintlify` folder. Then run `mint dev` again. - - - -Curious about what changed in the latest CLI version? Check out the [CLI changelog](https://www.npmjs.com/package/mintlify?activeTab=versions). diff --git a/docs.json b/docs.json index 6195f5f..719970e 100644 --- a/docs.json +++ b/docs.json @@ -2,67 +2,105 @@ "$schema": "https://mintlify.com/docs.json", "theme": "mint", "name": "YourSSH", + "description": "YourSSH is a fast, open-source SSH, SFTP, RDP and VNC client for macOS, Windows, Linux and Android.", "colors": { - "primary": "#16A34A", - "light": "#07C983", - "dark": "#15803D" + "primary": "#E87C08", + "light": "#F3A231", + "dark": "#C76A06" + }, + "appearance": { + "default": "dark" }, "favicon": "/favicon.svg", + "icons": { + "library": "lucide" + }, + "logo": { + "light": "/logo/light.svg", + "dark": "/logo/dark.svg", + "href": "https://github.com/YoursshLabs/yourssh" + }, "navigation": { "tabs": [ { - "tab": "Guides", + "tab": "User guide", "groups": [ { - "group": "Getting started", + "group": "Get started", "pages": [ "index", - "quickstart", - "development" + "installation", + "quickstart" + ] + }, + { + "group": "Connections", + "pages": [ + "user-guide/hosts", + "user-guide/host-keys", + "user-guide/terminal", + "user-guide/terminal-sharing", + "user-guide/bulk-actions", + "user-guide/port-forwarding" + ] + }, + { + "group": "Files", + "pages": [ + "user-guide/sftp" + ] + }, + { + "group": "Remote desktop", + "pages": [ + "user-guide/rdp", + "user-guide/vnc" ] }, { - "group": "Customization", + "group": "Security", "pages": [ - "essentials/settings", - "essentials/navigation" + "user-guide/keychain", + "user-guide/recording", + "user-guide/audit-log" ] }, { - "group": "Writing content", + "group": "Tools", "pages": [ - "essentials/markdown", - "essentials/code", - "essentials/images", - "essentials/reusable-snippets" + "user-guide/snippets", + "user-guide/ai-chat", + "user-guide/devops", + "user-guide/web-tools", + "user-guide/cli" ] }, { - "group": "AI tools", + "group": "Settings and sync", "pages": [ - "ai-tools/cursor", - "ai-tools/claude-code", - "ai-tools/windsurf" + "user-guide/settings", + "user-guide/sync", + "user-guide/mobile" ] } ] }, { - "tab": "API reference", + "tab": "Developer guide", "groups": [ { - "group": "API documentation", + "group": "Develop", "pages": [ - "api-reference/introduction" + "developer-guide/architecture", + "developer-guide/build", + "developer-guide/contributing" ] }, { - "group": "Endpoint examples", + "group": "Plugins", "pages": [ - "api-reference/endpoint/get", - "api-reference/endpoint/create", - "api-reference/endpoint/delete", - "api-reference/endpoint/webhook" + "developer-guide/plugin-system", + "developer-guide/plugin-authoring" ] } ] @@ -71,52 +109,43 @@ "global": { "anchors": [ { - "anchor": "Documentation", - "href": "https://mintlify.com/docs", - "icon": "book-open-cover" + "anchor": "GitHub", + "href": "https://github.com/YoursshLabs/yourssh", + "icon": "github" }, { - "anchor": "Blog", - "href": "https://mintlify.com/blog", - "icon": "newspaper" + "anchor": "Releases", + "href": "https://github.com/YoursshLabs/yourssh/releases", + "icon": "download" } ] } }, - "logo": { - "light": "/logo/light.svg", - "dark": "/logo/dark.svg" - }, "navbar": { "links": [ { - "label": "Support", - "href": "mailto:hi@mintlify.com" + "label": "Issues", + "href": "https://github.com/YoursshLabs/yourssh/issues" } ], "primary": { "type": "button", - "label": "Dashboard", - "href": "https://dashboard.mintlify.com" + "label": "Download", + "href": "https://github.com/YoursshLabs/yourssh/releases/latest" } }, "contextual": { "options": [ - "copy", - "view", - "chatgpt", - "claude", - "perplexity", - "mcp", - "cursor", - "vscode" - ] + "copy", + "view", + "chatgpt", + "claude", + "perplexity" + ] }, "footer": { "socials": { - "x": "https://x.com/mintlify", - "github": "https://github.com/mintlify", - "linkedin": "https://linkedin.com/company/mintlify" + "github": "https://github.com/YoursshLabs/yourssh" } } } diff --git a/essentials/code.mdx b/essentials/code.mdx deleted file mode 100644 index ae2abbf..0000000 --- a/essentials/code.mdx +++ /dev/null @@ -1,35 +0,0 @@ ---- -title: 'Code blocks' -description: 'Display inline code and code blocks' -icon: 'code' ---- - -## Inline code - -To denote a `word` or `phrase` as code, enclose it in backticks (`). - -``` -To denote a `word` or `phrase` as code, enclose it in backticks (`). -``` - -## Code blocks - -Use [fenced code blocks](https://www.markdownguide.org/extended-syntax/#fenced-code-blocks) by enclosing code in three backticks and follow the leading ticks with the programming language of your snippet to get syntax highlighting. Optionally, you can also write the name of your code after the programming language. - -```java HelloWorld.java -class HelloWorld { - public static void main(String[] args) { - System.out.println("Hello, World!"); - } -} -``` - -````md -```java HelloWorld.java -class HelloWorld { - public static void main(String[] args) { - System.out.println("Hello, World!"); - } -} -``` -```` diff --git a/essentials/images.mdx b/essentials/images.mdx deleted file mode 100644 index 1144eb2..0000000 --- a/essentials/images.mdx +++ /dev/null @@ -1,59 +0,0 @@ ---- -title: 'Images and embeds' -description: 'Add image, video, and other HTML elements' -icon: 'image' ---- - - - -## Image - -### Using Markdown - -The [markdown syntax](https://www.markdownguide.org/basic-syntax/#images) lets you add images using the following code - -```md -![title](/path/image.jpg) -``` - -Note that the image file size must be less than 5MB. Otherwise, we recommend hosting on a service like [Cloudinary](https://cloudinary.com/) or [S3](https://aws.amazon.com/s3/). You can then use that URL and embed. - -### Using embeds - -To get more customizability with images, you can also use [embeds](/writing-content/embed) to add images - -```html - -``` - -## Embeds and HTML elements - - - -
- - - -Mintlify supports [HTML tags in Markdown](https://www.markdownguide.org/basic-syntax/#html). This is helpful if you prefer HTML tags to Markdown syntax, and lets you create documentation with infinite flexibility. - - - -### iFrames - -Loads another HTML page within the document. Most commonly used for embedding videos. - -```html - -``` diff --git a/essentials/markdown.mdx b/essentials/markdown.mdx deleted file mode 100644 index a45c1d5..0000000 --- a/essentials/markdown.mdx +++ /dev/null @@ -1,88 +0,0 @@ ---- -title: 'Markdown syntax' -description: 'Text, title, and styling in standard markdown' -icon: 'text-size' ---- - -## Titles - -Best used for section headers. - -```md -## Titles -``` - -### Subtitles - -Best used for subsection headers. - -```md -### Subtitles -``` - - - -Each **title** and **subtitle** creates an anchor and also shows up on the table of contents on the right. - - - -## Text formatting - -We support most markdown formatting. Simply add `**`, `_`, or `~` around text to format it. - -| Style | How to write it | Result | -| ------------- | ----------------- | --------------- | -| Bold | `**bold**` | **bold** | -| Italic | `_italic_` | _italic_ | -| Strikethrough | `~strikethrough~` | ~strikethrough~ | - -You can combine these. For example, write `**_bold and italic_**` to get **_bold and italic_** text. - -You need to use HTML to write superscript and subscript text. That is, add `` or `` around your text. - -| Text Size | How to write it | Result | -| ----------- | ------------------------ | ---------------------- | -| Superscript | `superscript` | superscript | -| Subscript | `subscript` | subscript | - -## Linking to pages - -You can add a link by wrapping text in `[]()`. You would write `[link to google](https://google.com)` to [link to google](https://google.com). - -Links to pages in your docs need to be root-relative. Basically, you should include the entire folder path. For example, `[link to text](/writing-content/text)` links to the page "Text" in our components section. - -Relative links like `[link to text](../text)` will open slower because we cannot optimize them as easily. - -## Blockquotes - -### Singleline - -To create a blockquote, add a `>` in front of a paragraph. - -> Dorothy followed her through many of the beautiful rooms in her castle. - -```md -> Dorothy followed her through many of the beautiful rooms in her castle. -``` - -### Multiline - -> Dorothy followed her through many of the beautiful rooms in her castle. -> -> The Witch bade her clean the pots and kettles and sweep the floor and keep the fire fed with wood. - -```md -> Dorothy followed her through many of the beautiful rooms in her castle. -> -> The Witch bade her clean the pots and kettles and sweep the floor and keep the fire fed with wood. -``` - -### LaTeX - -Mintlify supports [LaTeX](https://www.latex-project.org) through the Latex component. - -8 x (vk x H1 - H2) = (0,1) - -```md -8 x (vk x H1 - H2) = (0,1) -``` diff --git a/essentials/navigation.mdx b/essentials/navigation.mdx deleted file mode 100644 index 60adeff..0000000 --- a/essentials/navigation.mdx +++ /dev/null @@ -1,87 +0,0 @@ ---- -title: 'Navigation' -description: 'The navigation field in docs.json defines the pages that go in the navigation menu' -icon: 'map' ---- - -The navigation menu is the list of links on every website. - -You will likely update `docs.json` every time you add a new page. Pages do not show up automatically. - -## Navigation syntax - -Our navigation syntax is recursive which means you can make nested navigation groups. You don't need to include `.mdx` in page names. - - - -```json Regular Navigation -"navigation": { - "tabs": [ - { - "tab": "Docs", - "groups": [ - { - "group": "Getting Started", - "pages": ["quickstart"] - } - ] - } - ] -} -``` - -```json Nested Navigation -"navigation": { - "tabs": [ - { - "tab": "Docs", - "groups": [ - { - "group": "Getting Started", - "pages": [ - "quickstart", - { - "group": "Nested Reference Pages", - "pages": ["nested-reference-page"] - } - ] - } - ] - } - ] -} -``` - - - -## Folders - -Simply put your MDX files in folders and update the paths in `docs.json`. - -For example, to have a page at `https://yoursite.com/your-folder/your-page` you would make a folder called `your-folder` containing an MDX file called `your-page.mdx`. - - - -You cannot use `api` for the name of a folder unless you nest it inside another folder. Mintlify uses Next.js which reserves the top-level `api` folder for internal server calls. A folder name such as `api-reference` would be accepted. - - - -```json Navigation With Folder -"navigation": { - "tabs": [ - { - "tab": "Docs", - "groups": [ - { - "group": "Group Name", - "pages": ["your-folder/your-page"] - } - ] - } - ] -} -``` - -## Hidden pages - -MDX files not included in `docs.json` will not show up in the sidebar but are accessible through the search bar and by linking directly to them. diff --git a/essentials/reusable-snippets.mdx b/essentials/reusable-snippets.mdx deleted file mode 100644 index 376e27b..0000000 --- a/essentials/reusable-snippets.mdx +++ /dev/null @@ -1,110 +0,0 @@ ---- -title: "Reusable snippets" -description: "Reusable, custom snippets to keep content in sync" -icon: "recycle" ---- - -import SnippetIntro from '/snippets/snippet-intro.mdx'; - - - -## Creating a custom snippet - -**Pre-condition**: You must create your snippet file in the `snippets` directory. - - - Any page in the `snippets` directory will be treated as a snippet and will not - be rendered into a standalone page. If you want to create a standalone page - from the snippet, import the snippet into another file and call it as a - component. - - -### Default export - -1. Add content to your snippet file that you want to re-use across multiple - locations. Optionally, you can add variables that can be filled in via props - when you import the snippet. - -```mdx snippets/my-snippet.mdx -Hello world! This is my content I want to reuse across pages. My keyword of the -day is {word}. -``` - - - The content that you want to reuse must be inside the `snippets` directory in - order for the import to work. - - -2. Import the snippet into your destination file. - -```mdx destination-file.mdx ---- -title: My title -description: My Description ---- - -import MySnippet from '/snippets/path/to/my-snippet.mdx'; - -## Header - -Lorem impsum dolor sit amet. - - -``` - -### Reusable variables - -1. Export a variable from your snippet file: - -```mdx snippets/path/to/custom-variables.mdx -export const myName = 'my name'; - -export const myObject = { fruit: 'strawberries' }; -``` - -2. Import the snippet from your destination file and use the variable: - -```mdx destination-file.mdx ---- -title: My title -description: My Description ---- - -import { myName, myObject } from '/snippets/path/to/custom-variables.mdx'; - -Hello, my name is {myName} and I like {myObject.fruit}. -``` - -### Reusable components - -1. Inside your snippet file, create a component that takes in props by exporting - your component in the form of an arrow function. - -```mdx snippets/custom-component.mdx -export const MyComponent = ({ title }) => ( -
-

{title}

-

... snippet content ...

-
-); -``` - - - MDX does not compile inside the body of an arrow function. Stick to HTML - syntax when you can or use a default export if you need to use MDX. - - -2. Import the snippet into your destination file and pass in the props - -```mdx destination-file.mdx ---- -title: My title -description: My Description ---- - -import { MyComponent } from '/snippets/custom-component.mdx'; - -Lorem ipsum dolor sit amet. - - -``` diff --git a/essentials/settings.mdx b/essentials/settings.mdx deleted file mode 100644 index 884de13..0000000 --- a/essentials/settings.mdx +++ /dev/null @@ -1,318 +0,0 @@ ---- -title: 'Global Settings' -description: 'Mintlify gives you complete control over the look and feel of your documentation using the docs.json file' -icon: 'gear' ---- - -Every Mintlify site needs a `docs.json` file with the core configuration settings. Learn more about the [properties](#properties) below. - -## Properties - - -Name of your project. Used for the global title. - -Example: `mintlify` - - - - - An array of groups with all the pages within that group - - - The name of the group. - - Example: `Settings` - - - - The relative paths to the markdown files that will serve as pages. - - Example: `["customization", "page"]` - - - - - - - - Path to logo image or object with path to "light" and "dark" mode logo images - - - Path to the logo in light mode - - - Path to the logo in dark mode - - - Where clicking on the logo links you to - - - - - - Path to the favicon image - - - - Hex color codes for your global theme - - - The primary color. Used for most often for highlighted content, section - headers, accents, in light mode - - - The primary color for dark mode. Used for most often for highlighted - content, section headers, accents, in dark mode - - - The primary color for important buttons - - - The color of the background in both light and dark mode - - - The hex color code of the background in light mode - - - The hex color code of the background in dark mode - - - - - - - - Array of `name`s and `url`s of links you want to include in the topbar - - - The name of the button. - - Example: `Contact us` - - - The url once you click on the button. Example: `https://mintlify.com/docs` - - - - - - - - - Link shows a button. GitHub shows the repo information at the url provided including the number of GitHub stars. - - - If `link`: What the button links to. - - If `github`: Link to the repository to load GitHub information from. - - - Text inside the button. Only required if `type` is a `link`. - - - - - - - Array of version names. Only use this if you want to show different versions - of docs with a dropdown in the navigation bar. - - - - An array of the anchors, includes the `icon`, `color`, and `url`. - - - The [Font Awesome](https://fontawesome.com/search?q=heart) icon used to feature the anchor. - - Example: `comments` - - - The name of the anchor label. - - Example: `Community` - - - The start of the URL that marks what pages go in the anchor. Generally, this is the name of the folder you put your pages in. - - - The hex color of the anchor icon background. Can also be a gradient if you pass an object with the properties `from` and `to` that are each a hex color. - - - Used if you want to hide an anchor until the correct docs version is selected. - - - Pass `true` if you want to hide the anchor until you directly link someone to docs inside it. - - - One of: "brands", "duotone", "light", "sharp-solid", "solid", or "thin" - - - - - - - Override the default configurations for the top-most anchor. - - - The name of the top-most anchor - - - Font Awesome icon. - - - One of: "brands", "duotone", "light", "sharp-solid", "solid", or "thin" - - - - - - An array of navigational tabs. - - - The name of the tab label. - - - The start of the URL that marks what pages go in the tab. Generally, this - is the name of the folder you put your pages in. - - - - - - Configuration for API settings. Learn more about API pages at [API Components](/api-playground/demo). - - - The base url for all API endpoints. If `baseUrl` is an array, it will enable for multiple base url - options that the user can toggle. - - - - - - The authentication strategy used for all API endpoints. - - - The name of the authentication parameter used in the API playground. - - If method is `basic`, the format should be `[usernameName]:[passwordName]` - - - The default value that's designed to be a prefix for the authentication input field. - - E.g. If an `inputPrefix` of `AuthKey` would inherit the default input result of the authentication field as `AuthKey`. - - - - - - Configurations for the API playground - - - - Whether the playground is showing, hidden, or only displaying the endpoint with no added user interactivity `simple` - - Learn more at the [playground guides](/api-playground/demo) - - - - - - Enabling this flag ensures that key ordering in OpenAPI pages matches the key ordering defined in the OpenAPI file. - - This behavior will soon be enabled by default, at which point this field will be deprecated. - - - - - - - A string or an array of strings of URL(s) or relative path(s) pointing to your - OpenAPI file. - - Examples: - - ```json Absolute - "openapi": "https://example.com/openapi.json" - ``` - ```json Relative - "openapi": "/openapi.json" - ``` - ```json Multiple - "openapi": ["https://example.com/openapi1.json", "/openapi2.json", "/openapi3.json"] - ``` - - - - - - An object of social media accounts where the key:property pair represents the social media platform and the account url. - - Example: - ```json - { - "x": "https://x.com/mintlify", - "website": "https://mintlify.com" - } - ``` - - - One of the following values `website`, `facebook`, `x`, `discord`, `slack`, `github`, `linkedin`, `instagram`, `hacker-news` - - Example: `x` - - - The URL to the social platform. - - Example: `https://x.com/mintlify` - - - - - - Configurations to enable feedback buttons - - - - Enables a button to allow users to suggest edits via pull requests - - - Enables a button to allow users to raise an issue about the documentation - - - - - - Customize the dark mode toggle. - - - Set if you always want to show light or dark mode for new users. When not - set, we default to the same mode as the user's operating system. - - - Set to true to hide the dark/light mode toggle. You can combine `isHidden` with `default` to force your docs to only use light or dark mode. For example: - - - ```json Only Dark Mode - "modeToggle": { - "default": "dark", - "isHidden": true - } - ``` - - ```json Only Light Mode - "modeToggle": { - "default": "light", - "isHidden": true - } - ``` - - - - - - - - - A background image to be displayed behind every page. See example with - [Infisical](https://infisical.com/docs) and [FRPC](https://frpc.io). - diff --git a/favicon.svg b/favicon.svg index d50ceed..31bbab3 100644 --- a/favicon.svg +++ b/favicon.svg @@ -1,5 +1,90 @@ - - - - + + + + + + + + + + + + + + + + + + + diff --git a/images/01-first-launch/01-empty-dashboard.png b/images/01-first-launch/01-empty-dashboard.png new file mode 100644 index 0000000..de8f84f Binary files /dev/null and b/images/01-first-launch/01-empty-dashboard.png differ diff --git a/images/02-add-host/01-new-host-panel.png b/images/02-add-host/01-new-host-panel.png new file mode 100644 index 0000000..02fd17d Binary files /dev/null and b/images/02-add-host/01-new-host-panel.png differ diff --git a/images/02-add-host/04-section-template.png b/images/02-add-host/04-section-template.png new file mode 100644 index 0000000..44c5769 Binary files /dev/null and b/images/02-add-host/04-section-template.png differ diff --git a/images/02-add-host/05-section-options.png b/images/02-add-host/05-section-options.png new file mode 100644 index 0000000..978b7f1 Binary files /dev/null and b/images/02-add-host/05-section-options.png differ diff --git a/images/02-add-host/06-section-group.png b/images/02-add-host/06-section-group.png new file mode 100644 index 0000000..afcf869 Binary files /dev/null and b/images/02-add-host/06-section-group.png differ diff --git a/images/02-add-host/07-validation-required.png b/images/02-add-host/07-validation-required.png new file mode 100644 index 0000000..031e070 Binary files /dev/null and b/images/02-add-host/07-validation-required.png differ diff --git a/images/02-add-host/09-filled-form.png b/images/02-add-host/09-filled-form.png new file mode 100644 index 0000000..4ab2af5 Binary files /dev/null and b/images/02-add-host/09-filled-form.png differ diff --git a/images/02-add-host/10-test-result.png b/images/02-add-host/10-test-result.png new file mode 100644 index 0000000..1a65df7 Binary files /dev/null and b/images/02-add-host/10-test-result.png differ diff --git a/images/02-add-host/11-dashboard-with-host.png b/images/02-add-host/11-dashboard-with-host.png new file mode 100644 index 0000000..7b00c89 Binary files /dev/null and b/images/02-add-host/11-dashboard-with-host.png differ diff --git a/images/03-first-connect/02-card-hover-actions.png b/images/03-first-connect/02-card-hover-actions.png new file mode 100644 index 0000000..e864ba5 Binary files /dev/null and b/images/03-first-connect/02-card-hover-actions.png differ diff --git a/images/03-first-connect/07-terminal-ls.png b/images/03-first-connect/07-terminal-ls.png new file mode 100644 index 0000000..85a34c6 Binary files /dev/null and b/images/03-first-connect/07-terminal-ls.png differ diff --git a/images/03-first-connect/09-terminal-search.png b/images/03-first-connect/09-terminal-search.png new file mode 100644 index 0000000..f9035b9 Binary files /dev/null and b/images/03-first-connect/09-terminal-search.png differ diff --git a/images/03-first-connect/10-input-bar.png b/images/03-first-connect/10-input-bar.png new file mode 100644 index 0000000..66ca223 Binary files /dev/null and b/images/03-first-connect/10-input-bar.png differ diff --git a/images/03-first-connect/13-terminal-context-menu.png b/images/03-first-connect/13-terminal-context-menu.png new file mode 100644 index 0000000..c4badeb Binary files /dev/null and b/images/03-first-connect/13-terminal-context-menu.png differ diff --git a/images/03-first-connect/14-tab-context-menu.png b/images/03-first-connect/14-tab-context-menu.png new file mode 100644 index 0000000..30febd5 Binary files /dev/null and b/images/03-first-connect/14-tab-context-menu.png differ diff --git a/images/03-first-connect/17-snippets-panel.png b/images/03-first-connect/17-snippets-panel.png new file mode 100644 index 0000000..b64345c Binary files /dev/null and b/images/03-first-connect/17-snippets-panel.png differ diff --git a/images/03-first-connect/19-theme-picker.png b/images/03-first-connect/19-theme-picker.png new file mode 100644 index 0000000..cc1860f Binary files /dev/null and b/images/03-first-connect/19-theme-picker.png differ diff --git a/images/03-first-connect/20-recording-active.png b/images/03-first-connect/20-recording-active.png new file mode 100644 index 0000000..26e7e17 Binary files /dev/null and b/images/03-first-connect/20-recording-active.png differ diff --git a/images/04-keychain/02-generate-panel.png b/images/04-keychain/02-generate-panel.png new file mode 100644 index 0000000..7adb9f2 Binary files /dev/null and b/images/04-keychain/02-generate-panel.png differ diff --git a/images/04-keychain/04-generated-result.png b/images/04-keychain/04-generated-result.png new file mode 100644 index 0000000..9d93f8d Binary files /dev/null and b/images/04-keychain/04-generated-result.png differ diff --git a/images/04-keychain/05-key-list.png b/images/04-keychain/05-key-list.png new file mode 100644 index 0000000..e6634eb Binary files /dev/null and b/images/04-keychain/05-key-list.png differ diff --git a/images/04-keychain/06-key-hover-actions.png b/images/04-keychain/06-key-hover-actions.png new file mode 100644 index 0000000..47f8b5f Binary files /dev/null and b/images/04-keychain/06-key-hover-actions.png differ diff --git a/images/04-keychain/07-deploy-dialog.png b/images/04-keychain/07-deploy-dialog.png new file mode 100644 index 0000000..47f8b5f Binary files /dev/null and b/images/04-keychain/07-deploy-dialog.png differ diff --git a/images/04-keychain/08-remove-confirm.png b/images/04-keychain/08-remove-confirm.png new file mode 100644 index 0000000..6a46208 Binary files /dev/null and b/images/04-keychain/08-remove-confirm.png differ diff --git a/images/05-more-hosts/01-auth-method-menu.png b/images/05-more-hosts/01-auth-method-menu.png new file mode 100644 index 0000000..3145fb5 Binary files /dev/null and b/images/05-more-hosts/01-auth-method-menu.png differ diff --git a/images/05-more-hosts/03-key-auth-form.png b/images/05-more-hosts/03-key-auth-form.png new file mode 100644 index 0000000..65d534f Binary files /dev/null and b/images/05-more-hosts/03-key-auth-form.png differ diff --git a/images/05-more-hosts/05-chain-picker.png b/images/05-more-hosts/05-chain-picker.png new file mode 100644 index 0000000..896a38e Binary files /dev/null and b/images/05-more-hosts/05-chain-picker.png differ diff --git a/images/05-more-hosts/06-chain-with-hop.png b/images/05-more-hosts/06-chain-with-hop.png new file mode 100644 index 0000000..37aa800 Binary files /dev/null and b/images/05-more-hosts/06-chain-with-hop.png differ diff --git a/images/05-more-hosts/08-host-key-type-changed.png b/images/05-more-hosts/08-host-key-type-changed.png new file mode 100644 index 0000000..70cdd94 Binary files /dev/null and b/images/05-more-hosts/08-host-key-type-changed.png differ diff --git a/images/05-more-hosts/09-chain-terminal.png b/images/05-more-hosts/09-chain-terminal.png new file mode 100644 index 0000000..869a22b Binary files /dev/null and b/images/05-more-hosts/09-chain-terminal.png differ diff --git a/images/05-more-hosts/10-split-two-sessions.png b/images/05-more-hosts/10-split-two-sessions.png new file mode 100644 index 0000000..dfba5ae Binary files /dev/null and b/images/05-more-hosts/10-split-two-sessions.png differ diff --git a/images/05-more-hosts/11-split-two-sessions-vertical.png b/images/05-more-hosts/11-split-two-sessions-vertical.png new file mode 100644 index 0000000..be67e5c Binary files /dev/null and b/images/05-more-hosts/11-split-two-sessions-vertical.png differ diff --git a/images/06-dashboard/01-grid.png b/images/06-dashboard/01-grid.png new file mode 100644 index 0000000..99943b4 Binary files /dev/null and b/images/06-dashboard/01-grid.png differ diff --git a/images/06-dashboard/02-list.png b/images/06-dashboard/02-list.png new file mode 100644 index 0000000..e8a2375 Binary files /dev/null and b/images/06-dashboard/02-list.png differ diff --git a/images/06-dashboard/03-sort-menu.png b/images/06-dashboard/03-sort-menu.png new file mode 100644 index 0000000..3fb8d5a Binary files /dev/null and b/images/06-dashboard/03-sort-menu.png differ diff --git a/images/06-dashboard/04-search.png b/images/06-dashboard/04-search.png new file mode 100644 index 0000000..6273cce Binary files /dev/null and b/images/06-dashboard/04-search.png differ diff --git a/images/06-dashboard/05-card-menu.png b/images/06-dashboard/05-card-menu.png new file mode 100644 index 0000000..464a235 Binary files /dev/null and b/images/06-dashboard/05-card-menu.png differ diff --git a/images/06-dashboard/06-delete-confirm.png b/images/06-dashboard/06-delete-confirm.png new file mode 100644 index 0000000..e3c76b1 Binary files /dev/null and b/images/06-dashboard/06-delete-confirm.png differ diff --git a/images/06-dashboard/07-select-mode.png b/images/06-dashboard/07-select-mode.png new file mode 100644 index 0000000..8a6e19f Binary files /dev/null and b/images/06-dashboard/07-select-mode.png differ diff --git a/images/06-dashboard/08-select-all.png b/images/06-dashboard/08-select-all.png new file mode 100644 index 0000000..12ec642 Binary files /dev/null and b/images/06-dashboard/08-select-all.png differ diff --git a/images/06-dashboard/09-bulk-run-empty.png b/images/06-dashboard/09-bulk-run-empty.png new file mode 100644 index 0000000..16dea5f Binary files /dev/null and b/images/06-dashboard/09-bulk-run-empty.png differ diff --git a/images/06-dashboard/10-bulk-run-results.png b/images/06-dashboard/10-bulk-run-results.png new file mode 100644 index 0000000..918f165 Binary files /dev/null and b/images/06-dashboard/10-bulk-run-results.png differ diff --git a/images/06-dashboard/10b-bulk-run-row-expanded.png b/images/06-dashboard/10b-bulk-run-row-expanded.png new file mode 100644 index 0000000..49275e8 Binary files /dev/null and b/images/06-dashboard/10b-bulk-run-row-expanded.png differ diff --git a/images/06-dashboard/11-bulk-run-diff.png b/images/06-dashboard/11-bulk-run-diff.png new file mode 100644 index 0000000..94b9fc5 Binary files /dev/null and b/images/06-dashboard/11-bulk-run-diff.png differ diff --git a/images/06-dashboard/13-bulk-push-filled.png b/images/06-dashboard/13-bulk-push-filled.png new file mode 100644 index 0000000..f885370 Binary files /dev/null and b/images/06-dashboard/13-bulk-push-filled.png differ diff --git a/images/07-sftp/02-host-picker.png b/images/07-sftp/02-host-picker.png new file mode 100644 index 0000000..67276fd Binary files /dev/null and b/images/07-sftp/02-host-picker.png differ diff --git a/images/07-sftp/03-dual-panel.png b/images/07-sftp/03-dual-panel.png new file mode 100644 index 0000000..1b99127 Binary files /dev/null and b/images/07-sftp/03-dual-panel.png differ diff --git a/images/07-sftp/06-select-single-click.png b/images/07-sftp/06-select-single-click.png new file mode 100644 index 0000000..c456568 Binary files /dev/null and b/images/07-sftp/06-select-single-click.png differ diff --git a/images/07-sftp/07-remote-context-menu.png b/images/07-sftp/07-remote-context-menu.png new file mode 100644 index 0000000..eb62bdd Binary files /dev/null and b/images/07-sftp/07-remote-context-menu.png differ diff --git a/images/07-sftp/10-upload-progress.png b/images/07-sftp/10-upload-progress.png new file mode 100644 index 0000000..ee53524 Binary files /dev/null and b/images/07-sftp/10-upload-progress.png differ diff --git a/images/07-sftp/12-permissions-dialog.png b/images/07-sftp/12-permissions-dialog.png new file mode 100644 index 0000000..6c6125b Binary files /dev/null and b/images/07-sftp/12-permissions-dialog.png differ diff --git a/images/07-sftp/15b-mkdir-existing.png b/images/07-sftp/15b-mkdir-existing.png new file mode 100644 index 0000000..341120a Binary files /dev/null and b/images/07-sftp/15b-mkdir-existing.png differ diff --git a/images/07-sftp/18-run-file-confirm.png b/images/07-sftp/18-run-file-confirm.png new file mode 100644 index 0000000..ba3917a Binary files /dev/null and b/images/07-sftp/18-run-file-confirm.png differ diff --git a/images/08-port-forwarding/03-validation-port.png b/images/08-port-forwarding/03-validation-port.png new file mode 100644 index 0000000..fb43f88 Binary files /dev/null and b/images/08-port-forwarding/03-validation-port.png differ diff --git a/images/08-port-forwarding/04-local-rule-filled.png b/images/08-port-forwarding/04-local-rule-filled.png new file mode 100644 index 0000000..0414599 Binary files /dev/null and b/images/08-port-forwarding/04-local-rule-filled.png differ diff --git a/images/08-port-forwarding/06-type-menu.png b/images/08-port-forwarding/06-type-menu.png new file mode 100644 index 0000000..483a23d Binary files /dev/null and b/images/08-port-forwarding/06-type-menu.png differ diff --git a/images/08-port-forwarding/07-dynamic-rule-filled.png b/images/08-port-forwarding/07-dynamic-rule-filled.png new file mode 100644 index 0000000..748c439 Binary files /dev/null and b/images/08-port-forwarding/07-dynamic-rule-filled.png differ diff --git a/images/08-port-forwarding/09-running-connections.png b/images/08-port-forwarding/09-running-connections.png new file mode 100644 index 0000000..86443d2 Binary files /dev/null and b/images/08-port-forwarding/09-running-connections.png differ diff --git a/images/08-port-forwarding/10-rule-editor.png b/images/08-port-forwarding/10-rule-editor.png new file mode 100644 index 0000000..1f267d0 Binary files /dev/null and b/images/08-port-forwarding/10-rule-editor.png differ diff --git a/images/09-known-hosts/01-list.png b/images/09-known-hosts/01-list.png new file mode 100644 index 0000000..4c1a6c6 Binary files /dev/null and b/images/09-known-hosts/01-list.png differ diff --git a/images/09-known-hosts/03-remove-confirm.png b/images/09-known-hosts/03-remove-confirm.png new file mode 100644 index 0000000..f853ed4 Binary files /dev/null and b/images/09-known-hosts/03-remove-confirm.png differ diff --git a/images/10-recordings/01-recording-stopped.png b/images/10-recordings/01-recording-stopped.png new file mode 100644 index 0000000..034f1d2 Binary files /dev/null and b/images/10-recordings/01-recording-stopped.png differ diff --git a/images/10-recordings/02-library.png b/images/10-recordings/02-library.png new file mode 100644 index 0000000..2458341 Binary files /dev/null and b/images/10-recordings/02-library.png differ diff --git a/images/10-recordings/03b-player-playing.png b/images/10-recordings/03b-player-playing.png new file mode 100644 index 0000000..86337e4 Binary files /dev/null and b/images/10-recordings/03b-player-playing.png differ diff --git a/images/10-recordings/04-delete-confirm.png b/images/10-recordings/04-delete-confirm.png new file mode 100644 index 0000000..e41a724 Binary files /dev/null and b/images/10-recordings/04-delete-confirm.png differ diff --git a/images/11-audit-log/01-rows.png b/images/11-audit-log/01-rows.png new file mode 100644 index 0000000..74d19ca Binary files /dev/null and b/images/11-audit-log/01-rows.png differ diff --git a/images/11-audit-log/02-type-menu.png b/images/11-audit-log/02-type-menu.png new file mode 100644 index 0000000..7ffc219 Binary files /dev/null and b/images/11-audit-log/02-type-menu.png differ diff --git a/images/11-audit-log/04-search.png b/images/11-audit-log/04-search.png new file mode 100644 index 0000000..5ab88a9 Binary files /dev/null and b/images/11-audit-log/04-search.png differ diff --git a/images/11-audit-log/05-export-csv.png b/images/11-audit-log/05-export-csv.png new file mode 100644 index 0000000..7f29066 Binary files /dev/null and b/images/11-audit-log/05-export-csv.png differ diff --git a/images/11-audit-log/06-clear-confirm.png b/images/11-audit-log/06-clear-confirm.png new file mode 100644 index 0000000..df4406d Binary files /dev/null and b/images/11-audit-log/06-clear-confirm.png differ diff --git a/images/12-rdp/01-editor-rdp-mode.png b/images/12-rdp/01-editor-rdp-mode.png new file mode 100644 index 0000000..024dd41 Binary files /dev/null and b/images/12-rdp/01-editor-rdp-mode.png differ diff --git a/images/12-rdp/02-rdp-security.png b/images/12-rdp/02-rdp-security.png new file mode 100644 index 0000000..b20ef0f Binary files /dev/null and b/images/12-rdp/02-rdp-security.png differ diff --git a/images/12-rdp/04-dashboard-rdp-badge.png b/images/12-rdp/04-dashboard-rdp-badge.png new file mode 100644 index 0000000..ebbec0a Binary files /dev/null and b/images/12-rdp/04-dashboard-rdp-badge.png differ diff --git a/images/12-rdp/05-cert-trust-dialog.png b/images/12-rdp/05-cert-trust-dialog.png new file mode 100644 index 0000000..7d46bc5 Binary files /dev/null and b/images/12-rdp/05-cert-trust-dialog.png differ diff --git a/images/12-rdp/06-session-connected.png b/images/12-rdp/06-session-connected.png new file mode 100644 index 0000000..6afdfe7 Binary files /dev/null and b/images/12-rdp/06-session-connected.png differ diff --git a/images/12-rdp/10-fullscreen-hover-pill.png b/images/12-rdp/10-fullscreen-hover-pill.png new file mode 100644 index 0000000..1010033 Binary files /dev/null and b/images/12-rdp/10-fullscreen-hover-pill.png differ diff --git a/images/12-rdp/12-disconnected.png b/images/12-rdp/12-disconnected.png new file mode 100644 index 0000000..060d48a Binary files /dev/null and b/images/12-rdp/12-disconnected.png differ diff --git a/images/13-vnc/01-editor-vnc-mode.png b/images/13-vnc/01-editor-vnc-mode.png new file mode 100644 index 0000000..a258d01 Binary files /dev/null and b/images/13-vnc/01-editor-vnc-mode.png differ diff --git a/images/13-vnc/03-session-connected.png b/images/13-vnc/03-session-connected.png new file mode 100644 index 0000000..182fa85 Binary files /dev/null and b/images/13-vnc/03-session-connected.png differ diff --git a/images/14-settings/01-settings-top.png b/images/14-settings/01-settings-top.png new file mode 100644 index 0000000..a80cb2e Binary files /dev/null and b/images/14-settings/01-settings-top.png differ diff --git a/images/14-settings/09-sync.png b/images/14-settings/09-sync.png new file mode 100644 index 0000000..f5648f8 Binary files /dev/null and b/images/14-settings/09-sync.png differ diff --git a/images/14-settings/14-hotkeys-screen.png b/images/14-settings/14-hotkeys-screen.png new file mode 100644 index 0000000..75e707e Binary files /dev/null and b/images/14-settings/14-hotkeys-screen.png differ diff --git a/images/14-settings/15-sync-configured.png b/images/14-settings/15-sync-configured.png new file mode 100644 index 0000000..58060b8 Binary files /dev/null and b/images/14-settings/15-sync-configured.png differ diff --git a/images/14-settings/16-sync-p2p.png b/images/14-settings/16-sync-p2p.png new file mode 100644 index 0000000..7d25dc7 Binary files /dev/null and b/images/14-settings/16-sync-p2p.png differ diff --git a/images/14-settings/17-sync-qr-dialog.png b/images/14-settings/17-sync-qr-dialog.png new file mode 100644 index 0000000..4201a8d Binary files /dev/null and b/images/14-settings/17-sync-qr-dialog.png differ diff --git a/images/14-settings/18-sync-import-dialog.png b/images/14-settings/18-sync-import-dialog.png new file mode 100644 index 0000000..bdc8891 Binary files /dev/null and b/images/14-settings/18-sync-import-dialog.png differ diff --git a/images/14-settings/19-sync-disconnect-confirm.png b/images/14-settings/19-sync-disconnect-confirm.png new file mode 100644 index 0000000..c63ce8d Binary files /dev/null and b/images/14-settings/19-sync-disconnect-confirm.png differ diff --git a/images/15-plugins/01-manager.png b/images/15-plugins/01-manager.png new file mode 100644 index 0000000..bf67b5f Binary files /dev/null and b/images/15-plugins/01-manager.png differ diff --git a/images/15-plugins/03-snippets-screen.png b/images/15-plugins/03-snippets-screen.png new file mode 100644 index 0000000..eba7d6b Binary files /dev/null and b/images/15-plugins/03-snippets-screen.png differ diff --git a/images/16-ai-chat/03-configured.png b/images/16-ai-chat/03-configured.png new file mode 100644 index 0000000..11d411a Binary files /dev/null and b/images/16-ai-chat/03-configured.png differ diff --git a/images/16-ai-chat/05-provider-menu.png b/images/16-ai-chat/05-provider-menu.png new file mode 100644 index 0000000..678cf62 Binary files /dev/null and b/images/16-ai-chat/05-provider-menu.png differ diff --git a/images/16-ai-chat/06-multiline-prompt.png b/images/16-ai-chat/06-multiline-prompt.png new file mode 100644 index 0000000..6d4c0bc Binary files /dev/null and b/images/16-ai-chat/06-multiline-prompt.png differ diff --git a/images/17-devops/03-containers-no-docker.png b/images/17-devops/03-containers-no-docker.png new file mode 100644 index 0000000..1b97df7 Binary files /dev/null and b/images/17-devops/03-containers-no-docker.png differ diff --git a/images/17-devops/04-network-tools.png b/images/17-devops/04-network-tools.png new file mode 100644 index 0000000..b27d84e Binary files /dev/null and b/images/17-devops/04-network-tools.png differ diff --git a/images/17-devops/05-ping-result.png b/images/17-devops/05-ping-result.png new file mode 100644 index 0000000..dc480c2 Binary files /dev/null and b/images/17-devops/05-ping-result.png differ diff --git a/images/17-devops/10-cloudflare-rule.png b/images/17-devops/10-cloudflare-rule.png new file mode 100644 index 0000000..b9e3cb2 Binary files /dev/null and b/images/17-devops/10-cloudflare-rule.png differ diff --git a/images/17-devops/16-mail-detail.png b/images/17-devops/16-mail-detail.png new file mode 100644 index 0000000..f79ab83 Binary files /dev/null and b/images/17-devops/16-mail-detail.png differ diff --git a/images/17-devops/17-mail-clear-confirm.png b/images/17-devops/17-mail-clear-confirm.png new file mode 100644 index 0000000..a68153c Binary files /dev/null and b/images/17-devops/17-mail-clear-confirm.png differ diff --git a/images/17-devops/18-mcp-server.png b/images/17-devops/18-mcp-server.png new file mode 100644 index 0000000..558df99 Binary files /dev/null and b/images/17-devops/18-mcp-server.png differ diff --git a/images/17-devops/19-s3-browser.png b/images/17-devops/19-s3-browser.png new file mode 100644 index 0000000..938e3ba Binary files /dev/null and b/images/17-devops/19-s3-browser.png differ diff --git a/images/18-web-tools/01-web-tools.png b/images/18-web-tools/01-web-tools.png new file mode 100644 index 0000000..02c63e4 Binary files /dev/null and b/images/18-web-tools/01-web-tools.png differ diff --git a/images/18-web-tools/03-get-response.png b/images/18-web-tools/03-get-response.png new file mode 100644 index 0000000..b3f397e Binary files /dev/null and b/images/18-web-tools/03-get-response.png differ diff --git a/images/18-web-tools/05-method-menu.png b/images/18-web-tools/05-method-menu.png new file mode 100644 index 0000000..f3b1278 Binary files /dev/null and b/images/18-web-tools/05-method-menu.png differ diff --git a/images/18-web-tools/06-post-body.png b/images/18-web-tools/06-post-body.png new file mode 100644 index 0000000..094a4ec Binary files /dev/null and b/images/18-web-tools/06-post-body.png differ diff --git a/images/18-web-tools/08-history.png b/images/18-web-tools/08-history.png new file mode 100644 index 0000000..42f9239 Binary files /dev/null and b/images/18-web-tools/08-history.png differ diff --git a/images/18-web-tools/09-utilities.png b/images/18-web-tools/09-utilities.png new file mode 100644 index 0000000..66a43b9 Binary files /dev/null and b/images/18-web-tools/09-utilities.png differ diff --git a/images/18-web-tools/12-port-tunnels.png b/images/18-web-tools/12-port-tunnels.png new file mode 100644 index 0000000..7d787c9 Binary files /dev/null and b/images/18-web-tools/12-port-tunnels.png differ diff --git a/images/19-notifications/02-bell-open.png b/images/19-notifications/02-bell-open.png new file mode 100644 index 0000000..1560c26 Binary files /dev/null and b/images/19-notifications/02-bell-open.png differ diff --git a/images/20-small-window/01-dashboard-900.png b/images/20-small-window/01-dashboard-900.png new file mode 100644 index 0000000..f14fd41 Binary files /dev/null and b/images/20-small-window/01-dashboard-900.png differ diff --git a/images/20-small-window/03-terminal-900.png b/images/20-small-window/03-terminal-900.png new file mode 100644 index 0000000..1b1fd3b Binary files /dev/null and b/images/20-small-window/03-terminal-900.png differ diff --git a/images/20-small-window/04-sftp-900.png b/images/20-small-window/04-sftp-900.png new file mode 100644 index 0000000..e116852 Binary files /dev/null and b/images/20-small-window/04-sftp-900.png differ diff --git a/images/20-small-window/05-settings-900.png b/images/20-small-window/05-settings-900.png new file mode 100644 index 0000000..7cb5548 Binary files /dev/null and b/images/20-small-window/05-settings-900.png differ diff --git a/images/M1-mobile/01-app-lock.png b/images/M1-mobile/01-app-lock.png new file mode 100644 index 0000000..83d9f6c Binary files /dev/null and b/images/M1-mobile/01-app-lock.png differ diff --git a/images/M1-mobile/02-hosts.png b/images/M1-mobile/02-hosts.png new file mode 100644 index 0000000..7d877a5 Binary files /dev/null and b/images/M1-mobile/02-hosts.png differ diff --git a/images/M1-mobile/03-host-actions.png b/images/M1-mobile/03-host-actions.png new file mode 100644 index 0000000..676ed38 Binary files /dev/null and b/images/M1-mobile/03-host-actions.png differ diff --git a/images/M1-mobile/05-add-host-scrolled.png b/images/M1-mobile/05-add-host-scrolled.png new file mode 100644 index 0000000..a9924d8 Binary files /dev/null and b/images/M1-mobile/05-add-host-scrolled.png differ diff --git a/images/M1-mobile/06-snippets.png b/images/M1-mobile/06-snippets.png new file mode 100644 index 0000000..5884c64 Binary files /dev/null and b/images/M1-mobile/06-snippets.png differ diff --git a/images/M1-mobile/07-keys.png b/images/M1-mobile/07-keys.png new file mode 100644 index 0000000..0cdccbd Binary files /dev/null and b/images/M1-mobile/07-keys.png differ diff --git a/images/M1-mobile/08-key-generate.png b/images/M1-mobile/08-key-generate.png new file mode 100644 index 0000000..42a461d Binary files /dev/null and b/images/M1-mobile/08-key-generate.png differ diff --git a/images/M1-mobile/09-settings.png b/images/M1-mobile/09-settings.png new file mode 100644 index 0000000..7fa9ae9 Binary files /dev/null and b/images/M1-mobile/09-settings.png differ diff --git a/images/M1-mobile/10-sync.png b/images/M1-mobile/10-sync.png new file mode 100644 index 0000000..fdb1c50 Binary files /dev/null and b/images/M1-mobile/10-sync.png differ diff --git a/images/M1-mobile/12-terminal.png b/images/M1-mobile/12-terminal.png new file mode 100644 index 0000000..ab4adf9 Binary files /dev/null and b/images/M1-mobile/12-terminal.png differ diff --git a/images/M1-mobile/13-terminal-menu.png b/images/M1-mobile/13-terminal-menu.png new file mode 100644 index 0000000..aaf3305 Binary files /dev/null and b/images/M1-mobile/13-terminal-menu.png differ diff --git a/images/M1-mobile/14-sftp.png b/images/M1-mobile/14-sftp.png new file mode 100644 index 0000000..3eac7df Binary files /dev/null and b/images/M1-mobile/14-sftp.png differ diff --git a/images/M1-mobile/16-port-forward-add.png b/images/M1-mobile/16-port-forward-add.png new file mode 100644 index 0000000..88b000d Binary files /dev/null and b/images/M1-mobile/16-port-forward-add.png differ diff --git a/images/checks-passed.png b/images/checks-passed.png deleted file mode 100644 index 3303c77..0000000 Binary files a/images/checks-passed.png and /dev/null differ diff --git a/images/hero-dark.png b/images/hero-dark.png deleted file mode 100644 index a61cbb1..0000000 Binary files a/images/hero-dark.png and /dev/null differ diff --git a/images/hero-light.png b/images/hero-light.png deleted file mode 100644 index 68c712d..0000000 Binary files a/images/hero-light.png and /dev/null differ diff --git a/index.mdx b/index.mdx index 15c23fb..d0116ae 100644 --- a/index.mdx +++ b/index.mdx @@ -1,97 +1,72 @@ --- title: "Introduction" -description: "Welcome to the new home for your documentation" +description: "YourSSH is a fast, open-source SSH, SFTP, RDP and VNC client for macOS, Windows, Linux and Android." +icon: "terminal" --- -## Setting up +YourSSH is an open-source client for people who work on many servers: developers, sysadmins and DevOps engineers. It keeps your hosts, keys, files and remote desktops in one dark-themed app, with the secrets stored in your system credential store. -Get your documentation site up and running in minutes. + - - Follow our three step quickstart guide. - +## Platforms -## Make it yours +| Platform | Builds | +|---|---| +| macOS | Universal build (Apple Silicon and Intel), signed with a Developer ID and notarized | +| Windows | x64 and arm64 installer, plus portable `.zip` | +| Linux | x86_64 and arm64, as `.deb` (Debian, Ubuntu) or `.tar.gz` | +| Android | APK (development preview) | -Design a docs site that looks great and empowers your users. +See [Installation](/installation) for download links and first-launch notes. - - - Edit your docs locally and preview them in real time. +## What you can do + + + + Save SSH, RDP and VNC hosts, group and search them, chain jump hosts. - - Customize the design and colors of your site to match your brand. + + Trust on first use, key-change warnings and the Known hosts screen. - - Organize your docs to help users find what they need and succeed with your product. + + Tabs, split view, search, shell integration and hotkeys. - - Auto-generate API documentation from OpenAPI specifications. + + Connect to, run a command on, or push files to many hosts at once. - - -## Create beautiful pages - -Everything you need to create world-class documentation. - - - - Use MDX to style your docs pages. + + Local, remote and dynamic SOCKS5 tunnels. + + + A dual-panel file manager with uploads and downloads. - - Add sample code to demonstrate how to use your product. + + Remote desktops, direct or through an SSH tunnel. - - Display images and other media. + + Generate, import and deploy SSH keys. + + + Replay sessions and keep a secret-redacted local trail. + + + Move your hosts between devices, encrypted. + +
+ +## Where to start + + + + Download the build for your operating system. - - Write once and reuse across your docs. + + Add a host, connect and open SFTP in a few minutes. - + -## Need inspiration? +## Source and support - - Browse our showcase of exceptional documentation sites. - +YourSSH is developed in the open at [github.com/YoursshLabs/yourssh](https://github.com/YoursshLabs/yourssh). Report bugs and request features in the [issue tracker](https://github.com/YoursshLabs/yourssh/issues). To build from source or write plugins, see the **Developer guide** tab. diff --git a/installation.mdx b/installation.mdx new file mode 100644 index 0000000..0a9a475 --- /dev/null +++ b/installation.mdx @@ -0,0 +1,68 @@ +--- +title: "Installation" +description: "Download and install YourSSH on macOS, Windows, Linux or Android." +icon: "download" +--- + +Download the latest build from the [releases page](https://github.com/YoursshLabs/yourssh/releases/latest). Replace `` below with the version number, for example `0.4.0`. + + + + 1. Download `YourSSH--macOS-universal.dmg`. One build runs on Apple Silicon and Intel Macs. + 2. Open the `.dmg` and drag **YourSSH** to `/Applications`. + 3. Open YourSSH from Launchpad or Spotlight. + + Release builds are signed with a Developer ID and notarized by Apple, so Gatekeeper opens them without extra steps. If macOS still blocks a build (for example one you compiled or downloaded from a fork), right-click the app, choose **Open**, then confirm. + + A `YourSSH--macOS-universal.zip` is also published if you prefer an archive. + + + 1. Download the installer for your CPU: + - `YourSSH.Setup.-Windows-x64.exe` for Intel and AMD PCs. + - `YourSSH.Setup.-Windows-arm64.exe` for Surface and Snapdragon devices. + 2. Run the installer and follow the wizard. YourSSH is added to the Start menu and the desktop. + 3. If Windows SmartScreen warns on first run, click **More info**, then **Run anyway**. + + Prefer no installer? Download `YourSSH--Windows-x64-portable.zip` (or `arm64`), extract it anywhere and run `yourssh.exe`. + + + Debian and Ubuntu (22.04 or later, Debian 12 or later): + + ```bash + # x86_64 + sudo dpkg -i yourssh__amd64.deb + + # arm64 (Raspberry Pi 4/5, ARM servers) + sudo dpkg -i yourssh__arm64.deb + ``` + + Then run `yourssh` or start it from your application menu. YourSSH needs GTK 3, which these distributions include. + + On other distributions, download `YourSSH--Linux-x86_64.tar.gz` or `YourSSH--Linux-arm64.tar.gz`, extract it and run the `yourssh` binary inside. + + + Download `YourSSH--Android.apk` on your phone and open it. Android asks you to allow installs from your browser or file manager the first time. + + The Android app is a development preview. See [Mobile](/user-guide/mobile) for what it supports. + + + +## First launch + +YourSSH opens on the **Hosts** dashboard with a **No hosts yet** message. Continue with the [quickstart](/quickstart) to add your first host. + + +![YourSSH on first launch, showing the empty hosts dashboard with a New host button](/images/01-first-launch/01-empty-dashboard.png) + + +## macOS privacy prompts + +YourSSH is not sandboxed, so macOS asks for access to protected folders the first time the app touches them, for example when you pick a file from **Desktop**, **Documents** or **Downloads** for an upload or an SSH key. Choose **Allow**. If you clicked **Don't Allow**, the app shows a hint instead of failing silently. Open **System Settings**, then **Privacy & Security**, then **Files and Folders**, and switch the folder on for YourSSH. + +## Updates + +YourSSH checks the latest stable release on GitHub at launch, then every six hours while it runs and when you return to the window. Automatic checks are skipped if the last one was less than 24 hours ago. When a newer version exists you see a **New version available** banner with **Details** and **Update** buttons, plus a notification in the bell. To check right away, open **Settings**, go to **Updates** and click **Check for updates**. + +The in-app updater downloads the installer for your platform and opens it. On Windows it prefers the Setup installer over the portable build. On macOS it first verifies that the downloaded `.dmg` carries the YourSSH Developer ID signature. A file that is unsigned or signed by someone else is refused, and you are sent to the release page instead. + +To update manually, install the new build over the old one. Your hosts and settings are kept. diff --git a/logo/dark.svg b/logo/dark.svg index 54a338a..ca607b6 100644 --- a/logo/dark.svg +++ b/logo/dark.svg @@ -1,13 +1,14 @@ - - - - - - - - - - - - + + + + + + + + + + + + + YourSSH diff --git a/logo/light.svg b/logo/light.svg index 75fca1c..5e6050e 100644 --- a/logo/light.svg +++ b/logo/light.svg @@ -1,13 +1,14 @@ - - - - - - - - - - - - + + + + + + + + + + + + + YourSSH diff --git a/quickstart.mdx b/quickstart.mdx index c711458..47b59d7 100644 --- a/quickstart.mdx +++ b/quickstart.mdx @@ -1,80 +1,74 @@ --- title: "Quickstart" -description: "Start building awesome documentation in minutes" +description: "Add your first host, connect, run a command and open SFTP in a few minutes." +icon: "rocket" --- -## Get started in three steps +This walkthrough uses a demo host. Replace `demo`, `127.0.0.1` and port `2222` with your own server. You need [YourSSH installed](/installation) and an SSH server you can sign in to. -Get your documentation site running locally and make your first customization. + + + On the **Hosts** dashboard, click **New host**. The host editor opens on the right. Keep **SSH** selected at the top. -### Step 1: Set up your local environment + + - - - During the onboarding process, you created a GitHub repository with your docs content if you didn't already have one. You can find a link to this repository in your [dashboard](https://dashboard.mintlify.com). - - To clone the repository locally so that you can make and preview changes to your docs, follow the [Cloning a repository](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository) guide in the GitHub docs. - - - 1. Install the Mintlify CLI: `npm i -g mint` - 2. Navigate to your docs directory and run: `mint dev` - 3. Open `http://localhost:3000` to see your docs live! - - Your preview updates automatically as you edit files. - - + + Enter a **Label** (a name you will recognize), the **Hostname or IP**, the port (default `22`), your **Username** and **Password**. To use a key or your SSH agent instead, change **Auth method**. See [Hosts](/user-guide/hosts) for every option. -### Step 2: Deploy your changes + + - - - Install the Mintlify GitHub app from your [dashboard](https://dashboard.mintlify.com/settings/organization/github-app). - - Our GitHub app automatically deploys your changes to your docs site, so you don't need to manage deployments yourself. - - - For a first change, let's update the name and colors of your docs site. + + Click **Test** to check the address and credentials without opening a shell. A result such as **Connected** with a latency appears next to the button. Click **Save**. The host appears on the dashboard. - 1. Open `docs.json` in your editor. - 2. Change the `"name"` field to your project name. - 3. Update the `"colors"` to match your brand. - 4. Save and see your changes instantly at `http://localhost:3000`. + + - Try changing the primary color to see an immediate difference! - - + + Double-click the host card to open a terminal tab (or open its three-dot menu and choose **Connect**). The first time you connect, YourSSH pins the server's host key. See [Host keys](/user-guide/host-keys) for what that means and when you get a warning. -### Step 3: Go live + + - - 1. Commit and push your changes. - 2. Your docs will update and be live in moments! - + + When the shell prompt appears, type a command and press Enter. -## Next steps - -Now that you have your docs running, explore these key features: - - + + - - Learn MDX syntax and start writing your documentation. - + + Click the folder icon on the host card, or open the card's menu and choose **SFTP**. The dual-panel file manager shows your computer on the left and the server on the right. - - Make your docs match your brand perfectly. - + + + - - Include syntax-highlighted code blocks. - - - - Auto-generate API docs from OpenAPI specs. - +## Next steps + + + Groups, tags, keys, jump hosts and per-host options. + + + Tabs, split view, search and hotkeys. + + + Transfer files in both directions. + + + Generate an SSH key and deploy it to a host. + - - - **Need help?** See our [full documentation](https://mintlify.com/docs) or join our [community](https://mintlify.com/community). - diff --git a/snippets/snippet-intro.mdx b/snippets/snippet-intro.mdx deleted file mode 100644 index e20fbb6..0000000 --- a/snippets/snippet-intro.mdx +++ /dev/null @@ -1,4 +0,0 @@ -One of the core principles of software development is DRY (Don't Repeat -Yourself). This is a principle that applies to documentation as -well. If you find yourself repeating the same content in multiple places, you -should consider creating a custom snippet to keep your content in sync. diff --git a/user-guide/ai-chat.mdx b/user-guide/ai-chat.mdx new file mode 100644 index 0000000..f5bf245 --- /dev/null +++ b/user-guide/ai-chat.mdx @@ -0,0 +1,89 @@ +--- +title: "AI assistant" +description: "Ask an AI model about shell commands and errors from a sidebar next to your terminal, using your own API key." +icon: "bot" +--- + +The AI assistant is a chat sidebar that opens beside your terminal. Use it to look up commands, explain error messages and get DevOps help. It talks to the AI provider you configure with your own API key. + +## Set up a provider + +The **AI** button stays hidden in the terminal header until at least one provider has a key. + + + + Go to **Settings** and find the **AI providers** section. + + + Paste the key into the field for **Anthropic**, **OpenAI** or **Google Gemini**. The key is hidden as you type. Click the eye icon to show it. + + + Choose a model from the **Model** list under the key. Each provider has its own list and default. + + + + + +| Provider | Models in the list | +|---|---| +| **Anthropic** | `claude-haiku-4-5-20251001`, `claude-sonnet-4-6`, `claude-opus-4-7` | +| **OpenAI** | `gpt-4o-mini`, `gpt-4o`, `o1-mini` | +| **Google Gemini** | `gemini-2.0-flash`, `gemini-1.5-flash`, `gemini-1.5-pro` | + +To remove a key, click the clear button in its field. + +### Where keys are stored + +API keys are stored in the system credential store (macOS Keychain, Windows Credential Manager), not in a plain settings file. If the store can't be reached, YourSSH shows an error instead of saving the key somewhere less safe. Keys stay on this device. They aren't part of [sync](/user-guide/sync). See [Settings](/user-guide/settings) for other preferences. + +## Chat in a terminal + + + + In a terminal session, click **AI** in the terminal header. The sidebar titled **AI Assistant** opens on the right. + + + If you configured more than one provider, pick one from the list at the top of the sidebar. + + + Type in **Ask a command question…** and press `Enter`. Press `Shift+Enter` for a new line. + + + + + +Answers stream in and are formatted as Markdown, with code blocks for commands. The sidebar header has buttons to clear the chat and to close it. + + + +## What is sent to the provider + +- Your messages and the earlier messages of the current conversation. +- A short fixed instruction that tells the model to act as an SSH command assistant. + +YourSSH does not send your terminal output, files or host details on its own. The assistant can't run commands on your host. If you want it to look at an error, paste the text into the chat. Don't paste secrets. + +Your messages go to the provider you selected, under that provider's terms. Clearing the chat removes the conversation from the sidebar. + +## Tips + +- Paste an error and ask what it means. +- Ask for a command, then review it before you run it. Use [snippets](/user-guide/snippets) to keep the ones you reuse. +- Switch provider from the sidebar to compare answers. + +## Related pages + + + + Credential storage and other preferences. + + + The terminal header and sessions. + + diff --git a/user-guide/audit-log.mdx b/user-guide/audit-log.mdx new file mode 100644 index 0000000..862d4e0 --- /dev/null +++ b/user-guide/audit-log.mdx @@ -0,0 +1,82 @@ +--- +title: "Audit log" +description: "A local, secret-safe record of connections and commands run through YourSSH, with filters, export and retention." +icon: "scroll-text" +--- + +YourSSH keeps a local audit trail of what ran where: every connect and disconnect, and every command sent through an app feature such as a bulk run, DevOps tool, plugin or the input bar. Open it from **Audit Log** in the sidebar. + + + + +The log records commands sent through app features. Keystrokes you type directly into a terminal aren't captured. For a full replay of a terminal, use [session recording](/user-guide/recording). + + +## What gets recorded + +| Type | When | +|---|---| +| `connect` | A session connects, or finally fails (with the error and number of attempts). | +| `disconnect` | You close a live tab, or a session drops, including drops that reconnect automatically. | +| `exec` | A command runs over SSH exec, with its source and exit code. | +| `input` | A command goes in through the terminal input bar, broadcast input or a plugin. | + +Each row shows the time, a colored type chip, `user@host`, the command, its **source** and, for commands, the exit code. The source says which feature produced the event, for example `bulk` for [bulk actions](/user-guide/bulk-actions), `devops` for the [DevOps Hub](/user-guide/devops), `input-bar` for the input bar, `plugin:` for a plugin, `cli` or `url` for connections started from the [command line](/user-guide/cli) or a `yourssh://` link, and `rdp` or `vnc` for remote desktop sessions. + +YourSSH leaves out its own background probes, such as the network stats overlay and OS detection, so the log stays readable. + +## Secret redaction + +YourSSH scrubs commands before it writes them to disk. It masks: + +- `password=`, `token=`, `secret=` and `api_key=` values, including quoted multi-word values and prefixed forms like `PGPASSWORD=` +- `Authorization: Bearer` tokens +- `sshpass -p` +- the attached `-p` form of `mysql` and `mariadb` +- `redis-cli -a` +- passwords inside URLs + +Error messages stored with failed events go through the same redaction. + + +Redaction is best-effort pattern matching. Avoid putting secrets on command lines where you can. + + +## Filter and search + +- Pick an event type from the type menu, which starts at **All types**. +- Pick a time range with the **Today**, **7d**, **30d** and **All** chips. +- Type in **Search command or host…** to match the command or host name. +- Click **Load more** at the bottom to page through a long history. + + + + + +## Export + +Click **CSV** or **JSON** at the top to export what the current filter shows. A save dialog asks where to put the file, and a toast confirms the export. + + + +## Retention and clearing + +Open **Settings → Audit** to choose how long to keep events: `30 days`, `90 days` (the default), `365 days` or **Keep forever**. YourSSH deletes older events at launch. + +Click **Clear** on the Audit log screen, or in **Settings → Audit**, to delete every event. YourSSH asks **Clear audit log?** and says all recorded events will be deleted. + + + +## Where it is stored + +The log is a local SQLite database named `audit.db` in the app's support folder. Only your user can read it, and it never syncs anywhere. diff --git a/user-guide/bulk-actions.mdx b/user-guide/bulk-actions.mdx new file mode 100644 index 0000000..6709e70 --- /dev/null +++ b/user-guide/bulk-actions.mdx @@ -0,0 +1,106 @@ +--- +title: "Bulk actions" +description: "Select several hosts to open tabs, run one command everywhere in parallel, or push files to all of them." +icon: "layers" +--- + +Bulk actions work on many hosts at once from the hosts dashboard. You can open a tab for each host, run one command on all of them, or upload files to the same path on each. + +## Select hosts + + + + On the hosts dashboard, click **Select**. Every host card gets a checkbox, and an action bar replaces the toolbar. + + + + + Tick the hosts you want, or click **Select all**. **Select all** respects the search and filter you have active, so filter first to select only matching hosts. **Clear** empties the selection. + + + + + Click **Connect all**, **Run command** or **Push files**. Click **Done**, or press `Esc`, to leave select mode. + + + + + **Run command** and **Push files** work over SSH. RDP and VNC hosts in the selection are skipped, and YourSSH tells you how many. + + +## Connect all + +**Connect all** opens a tab for every selected host, whatever its protocol. Hosts that already have a connecting or connected session are skipped, and a notice tells you how many. If it would open more than five tabs, YourSSH asks **Open N tabs?** first: click **Open all** to continue. + +## Run command + +**Run command** runs one command on every selected host in parallel. + + + + Type a command in the box, or click the `{}` button to insert a saved [snippet](/user-guide/snippets). Click **Run**. + + + + + The **Results** tab lists each host with its status and duration. Click a row to expand its output and exit code. + + + + + + + +Hosts run in parallel, at most six at a time. Each host has a 30-second timeout, and a failure on one host never stops the others. + +### Exit codes and the footer + +The footer summarizes the run, for example `3 ok · 1 non-zero exit · 0 failed`: + +- **ok**: the command ran and returned exit code 0. +- **non-zero exit**: the command ran but returned a non-zero code, or the server sent no exit status. The row shows the real code, or marks it as unknown. +- **failed**: YourSSH could not run the command, for example the host was unreachable, authentication failed or it timed out. +- **cancelled**: shown only if you cancelled hosts that had not started. + +### Diff + +The **Diff** tab groups hosts that printed identical output. The biggest group is the **BASELINE**. Click the flag on another group to make it the baseline instead. Click **Compare two hosts** to see two hosts' output side by side. This is a quick way to find the one server whose config differs. + + + +## Push files + +**Push files** uploads files or folders to the same path on every selected host. + +1. Click **Add files** or **Add folder**. Each item appears as a chip with its size, and the **x** removes it. +2. Enter an absolute **Destination**, for example `/home/demo/backups`. YourSSH creates the folder if it doesn't exist. +3. Click **Push**. Each host shows its own progress. + + + + + Existing remote files with the same name are overwritten without asking. + + +## Cancel a running job + +If you close a bulk dialog while work is still running, YourSSH asks **Cancel run?** (or **Cancel push?**). Choose **Keep running** (or **Keep pushing**) to carry on. For a run, **Cancel run** stops the queue, and hosts already in flight finish with their real result. For a push, **Cancel push** stops transfers in flight at the next file boundary. + +## Related + +- [Hosts](/user-guide/hosts) covers groups, tags and search, which make selecting easier. +- [Terminal](/user-guide/terminal) covers broadcast, for typing into several open sessions at once. diff --git a/user-guide/cli.mdx b/user-guide/cli.mdx new file mode 100644 index 0000000..922e4a2 --- /dev/null +++ b/user-guide/cli.mdx @@ -0,0 +1,140 @@ +--- +title: "Command line and links" +description: "Open hosts from a terminal, a script or a link with the yourssh command and yourssh:// URLs." +icon: "square-terminal" +--- + +The `yourssh` command asks the running YourSSH app to do something, such as open a host. It is useful from a shell, a script or a launcher. YourSSH can also open saved hosts from `yourssh://` links. + + +The command-line client is in its first phase. Release builds don't include the `yourssh` binary yet, so you run it from the source repository. In a release build, `yourssh` (or `yourssh.exe`, or `/usr/bin/yourssh` from the `.deb`) is the app itself. + + +## Run the client + +You need the Dart SDK and a checkout of the [YourSSH repository](https://github.com/YoursshLabs/yourssh). From the repository root, run: + +```bash +dart run packages/yourssh_cli/bin/yourssh.dart +``` + +Or compile a standalone binary once and put it on your `PATH`: + +```bash +dart compile exe packages/yourssh_cli/bin/yourssh.dart -o yourssh +``` + +The examples below use `yourssh`. The client works on macOS, Linux and Windows. + +## Commands + +| Command | What it does | +|---|---| +| `yourssh connect ` | Opens a host in a new tab and brings the YourSSH window to the front. | +| `yourssh ls [--json] [--tag T] [--filter Q]` | Lists your saved hosts. | +| `yourssh version` | Prints the client and app versions. | +| `yourssh open ` | Opens a `yourssh://connect/` link. | +| `yourssh help` | Shows the usage text. | + +### connect + +```bash +yourssh connect "Demo Server" +``` + +`` is matched against your saved hosts in this order: + +1. The host id. +2. The label, ignoring case. If several hosts have that label, the command lists them and exits with code 2. Use the id instead. +3. A `user@hostname[:port]` that equals a saved host. + +If nothing matches, an address of the form `user@hostname[:port]` opens an unsaved SSH connection. Port 22 is used when you leave the port out. This signs in with the keys from your SSH agent. A server that only accepts a password needs a saved host, because the app has no password prompt for unsaved hosts. + +`connect` returns as soon as the tab opens. It doesn't wait for sign-in. RDP and VNC hosts open the same way. + +### ls + +```bash +yourssh ls +yourssh ls --tag prod --filter db +yourssh ls --json +``` + +The table has the columns `LABEL`, `USER@HOST:PORT`, `PROTOCOL` and `TAGS`. `--tag` limits the list to a tag and `--filter` to hosts matching a search text. `--json` prints a stable JSON list for scripts and launchers. It never contains passwords, keys or passphrases. + +### version + +`yourssh version` prints the client version and the app version. It never starts the app. If the app isn't running, it says **YourSSH app: not running** and exits with code 3. + +### open + +```bash +yourssh open "yourssh://connect/Demo%20Server" +``` + +This is the same as following the link. See [Links](#yourssh-links) below. + +## Exit codes + +| Code | Meaning | +|---|---| +| `0` | Success. | +| `1` | The command failed. | +| `2` | Bad arguments, or an unknown or ambiguous host. | +| `3` | The app isn't reachable, still starting, or speaks a different protocol version. | +| `4` | Access denied. The client refused to talk to the app or the app refused the client. | + +## If the app isn't running + +`connect`, `ls` and `open` start YourSSH for you and wait up to 15 seconds for it. They then wait until your hosts and keys have loaded. `version` never starts the app. + +How the client finds the app depends on the platform: + +- **macOS**: it asks the system to open YourSSH by its bundle identifier. If YourSSH isn't installed, the command fails at once with exit code 3. +- **Linux and Windows**: YourSSH writes its own location to a file in your user's run folder each time it starts, and the client launches that path. If the file isn't there yet, or the path isn't safe to run, start YourSSH once from the launcher or Start menu. + +## Security + +The client and the app talk over a local channel that only your own user account can reach. + +- **A private socket or pipe.** On macOS and Linux it is a Unix socket in a private folder. On Windows it is a named pipe that only your user can open, and remote clients are refused. +- **Same user only.** The app checks which user is on the other end and drops anyone else. +- **A token.** The app writes a new random token to a private file each time it starts. Every request must carry it. +- **No secrets.** Passwords, keys and passphrases never appear in command arguments, output or `--json`. +- **Same safeguards as the app.** A connection opened by the command goes through the usual host key check and is written to the [audit log](/user-guide/audit-log). + +The app only allows one running instance. Starting it a second time brings the existing window forward. + +## YourSSH links + +A `yourssh://connect/` link opens a saved host. Use it from a bookmark, a note or another app. + +```text +yourssh://connect/Demo%20Server +``` + +- Only saved hosts work. A link can't point YourSSH at a new address or run a command, so a web page can't use it to connect you to someone else's server. +- The link has exactly one path segment. Queries, ports and user names in the link are refused. +- Opening the same link again within two seconds is ignored. +- A refused link, for example an unknown or ambiguous host, shows up in the notification bell as **Link refused**. + +### Where links are registered + +| Platform | Registered by | +|---|---| +| macOS | The app. | +| Windows | The installer, for the user who installs it. The portable zip doesn't register the scheme. | +| Linux | The `.deb` package. The tarball doesn't register the scheme. | + +Where the scheme isn't registered, you can still use `yourssh open `. + +## Related pages + + + + Save the hosts the command opens. + + + See connects started by the command or a link. + + diff --git a/user-guide/devops.mdx b/user-guide/devops.mdx new file mode 100644 index 0000000..c45e564 --- /dev/null +++ b/user-guide/devops.mdx @@ -0,0 +1,179 @@ +--- +title: "DevOps Hub" +description: "Manage containers, run network diagnostics, expose ports, catch mail, share files and browse S3 buckets from your SSH sessions." +icon: "rocket" +--- + +DevOps Hub is a built-in plugin with seven tools. Most of them run on the host of an open SSH session, so connect to a host first. + +## Open the hub + +Click **DevOps Hub** in the sidebar under **Tools**. The hub has its own list on the left: **Containers**, **Network Tools**, **Cloudflare**, **LAN Share**, **Mail Catcher**, **MCP Server** and **S3 Browser**. The hub opens on **Network Tools**. + +If **DevOps Hub** is missing, turn it on in **Plugins** under **BUILT-IN PLUGINS**. + + + + +Commands the hub runs on a host are recorded in the [audit log](/user-guide/audit-log) with the source `devops`. + + +## Containers + +**Containers** manages Docker, Docker Compose and Kubernetes on the remote host. + +1. Pick a session from the list at the top. If no SSH session is open, the tool asks you to open one first. +2. Click the refresh button (**Rescan runtimes**), or **Scan**, to detect what is installed. +3. Switch between the **Docker**, **Compose** and **Kubernetes** tabs. + +If a tool isn't installed on the host, the tab says so, for example **docker is not installed on this host**, and offers **Copy command** with the install hint. + + + +### Docker + +The **Docker** tab lists all containers, running and stopped, with image and status. Each container has icon buttons. Hover one to see its name: + +| Button | What it does | +|---|---| +| **Stop**, **Restart**, **Start** | Change the container state. Which one shows depends on the current state. | +| **Exec** | Opens a shell inside the container. | +| **Logs** | Shows the live log below the list. | + +### Compose + +The **Compose** tab lists Compose stacks found on the host. Use **Add path manually** to add a stack that isn't found. For each stack you can bring it **Up** or **Down** and select it to see its services. **Down** asks you to confirm first. For each service you can start, stop and open **Logs**. Docker Compose v2 is required. + +### Kubernetes + +The **Kubernetes** tab lists pods. Filter by **Namespace** or turn on **All namespaces**. For a pod you can **Exec** into a container, open **Logs** or use **Forward port** to forward a pod port to a local port. `kubectl` must be installed on the host. + +## Network tools + +**Network Tools** runs diagnostics on the host of the active session. Pick a tool from the list. Most tools ask for a target such as a host, URL or path. **Netstat**, **Top Processes** and **Memory Info** don't. Click the run button, which carries the tool's name. Without an open SSH session the tool shows **No active session — connect to a host first**. + +| Group | Tools | +|---|---| +| **NETWORK** | **Ping**, **cURL**, **DNS Lookup**, **Traceroute**, **Port Scan**, **Whois**, **Netstat** | +| **SYSTEM** | **Disk Usage**, **Top Processes**, **Memory Info** | +| **HTTP** | **HTTP Headers**, **SSL Certificate** | + +The commands run on the remote host, not on your computer. Each run opens a result tab. Use the copy button to copy the output and **Clear all tabs** to close them. + + + + + +## Cloudflare tunnels + +**Cloudflare** starts a quick tunnel with `cloudflared` on the remote host and gives you a public HTTPS URL for a port on that host. Use it to share a dev server without changing firewall rules. + + + + The tool needs an active SSH session. `cloudflared` must be installed on that host. + + + Click **New Tunnel**. Enter a **Label** and the **Local Port** (1–65535), then click **Add Tunnel**. Empty or invalid fields show **Required** or **Invalid (1–65535)**. + + + Click the start button on the tunnel. When it is running, use **Copy URL** to copy the public address. The stop button ends it. **Remove** deletes the entry after you confirm **Remove tunnel**. + + + + + +If `cloudflared` isn't installed on the host, starting a tunnel shows an error with the install command. + + +Anyone with the tunnel URL can reach that port while the tunnel runs. Stop the tunnel when you are done. + + +## LAN Share + +**LAN Share** shares one file over HTTP on your local network. + +1. Click **Pick File to Share** and choose a file on your computer. +2. YourSSH generates a local URL on port `8765` that contains a random token. Use **Copy URL** to copy it. The URL uses your Wi-Fi address, so the computer needs to be on Wi-Fi. +3. Anyone on the same network who has the URL can download the file with a browser. The link is plain HTTP. + +Click **Stop Sharing** when you are done. Sharing also stops when you switch to another tool in the hub, and the link only works while YourSSH is running. + +## Mail Catcher + +**Mail Catcher** starts a small SMTP server on the remote host so you can test the mail your app sends, without delivering it. It needs `python3` on the host. + + + + Click the start button (its tooltip reads **Start on port 1025**). The header then shows **Listening on :1025**. + + + Configure the app on that host to send mail to SMTP port `1025`. + + + Captured messages appear in the list with the sender and time. Select one to see **Subject**, **From**, **To**, **Received** and the body. + + + + + +Click **Clear all** (the clear button in the header) to remove every captured message. YourSSH asks **Clear captured mail?** first, because the messages are also removed from the catcher log on the host. Click **Stop** to shut the server down. + + + +## MCP Server + +**MCP Server** runs a Model Context Protocol server on the remote host and makes it available on a local port, so an AI client on your computer can use it. + +1. Enter the **MCP Server Command** that starts the server on the host. The default is `npx @anthropic-ai/mcp-server`. +2. Set the **Local Port** (default `9090`). +3. Click **Start MCP Server**. + +YourSSH forwards the port over SSH and shows the endpoint, with a button to copy it. Point your AI tool at that endpoint. Click **Stop MCP Server** to end it. The page explains the flow under **How it works**. + + + +## S3 Browser + +**S3 Browser** browses S3-compatible storage such as AWS S3, MinIO and Cloudflare R2. It talks to the bucket directly from your computer, so it doesn't need an SSH session. + + + + Click **Add Bucket** and fill in **Display Name**, **Endpoint**, **Bucket**, **Region**, **Access Key** and **Secret Key**. Click **Save**. + + + Open the bucket to see its folders and objects. You can upload, create a folder with **New Folder**, rename or move an object, copy a download URL, download an object to your `Downloads` folder and delete objects. + + + +Bucket settings, including the keys, are stored in the system credential store. Use **Edit Bucket** and **Remove Bucket** to change or delete a saved bucket. + + + +## Related pages + + + + HTTP client, utilities and an embedded browser. + + + Tunnels behind the MCP server and browser. + + diff --git a/user-guide/host-keys.mdx b/user-guide/host-keys.mdx new file mode 100644 index 0000000..9085800 --- /dev/null +++ b/user-guide/host-keys.mdx @@ -0,0 +1,60 @@ +--- +title: "Host keys" +description: "How YourSSH pins server host keys, warns when they change, and lets you manage them." +icon: "shield-check" +--- + +Every SSH server has a **host key**. YourSSH remembers it the first time you connect and checks it on every later connection. If the key is different, someone may be impersonating the server, so YourSSH stops and asks you. + +## Trust on first use + +When you connect to a host or port that YourSSH has never seen, it saves the server's host key without asking, then continues. This is trust on first use. The first connection is the only moment an attacker could slip in unnoticed, so connect to new servers from a network you trust. + +The pin is stored per host, port and key type. The same check applies to every hop of a [connection chain](/user-guide/hosts#connection-chain), to **Test**, to [SFTP](/user-guide/sftp) and to [port forwarding](/user-guide/port-forwarding). + +## When a key changes + +If a pinned server presents a different key, the connection is blocked until you decide. + + + A changed host key can mean a man-in-the-middle attack. Only choose **Trust new key** if you know why the key changed, for example after you reinstalled the server. + + +### Host key type changed + +A server can offer several key types, such as `ssh-ed25519` and `ssh-rsa`. If you pinned one type and the server now presents another, YourSSH shows **Host key type changed** with the old and new SHA-256 fingerprints. A server or attacker that only changes the algorithm cannot get past the pin. + + + +### Host key changed + +If the key type is the same but the key itself is different, YourSSH shows **Host key changed** with the old and new fingerprints. + +In both cases: + +- **Cancel** aborts the connection and keeps the old pin. It has the default focus. +- **Trust new key** replaces the pin and continues. + +## Known hosts + +Open **Known Hosts** in the sidebar to see every pinned key. Each row shows the host and port, the key type and the fingerprint. + + + +- **Copy fingerprint**: copies the fingerprint of the row (the copy icon). +- **Remove**: deletes the pin (the trash icon). YourSSH asks **Remove host key?** first, because it will then trust whatever key that host presents on the next connection. Cancel is selected by default. +- **Import**: reads `~/.ssh/known_hosts` and adds entries you don't have yet. YourSSH reports **Imported N entries**, or **No new entries found**. If the file doesn't exist, it says so. + + + +Use remove after you legitimately rebuild a server, then connect again to pin the new key. + +## RDP certificates + +Remote desktop hosts use a certificate instead of an SSH host key. The pin works similarly, is stored in the same Known Hosts list and is covered on the [RDP page](/user-guide/rdp). diff --git a/user-guide/hosts.mdx b/user-guide/hosts.mdx new file mode 100644 index 0000000..f4ff369 --- /dev/null +++ b/user-guide/hosts.mdx @@ -0,0 +1,227 @@ +--- +title: "Hosts" +description: "Organize saved SSH, RDP and VNC hosts on the dashboard and configure each one in the host editor." +icon: "server" +--- + +A **host** is a saved connection profile. You manage hosts on the **Hosts** dashboard (sidebar, **Hosts**) and edit them in the host editor. + +## The hosts dashboard + + + +The toolbar has, from left to right: + +| Control | What it does | +|---|---| +| Search box | Filters hosts as you type. See [Search and filter](#search-and-filter). | +| Sort | Orders hosts. | +| Grid and list buttons | Switch the layout. | +| **Discover** | Scans your network for devices. See [Discover devices](#discover-devices). | +| **Select** | Turns on select mode for [bulk actions](/user-guide/bulk-actions). | +| **Local terminal** | Opens a shell on your own computer. | +| **New host** | Opens the host editor. The arrow next to it adds **New group** and **Import**. | + +When the window is narrower than 900 px, lower-priority controls collapse into icons or a menu. + +### Grid and list + +Grid view shows cards. List view shows one compact row per host. Your choice, and your sort order, are remembered between launches. + + + +### Sort + +Open the sort menu and pick **Name A→Z**, **Name Z→A**, **Host A→Z**, **Host Z→A**, **Newest first** or **Oldest first**. The default is **Name A→Z**. + + + +### Search and filter + +Type in the search box to match labels, hostnames, IPs, usernames and tags. Tokens written as `key:value` match tags of the same form. Tag a host `env:prod` and search `env:prod` to find it. Values for the same key are ORed (`env:prod env:staging`), different keys are ANDed (`env:prod role:db`). + + + +When any host has a `key:value` tag, a row of filter chips appears on the left of the **N of M hosts** counter, one chip per distinct tag. Click a chip to add or remove that tag from the search. + +### Groups + +Click **New host**'s arrow, then **New group**, to create a group. Set a host's **Group** in the editor, or choose **Move to group** from its card menu. Click a group card to see only its hosts. Use the group card's options menu to delete a group. + +### Host card menu + +Double-click a card to connect. Hover it to see quick actions: **Test connection** (the pulse icon), **SFTP** (the folder icon) and the three-dot **More** menu. + + + +| Item | What it does | +|---|---| +| **Connect** | Opens a session. | +| **SFTP** | Opens the file manager on this host. SSH hosts only. | +| **Monitor** | Shows live server stats. SSH hosts only. | +| **Edit** | Opens the host editor. | +| **Duplicate** | Makes a copy of the host. | +| **Copy SSH URL** | Copies a connection URL such as `ssh://user@host:port`. The scheme follows the host's protocol, and the item reads **Copy RDP URL** or **Copy VNC URL** for those hosts. | +| **Move to group** | Changes the host's group. | +| **Export** | Shows the host as `.ssh/config` text or JSON, ready to copy. | +| **Delete** | Deletes the host after a confirmation. | + + + +### Discover devices + +**Discover** scans a local subnet for devices with SSH open. Pick a subnet (the app fills in your network's), click **Scan**, then click **Add** to save a result as a host or **Connect** to open a session. When you create a new host, the **Scan network to pick a device** link in the editor opens the same scan and fills the hostname with the device you pick. + +### Import hosts + +Open the arrow next to **New host** and choose **Import**. Pick a source tab, then choose a file or paste text, click **Parse** and review the hosts before importing. The sources are: + +- **~/.ssh**: OpenSSH config text. JSON host lists, such as the YourSSH export, are also recognized here. +- **CSV** with columns `host, label, port, username, auth_type, group, tags` +- **PuTTY**, **MobaXterm**, **SecureCRT**, **WinSCP**, **Termius** exports and **Ansible** INI inventories +- **SSH URI**: one `ssh://user@host:port` per line + +CSV rows that can't be parsed are listed as warnings, not silently dropped. + +## The host editor + +Click **New host**, or **Edit** on a card. The editor opens as a side panel. Press `Enter` in any single-line field to save. + + + +### Protocol + +The switch at the top selects **SSH**, **RDP** or **VNC**. Changing it swaps the sections below. The port changes to the protocol's default (22, 3389, 5900) unless you already typed a custom port. RDP and VNC hosts hide the SSH-only sections. See [RDP](/user-guide/rdp) and [VNC](/user-guide/vnc). + +### General + +**Label** is the display name. **Hostname or IP** and the port sit side by side. Tab moves through label, hostname, port and username. + +### Credentials and auth method + +Set **Username** and **Password**, then choose an **Auth method**: + +| Method | Use it when | +|---|---| +| **Password** | You sign in with a password. It is stored in the system credential store. | +| **Private Key** | You sign in with a key. Pick one under **Select key** from your [Keychain](/user-guide/keychain). A key can carry a passphrase and an SSH certificate there. | +| **SSH Agent** | Your local agent holds the key (`SSH_AUTH_SOCK` on macOS and Linux, the OpenSSH agent pipe on Windows). | + + + + + +### Group and tags + +Choose a **Group** and add **Tags**, comma separated. Use `key:value` tags such as `env:prod, role:db` to get the search facets above. + + + +### Connection chain + +The **CONNECTION CHAIN** section routes the connection through one or more jump hosts (bastions). Click **Add a Host** and pick a saved host. Repeat to add more hops. Each hop has a remove button, and **Clear** returns to a direct connection. Hosts already in the chain are not offered again, so you can't create a loop. + + + + + +The terminal, SFTP, bulk actions and port forwarding all use the full chain. YourSSH verifies the [host key](/user-guide/host-keys) of every hop. The status bar shows `via` and the first hop. + + + +### Proxy + +The **PROXY** section sends the connection through an **HTTP CONNECT** or **SOCKS5** proxy. Enter the proxy host, port and optional username and password. Leave it on **None** for a direct connection. The proxy password is stored in the system credential store. + +### SFTP mode + +**SFTP MODE** chooses how the file manager starts the SFTP server on the host: + +- **Default**: the normal SFTP subsystem. +- **Sudo (root)**: runs the SFTP server with `sudo`, so you can browse files owned by root. +- **Custom command**: runs the command you enter, for example `sudo /usr/lib/openssh/sftp-server`. + +### Options + + + +| Option | Effect | +|---|---| +| **Auto-record sessions** | Starts a [recording](/user-guide/recording) on every connect. | +| **Redact secrets in recordings** | Masks passwords and tokens in the recording. Needs the global setting too. | +| **Shell integration** | Reports the working directory and command status on bash and zsh. | +| **Agent forwarding** | Lets this host use your local SSH keys for onward hops, like `ssh -A`. Off by default. Only your agent signs. Private keys never leave your computer. | +| **OSC 52 clipboard** | Lets remote programs such as tmux and vim set your local clipboard. Write-only, off by default. | + + + Turn on **Agent forwarding** only for hosts you trust. Anyone with root on that host can use your keys while the session is open, though they can't read them. + + +When agent forwarding is on, a status line tells you whether YourSSH will use your system agent or fall back to Keychain keys. During a session, a key icon on the tab shows whether the host has asked for a key. + +### Session template + +The **SESSION TEMPLATE** section sets up each new session on this host. All fields are optional, and an empty field follows your global [settings](/user-guide/settings). + + + +- **Working directory**: `cd` into this folder on connect, without echo. bash and zsh only. +- **Environment variables**: `NAME=value` pairs, exported invisibly. Names use `A–Z`, `0–9` and `_` only, and must be unique. bash and zsh only. +- **Startup snippet**: text typed visibly into the shell after setup, as if you typed it. It shows in recordings and the [audit log](/user-guide/audit-log). +- **Theme**, **font**, **size**, **TERM** and **tmux**: per-host overrides. A distinct theme is handy for marking production hosts. + +If you start typing before setup finishes, YourSSH skips the template so you keep control of the session. + +### Validate, test, save, delete + +The footer is always visible. Required fields show **Required**, and an out-of-range port shows **Invalid (1–65535)**. The message disappears as soon as you fix the value. + + + +- **Test** (SSH only) connects and signs in without opening a shell. It shows **Connected** with the latency, or the error message. +- **Save** stores the host. For an existing host the button reads **Save changes**. +- **Delete** (existing hosts only) removes the host after a confirmation. Its stored password and proxy password are removed too. + + + +## Small windows + +The editor, dashboard and terminal work down to the 800 by 600 minimum window size. + + diff --git a/user-guide/keychain.mdx b/user-guide/keychain.mdx new file mode 100644 index 0000000..e8267d8 --- /dev/null +++ b/user-guide/keychain.mdx @@ -0,0 +1,118 @@ +--- +title: "Keychain and credentials" +description: "Generate, import and deploy SSH keys, and learn how YourSSH stores passwords and passphrases." +icon: "key" +--- + +The **Keychain** screen is YourSSH's SSH key manager. Open it from **Keychain** in the sidebar, under **Security**. It lists every private key YourSSH knows about and lets you generate, import, link certificates to, deploy and remove keys. + + + +YourSSH keeps a reference to each private key file. It does not copy the file into the app or upload it anywhere. + +## Keys found automatically + +On startup YourSSH looks in `~/.ssh` for the default key names `id_ed25519`, `id_rsa`, `id_ecdsa` and `id_dsa` and lists any it finds, except keys you removed from the Keychain. If a matching `.pub` file or `-cert.pub` certificate sits next to the key, YourSSH reads it too. + +When no keys are listed, the screen says **No keys added** and offers **Import Key** and **+ Generate Key**. + +## Generate a key + + + + In **Keychain**, click **+ Generate**. The **Generate SSH Key** panel opens on the right. + + + Enter a **Key name**. The default is `id_ed25519`. YourSSH replaces any character other than letters, digits, `_` and `-` with `_` in the file name. + + + Choose an **Algorithm**: + + | Option | Needs | + |---|---| + | **Ed25519 (recommended)** | Nothing. YourSSH generates it itself. | + | **RSA 4096** | The OpenSSH client (`ssh-keygen`) on your computer. | + | **ECDSA P-256** | The OpenSSH client (`ssh-keygen`) on your computer. | + + If `ssh-keygen` isn't installed, the RSA and ECDSA options are unavailable and the panel says **RSA/ECDSA require OpenSSH client (ssh-keygen)**. + + + Enter a **Passphrase (optional)**, or leave it empty for a key without one. When you set one, YourSSH saves it in your [system credential store](#how-credentials-are-stored) so the key works without prompting you each time. + + + Click **Generate Key**. The panel shows the new public key with **Copy public key** and **Done** buttons. + + + + + + + +YourSSH writes the key pair to a `YourSSH/keys` folder inside your Documents folder, as `` (the private key) and `.pub`. On macOS and Linux the private key file is created with mode `600` (readable only by you) before any key material is written. YourSSH refuses to overwrite an existing key with the same name and asks you to choose another. + +## Import a key + +Click **Import** (or **Import Key** on an empty screen), then pick your private key file in the **Select SSH Private Key** dialog. YourSSH adds it to the list, reads the matching `.pub` file if there is one, and links a `-cert.pub` certificate if it finds one next to the key. + +## Link a certificate + +If your hosts use SSH certificates, click **Link certificate…** on a key and choose the certificate file (`*-cert.pub`). A **CERT** badge appears on the key. Click the unlink button on that row to remove the link. + +## Copy, deploy and remove + +Hover a key row to show three actions on the right. + + + +- **Copy public key** puts the public key on your clipboard. +- **Deploy to host…** opens a dialog that lists your saved hosts, with a search box. Pick a host and YourSSH connects to it and appends the public key to `~/.ssh/authorized_keys`, creating `~/.ssh` with mode `700` if needed. Deploying is idempotent: if the key is already there, YourSSH says **Key already deployed** and changes nothing. Otherwise it confirms **Public key added**. +- **Remove key** asks you to confirm with **Remove "name" from keychain?**. Removing takes the key out of YourSSH and deletes the passphrase YourSSH saved for it in the system credential store. The key file on disk is not deleted. A removed key from `~/.ssh` stays removed: the startup scan skips it. Import the same file again with **Import key** to bring it back. + + + + + +To use a key for a host, pick it in the host editor. See [Hosts](/user-guide/hosts). + +## How credentials are stored + +YourSSH stores the secrets that unlock your hosts in your operating system's **system credential store**, not in its own files: + +| Platform | Store | +|---|---| +| macOS | macOS Keychain | +| Windows | Windows Credential Manager | +| Linux | The system keyring (the secret service) | + +This covers host passwords, sudo passwords and key passphrases. Everything else, such as the host list, settings and known hosts, is ordinary configuration. + +YourSSH always tries the system credential store first. When a write succeeds, it also deletes any older plain-text copy of that secret. On every launch it moves any secret still sitting in plain-text preferences into the store: it writes the secret, reads it back to confirm, and only then removes the old copy, so a failed write never destroys your only copy. + +On macOS, YourSSH uses the file-based login keychain. If you update to a build with a different signature, macOS may ask you again to allow access. + +### When the store refuses a write + +If the system credential store rejects a secret, YourSSH falls back to saving it as readable text in its preferences file, so you don't lose it. The fallback is never silent: + +- A notification appears in the bell at the top of the window. +- **Settings → Security** shows **Plain text** instead of **Encrypted**, with the number of affected credentials. + +Click **Retry** to move them into the store again. A credential that can't be moved stays where it is rather than being deleted, and YourSSH retries on the next launch. See [Settings](/user-guide/settings#security). + +### What stays on your device + +- Private key files stay where they are on disk. Only their paths are stored. +- Passwords and passphrases stay in the system credential store. +- Passwords of hosts you sync are the one exception. They travel with your host list, encrypted on your device first. See [Sync](/user-guide/sync). diff --git a/user-guide/mobile.mdx b/user-guide/mobile.mdx new file mode 100644 index 0000000..9b41cd2 --- /dev/null +++ b/user-guide/mobile.mdx @@ -0,0 +1,186 @@ +--- +title: "YourSSH for Android" +description: "Use YourSSH on an Android phone: lock the app, manage hosts and keys, connect over SSH, browse files and forward ports." +icon: "smartphone" +--- + +YourSSH has an Android app: a focused mobile SSH client that shares its core with the desktop app. It is available as a development preview from the [releases page](https://github.com/YoursshLabs/yourssh/releases) as `YourSSH-x.x.x-Android.apk`. There is no iOS version yet. + +The Android app covers hosts, keys, snippets, an SSH terminal, file browsing and port forwarding. SSH only: RDP, VNC, plugins, session recording and the audit log are desktop features. + + +The preview APK is signed with a debug key. It installs and runs, but it can't be upgraded in place from a differently signed build. + + +The app has four tabs along the bottom: **Hosts**, **Snippets**, **Keys** and **Settings**. + +## Lock the app + +**Settings → Security → Biometric unlock** locks YourSSH behind your fingerprint, face or device credential. It is on by default. When it's on, the app locks when you open it and whenever it comes back from the background. It also locks before the app switcher takes a snapshot, so nothing shows there. A locked app shows **YourSSH is locked** and an **Unlock** button. + + + The YourSSH is locked screen with an Unlock button + + + The Settings tab with Terminal, Security and Keyboard and Sync groups + + + +If your phone has no biometrics or screen lock enrolled, the app doesn't lock, so you can't be locked out of a screen you can't unlock. The **Auto-lock** row reads **Immediately when you leave the app**: the app locks as soon as it goes to the background. + +## Hosts + +The **Hosts** tab lists your saved hosts in sections named after each host's first tag (hosts without tags go under **Other**), with their tags, a status dot and a reachability badge such as **offline**. Use the search box (**Search hosts, tags, IPs…**) or the tag chips under it to filter. Tap a host to connect. + +Long-press a host to open its action sheet, where you can **Edit** or **Delete** it. Deleting asks for confirmation and removes the saved host and its credentials. + + + + The Hosts tab with two hosts grouped under Docs and Jump + + + The host action sheet with Edit and Delete + + + +### Add a host + +Tap the **+** button on the **Hosts** tab to open **New host**. + +1. Fill in **Nickname**, **Hostname** and **Port** (22 by default). +2. Enter the **Username**. +3. Choose a **Method**: **Password**, or **SSH key** and then pick one from your keys in **Key**. +4. Optional, under **Advanced**: set a **Group** (for example `Production`; it is stored as the host's first tag) and a **Run on connect** command (for example `tmux attach`). +5. Tap **Save**, or **Save & connect** to connect right away. + + + + The New host form scrolled to authentication and advanced options + + + +Settings that you configured on desktop but that the mobile form doesn't edit, such as a connection chain, are kept unchanged when you edit a host here. + +The first time you connect to a host, the app shows its host key and asks you to trust it, the same way the desktop app does. See [Host keys](/user-guide/host-keys). + +## Snippets + +The **Snippets** tab lists your command snippets, filtered by tag. When a session is open, tap a snippet to run it in that session. With no session, the tab shows **No active session**. See [Snippets](/user-guide/snippets) for what snippets are. + + + + The Snippets tab listing Disk usage, Top memory and Tail logs + + + +## Keys + +The **Keys** tab lists your SSH keys with their algorithm, whether a host uses them, and a short SHA-256 fingerprint. Use the **+** button to generate a key and the import button to bring one in. + +- **Generate**: choose **Ed25519** (fast, modern, recommended), **RSA 4096** or **ECDSA P-256**, enter a **Key name** and an optional **Passphrase (optional)**, then tap **Generate**. +- **Import**: pick a private key file, enter its passphrase if it has one, and tap **Import**. +- **Remove**: tap or long-press a key and choose **Remove key**. This takes the key out of the app's key list. The key file on disk is kept, and YourSSH doesn't delete a passphrase saved for it. + + + + The Keys tab with one Ed25519 key + + + The Generate Key sheet with algorithm choices, key name and passphrase + + + +Passphrases are kept in the Android system credential store. See [Keychain and credentials](/user-guide/keychain#how-credentials-are-stored). + +## Settings + +The **Settings** tab has these groups: + +| Group | Options | +|---|---| +| **Terminal** | **Color theme**, **Font size** and **Terminal font**. | +| **Security** | **Biometric unlock** and **Auto-lock**. | +| **Keyboard & Sync** | **Shortcut key bar** (show or hide the extra key row), **Supabase sync** and **Pair new device**. | + +The row at the top shows **Sync active** or **Sync off**, with `Supabase · end-to-end encrypted` under it. + +## Sync and pair a device + +**Supabase sync** and **Pair new device** both open the **Pair device** screen. There you can: + +- Show a QR code for another device to scan. It's valid for 2 minutes, and **Refresh** restarts it. +- Tap **Scan QR code** to import hosts from a desktop that is showing **Export via QR**. +- Under **Cloud sync**, enter your Supabase project URL, anon key and 12-character sync code (**Edit credentials** reopens the form), tap **Save**, and then **Pull from cloud** to download your hosts. + + + + The Pair device screen with a QR code, a countdown and the Cloud sync section + + + +Cloud sync uses the same Supabase project and sync code as the desktop app, and the same end-to-end encryption. Setup, the sync code and the QR transfer are covered in [Sync](/user-guide/sync). + + +Pulling from the cloud and scanning a QR code both **replace** the host list on this phone with the one you receive. Hosts that exist only on the phone are removed. + + + +Only your hosts and their saved passwords are synced or transferred, as the screen says. SSH keys, snippets, settings and AI keys stay on the device where you created them. Import the keys you need on the phone from the **Keys** tab. + + +## Connect and use the terminal + +Tap a host to connect. A connecting screen shows progress, then the terminal opens. Each session is a tab at the top of the terminal, with **+** to open another session and **x** to close one. + +The terminal supports pinch-to-zoom, and a long-press lets you drag the cursor. + +### Shortcut key bar + +A row of keys above the on-screen keyboard gives you keys a phone keyboard lacks: + +- **Esc**, **Tab**, **Ctrl** and **Alt**. Ctrl and Alt are sticky: tap once, then press a letter. +- **^C** and **^D** send those control characters directly. +- Arrow keys. +- `/`, `-`, `|`, `~`, `:` and `$`. + +The keyboard icon at the left shows or hides the on-screen keyboard. Turn the bar off in **Settings → Keyboard & Sync → Shortcut key bar**. + + + + A terminal session on Android with the shortcut key bar at the bottom + + + The terminal overflow menu with Files and Port forwarding + + + +### Terminal menu + +Tap the three-dot button at the top right of the terminal for **Files** and **Port forwarding**. + +## Files (SFTP) + +**Files** opens a single-panel file browser for the connected host. Tap a folder to open it and the breadcrumb at the top to go back up. Tap the download icon beside a file to download it. Use the upload button at the top to send a file from your phone, and the three-dot menu for more actions such as **Refresh**. See [SFTP](/user-guide/sftp) for the desktop file manager. + + + + The Files screen listing folders and files on Demo Server + + + +## Port forwarding + +**Port forwarding** lists the rules for the host you're connected to. Tap **Add forwarding rule** at the bottom of the list to open the **Add forwarding rule** sheet. Each rule in the list can then be started and stopped. In the sheet, choose a type: + +- **Local** forwards a port on your phone to a host and port reachable from the server. Enter a **Local port**, a **Remote host** and a **Remote port**. +- **Remote** exposes a port on the server that points back to your device. +- **Dynamic** opens a SOCKS proxy on your phone. + +Add an optional **Label**, then tap **Add rule**. Ports must be between 1 and 65535. See [Port forwarding](/user-guide/port-forwarding) for what each type does. + + + + The Add forwarding rule sheet with Local, Remote and Dynamic types + + diff --git a/user-guide/port-forwarding.mdx b/user-guide/port-forwarding.mdx new file mode 100644 index 0000000..e8d3b5d --- /dev/null +++ b/user-guide/port-forwarding.mdx @@ -0,0 +1,122 @@ +--- +title: "Port forwarding" +description: "Create local, remote and dynamic SOCKS5 SSH tunnels, start them on launch and keep them alive." +icon: "arrow-left-right" +--- + +Port forwarding sends network traffic through an SSH connection. Open **Port Forwarding** in the sidebar to create saved rules, start and stop them, and see how many connections each one is carrying. + + +![Port Forwarding list with a running local rule and an idle dynamic SOCKS5 rule](/images/08-port-forwarding/09-running-connections.png) + + +## Rule types + +| Type | What it does | Example | +|---|---|---| +| **Local** | Listens on your machine and forwards to a destination reached from the SSH host | `127.0.0.1:2200` → `127.0.0.1:22` | +| **Remote** | Listens on the SSH host and forwards to a destination on your machine | Expose a local dev server on the remote host | +| **Dynamic SOCKS5** | Runs a SOCKS5 proxy on your machine and routes any TCP connection through the SSH host | `127.0.0.1:1080` | + +A rule always goes through a saved host (the **SSH Host**), using that host's stored credentials. You don't need an open terminal tab: YourSSH connects to the host on its own, and through its [connection chain](/user-guide/hosts) if it has one. + +## Create a rule + + + + Go to **Port Forwarding** and click **New rule**. The **New Port Forward Rule** panel opens on the right. + + + Enter a **Label**, then choose the **Type**: **Local**, **Remote** or **Dynamic SOCKS5**. + + + ![Type dropdown with Local, Remote and Dynamic SOCKS5](/images/08-port-forwarding/06-type-menu.png) + + + + Fill in **Local Host** and **Port** (the address that listens on your machine). For **Local** and **Remote** rules, also fill in **Remote Host** and **Port** for the destination. A **Dynamic SOCKS5** rule needs only the local address, so the remote fields disappear. + + + Pick the **SSH Host** the tunnel runs through. The field is marked optional so you can save a draft, but a rule without a host can't start. It reports **Select an SSH host first**. + + + Tick **Auto-start on launch** to bring the tunnel up each time YourSSH starts. + + + Click **Add Rule**. + + + + +![New Port Forward Rule panel with a local rule filled in](/images/08-port-forwarding/04-local-rule-filled.png) + + + +![New Port Forward Rule panel with Dynamic SOCKS5 selected](/images/08-port-forwarding/07-dynamic-rule-filled.png) + + +### Validation + +The editor checks the form when you save: + +- **Label**, **Local Host** and, for local and remote rules, **Remote Host** can't be empty. A missing value shows **Required**. +- Each **Port** must be a number from 1 to 65535. Anything else shows `1–65535` under the field. + + +![Port field highlighted in red with the message 1–65535](/images/08-port-forwarding/03-validation-port.png) + + +## Start and stop + +Each rule has a button on the right: the play button starts it and the stop button stops it. Several tunnels can run at once, and each one is independent. + +The status dot on the left shows the state: + +| Dot | State | +|---|---| +| Grey | Idle | +| Amber | Connecting, or reconnecting (the rule also shows **reconnecting…**) | +| Green | Active | +| Red | Error. The message appears under the rule, for example that a port is already in use | + +An active rule shows a live connection count such as **1 conn**. + +If a rule fails to start, check the message under it. Common causes are a local port already in use, no SSH host selected, or the host no longer existing. + +## Auto-reconnect + +If the SSH connection drops while a tunnel is running, the rule switches to **reconnecting…** and YourSSH reconnects with exponential backoff, starting at 2 seconds and doubling up to 30 seconds. Local listeners stay bound while it retries, so clients keep the same local port. Stopping the rule cancels the retry. + +## Edit, duplicate and delete + +- Click a rule, or right-click and choose **Edit**, to change it. The panel title is **Edit Port Forward Rule** and the button is **Save**. If the rule is running, stop and start it again to apply the change. +- Right-click and choose **Duplicate** to copy a rule. The copy is named `… (copy)` and never auto-starts. +- Hover a rule and click the trash icon, or right-click and choose **Delete**. YourSSH asks **Delete rule?** first, naming the label and endpoints, with **Cancel** selected by default. After you confirm, a running rule is stopped and removed. Deleting a host also stops the tunnels that use it. + + +![Edit Port Forward Rule panel next to the rule list](/images/08-port-forwarding/10-rule-editor.png) + + +## Example: reach a database on the SSH host + +To connect a SQL client to a PostgreSQL server that only listens on the SSH host: + +| Field | Value | +|---|---| +| Label | `Postgres` | +| Type | **Local** | +| Local Host / Port | `127.0.0.1` / `5432` | +| Remote Host / Port | `127.0.0.1` / `5432` | +| SSH Host | your database host | + +Start the rule, then point your client at `127.0.0.1:5432`. + +## Use tunnels in Web Tools + +The **Web Tools** plugin has a **Port Tunnels** tool that works with these forwarded ports, so you can open a tunnelled web service in the in-app browser. See [Web Tools](/user-guide/web-tools). + +## Related pages + +- [Hosts](/user-guide/hosts) for saved hosts and connection chains. +- [SFTP](/user-guide/sftp) and [Terminal](/user-guide/terminal) use the same SSH connection settings. +- [DevOps Hub](/user-guide/devops) for Cloudflare tunnels and other tunnel tools. diff --git a/user-guide/rdp.mdx b/user-guide/rdp.mdx new file mode 100644 index 0000000..0b48084 --- /dev/null +++ b/user-guide/rdp.mdx @@ -0,0 +1,132 @@ +--- +title: "RDP remote desktop" +description: "Connect to Windows, xrdp and other RDP servers from a YourSSH tab, with certificate pinning, an optional SSH tunnel and a fullscreen mode." +icon: "monitor" +--- + +YourSSH has a built-in RDP client. An RDP session opens as a tab next to your SSH sessions, so you don't need a separate remote desktop app. + +## Add an RDP host + + + + On the hosts dashboard, click **New host**, or open an existing host and click **Edit**. + + + At the top of the editor, select **RDP** in the **SSH / RDP / VNC** switch. The port changes to `3389`. A custom port you already typed is kept. + + + Enter the hostname or IP, **Username** and **Password**. **Domain** is optional and only needed for Windows domain accounts. + + + Set **RDP SECURITY**, **CLIPBOARD** and **SSH TUNNEL** as described below, then click **Save**. + + + + + ![Host editor in RDP mode with the SSH, RDP and VNC switch, hostname, port 3389, username, password, domain and RDP security fields](/images/12-rdp/01-editor-rdp-mode.png) + + +### RDP security + +| Option | Meaning | +|---|---| +| **Auto (negotiate)** | Let the client and server agree. Use this unless you have a reason not to. | +| **NLA (CredSSP)** | Network Level Authentication. | +| **TLS only** | Skip NLA and use TLS only. | + +### Clipboard + +**Accept remote clipboard** controls whether the remote desktop may replace your local clipboard. It is on by default. The remote text is capped at 1 MiB. Turn it off for hosts you don't trust. + +### SSH tunnel + +**SSH TUNNEL** routes the RDP connection through one of your saved SSH hosts. Choose **Direct connection** (the default) or **via** a host. The selector only appears when you have at least one other SSH host saved. The list only shows SSH hosts. See [Hosts](/user-guide/hosts) for connection chains. + + + ![Lower part of the RDP host editor showing RDP SECURITY set to Auto, the Accept remote clipboard switch and the SSH TUNNEL selector](/images/12-rdp/02-rdp-security.png) + + +RDP hosts carry an **RDP** badge on the hosts dashboard, in list rows and in the host panel header. + + + ![Hosts dashboard with the Demo Desktop card marked with an RDP badge](/images/12-rdp/04-dashboard-rdp-badge.png) + + +## Connect and trust the certificate + +Click the host card to connect. The first time you connect to a server, YourSSH stops before it sends any credentials and shows **Trust RDP certificate?** with the server address and the certificate's SHA-256 fingerprint. + + + ![Trust RDP certificate dialog with the server address, SHA-256 fingerprint and Reject and Accept buttons](/images/12-rdp/05-cert-trust-dialog.png) + + +- Click **Accept** to pin the certificate and continue. YourSSH reconnects and signs in. +- Click **Reject** to cancel. Nothing was sent to the server. + +Compare the fingerprint with one you trust before you accept. + + +If the server's certificate changes later, YourSSH aborts the connection before authentication and shows **RDP certificate changed**. Your password is never sent. Click **Trust new cert** only if you know the certificate was replaced. Otherwise click **Reject**, because a changed certificate can mean someone is intercepting the connection. + + +## Use the session + + + ![RDP session showing a remote Linux desktop, the toolbar with four icon buttons and the Connected status bar](/images/12-rdp/06-session-connected.png) + + +The toolbar at the top right has four buttons: + +| Button | What it does | +|---|---| +| **Send Ctrl+Alt+Del** | Sends the key combination to the remote desktop. | +| **Push clipboard to remote** | Sends your local clipboard text to the remote desktop. | +| **Fullscreen** | Hides the app chrome. Available while connected. | +| **Disconnect** | Ends the session. | + +- **Keyboard and mouse.** Keys, left, right and middle clicks and scrolling go to the remote desktop. App shortcuts are not typed into it. +- **Clipboard.** Text copied on the remote desktop lands in your local clipboard, if **Accept remote clipboard** is on. YourSSH also sends your local clipboard when the RDP view gains focus, but only if the text changed since the last push. +- **Size.** The desktop size follows your window when you connect. The status bar shows the negotiated size. + +Rename, color tag and pin work on RDP tabs like on SSH tabs. See [Terminal](/user-guide/terminal). + +## Fullscreen + +Click **Fullscreen** in the toolbar. The tab bar and sidebar disappear and the remote desktop fills the screen. + +A small pill with the host name and the toolbar buttons shows for a moment and then hides. Move the mouse to the top edge of the screen to bring it back. Use its exit button to leave fullscreen. + + + ![Fullscreen remote desktop with a floating pill at the top showing the host name and four icon buttons](/images/12-rdp/10-fullscreen-hover-pill.png) + + +YourSSH leaves fullscreen on its own if the session disconnects or you switch to another tab. + +## Disconnects and Retry + +When the session ends, the tab shows the reason and a **Retry** button. This happens when you click **Disconnect**, when the server ends the session, or when the connection drops. Click **Retry** to connect again. + + + ![Ended RDP session with the text disconnected by user and a Retry button](/images/12-rdp/12-disconnected.png) + + +Unexpected drops also appear in the notification bell. Connects and disconnects are written to the [audit log](/user-guide/audit-log). + +## Not supported + +- Audio redirection. +- Drive and printer redirection. +- Changing the desktop size while connected. Reconnect to apply a new window size. +- Recording, split view, the input bar and snippets. These are SSH-only and hidden on RDP tabs. + +## Related pages + + + + Connect to Linux VNC servers. + + + Add, group and tag hosts. + + diff --git a/user-guide/recording.mdx b/user-guide/recording.mdx new file mode 100644 index 0000000..1bbc66a --- /dev/null +++ b/user-guide/recording.mdx @@ -0,0 +1,91 @@ +--- +title: "Session recording" +description: "Record terminal sessions to asciicast files, replay them in the built-in player, and keep secrets out of the recording." +icon: "video" +--- + +YourSSH records terminal sessions to [asciicast v2](https://docs.asciinema.org/manual/asciicast/v2/) (`.cast`) files. Use them for runbooks, demos or a record of what happened on a host. + +## Start and stop a recording + +Open an SSH or local terminal session and click **REC** at the top right of the terminal. While a session records, the button turns red and its tooltip reads **Stop recording** (it reads **Start recording** when idle). The status bar at the bottom shows a red `REC` timer. + + + ![A terminal session with the REC button active and a 00:00:02 timer in the status bar](/images/03-first-connect/20-recording-active.png) + + +Click the button again to stop. Closing the session also stops the recording. Recording isn't available for RDP and VNC tabs. + + + ![The terminal after the recording stopped](/images/10-recordings/01-recording-stopped.png) + + +## Record every session of a host + +To record a host every time you connect, turn on **Auto-record sessions** in the host editor ("Start recording automatically on connect"). See [Hosts](/user-guide/hosts). + +## Redact secrets + +YourSSH masks secrets before it writes them to the file, so a recording you share doesn't leak a password someone echoed mid-session. Each match is replaced with `[REDACTED]`. The patterns are the same ones the [audit log](/user-guide/audit-log) uses: + +- `password=`, `token=`, `secret=` and `api_key=` style values, including prefixed forms such as `PGPASSWORD=` +- `Authorization: Bearer` tokens +- `sshpass -p` +- the attached `-p` form of `mysql` and `mariadb` +- `redis-cli -a` +- passwords inside URLs (`scheme://user:pass@host`) + +Redaction is on by default. You control it in two places: + +- **Settings → Recording → Redact secrets in recordings** is the global switch. +- **Redact secrets in recordings** in a host's editor opts a single host out. It only has an effect while the global switch is on. + +Local terminal recordings follow the global switch alone. YourSSH reads the setting when a recording starts, so changing it during a recording applies to the next one. + + +Redaction is a safety net, not a guarantee. A secret broken up by color codes, or one that doesn't match a known pattern, isn't caught. Also, YourSSH buffers output briefly so it can match secrets split across chunks, which makes replay timing per line rather than per keystroke. + + +## Recording library + +Click **Recordings** in the sidebar to open the **Recording Library**. It groups recordings by host (for example `demo@127.0.0.1`) and shows each one's date and size. Click the refresh button at the top to rescan the folder. + + + ![The Recording Library with one recording for demo@127.0.0.1](/images/10-recordings/02-library.png) + + +Click a recording, or its play button, to open the player next to the list. + + + ![The recording player with a timeline, play button and speed menu](/images/10-recordings/03b-player-playing.png) + + +| Control | What it does | +|---|---| +| Play / pause button | Starts or pauses the replay. | +| Timeline | Shows elapsed and total time. Drag or click it to seek. | +| Speed menu | Plays at `0.5x`, `1.0x`, `2.0x` or `5.0x`. | + +Click the trash icon on a recording to delete it. YourSSH asks **Delete recording?** first, and the file is removed from disk. + + + ![The Delete recording confirmation dialog](/images/10-recordings/04-delete-confirm.png) + + +## Where recordings are stored + +Recordings go to the folder in **Settings → Recording → Recording path**. The default is `Documents/YourSSH/Recordings` in your home folder. Click **Change…** to pick another folder. + +Each host gets a sub-folder, and each recording is named by its start time. Local terminals use a sub-folder named `local`. + +```text +/@/session_YYYY-MM-DD_HH-mm-ss.cast +``` + +YourSSH creates the folders and files so only your user can read them (mode `700` and `600` on macOS and Linux), because a recording can contain sensitive output. Because the files are standard asciicast v2, you can also play them with the `asciinema` tool. + +## Related pages + +- [Terminal](/user-guide/terminal) +- [Audit log](/user-guide/audit-log) +- [Settings](/user-guide/settings) diff --git a/user-guide/settings.mdx b/user-guide/settings.mdx new file mode 100644 index 0000000..a60d1aa --- /dev/null +++ b/user-guide/settings.mdx @@ -0,0 +1,136 @@ +--- +title: "Settings" +description: "Every section of the Settings screen: connection, appearance, terminal, recording, security, sync, AI providers, keyboard shortcuts and updates." +icon: "settings" +--- + +Open **Settings** from the sidebar. All sections sit on one scrolling page, in two columns on a wide window and in a single column on a narrow one. Changes apply immediately. + + + ![The Settings screen showing the Connection, Appearance, Recording, Monitoring and Audit sections](/images/14-settings/01-settings-top.png) + + + + ![Settings in a small window with the Connection section](/images/20-small-window/05-settings-900.png) + + +## Connection + +| Setting | What it does | +|---|---| +| **Auto-reconnect** | Reconnect when a connection drops. On by default. | +| **Max reconnect attempts** | `Unlimited` (the default), `1 times`, `3 times`, `5 times` or `10 times`. With `Unlimited`, the tab shows a countdown whose delay grows between attempts. | +| **Keep-alive interval** | How often YourSSH pings the server to keep the connection alive: `Off`, `10s` (the default), `30s` or `60s`. | +| **Tmux Integration** | Attach to a tmux session on connect. Needs tmux on the server. | +| **Shell Integration** | Detect the working directory, command status and exit codes on bash and zsh. This powers the directory in the tab, gutter markers, jump-to-prompt and path completion. On by default. | + +## Appearance + +- **Color theme**: pick a terminal theme from the built-in list. +- **Font size**: a slider, 13pt by default. +- **Terminal font**: choose the terminal font. + +The same three controls are in the terminal's side panel, so you can change them without leaving a session. See [Terminal](/user-guide/terminal). + +## Terminal + +- **Terminal emulation type**: the `TERM` value reported to servers, `xterm-256color` by default. It applies to new SSH connections. +- **Default local shell**: the shell new local terminals use. **Platform default** picks your system's shell. +- **Add custom shell...** adds your own entry. Enter a **Display name**, an **Executable path** and optional **Arguments** (space-separated, no quoting). + +## Keyword highlighting + +Tints matching text in every terminal session. Turn the whole feature on or off with **Enable keyword highlighting**. + +The list ships with rules for words such as `error`, `fail`, `warning`, `success`, `done` and `OK`, each with its own on/off toggle. Use the pencil icon to edit a rule, the trash icon to delete it, and **Add rule** to create one with a label, a pattern and a color. A rule can match literal text or a regular expression. You can have up to 20 rules. + +## Recording + +- **Recording path**: the folder for `.cast` files. Click **Change...** to pick another folder. +- **Redact secrets in recordings**: mask passwords and tokens before they're written. On by default. + +See [Session recording](/user-guide/recording). + +## Monitoring + +- **Network Stats Monitor**: show a Rx/Tx overlay on the active session. +- **Command finish notification**: alert you when a command finishes in a session that isn't focused. + +## Audit + +- **Retention**: delete audit events older than this on launch. Choose `30 days`, `90 days` (the default), `365 days` or **Keep forever**. +- **Clear audit log**: click **Clear** to delete all events now, after a confirmation. + +See [Audit log](/user-guide/audit-log). + +## Security + +**Credential storage** shows where YourSSH keeps host passwords, sudo passwords and key passphrases: the macOS Keychain, the Windows Credential Manager or the system keyring on Linux. + +- **Encrypted** means the system credential store holds every credential. This is the normal state. +- **Plain text** means the store refused one or more credentials, so YourSSH saved them as readable text in its preferences file. The row shows how many, and **Retry** tries to move them back into the store. + +See [Keychain and credentials](/user-guide/keychain#how-credentials-are-stored) for the full behaviour. + +## Sync + +Choose between two tabs: **Cloud Sync** (your own Supabase project) and **P2P Transfer** (a one-time transfer over your network). Both are covered in [Sync](/user-guide/sync). + +## AI providers + +Enter an API key and choose a **Model** for each provider: **Anthropic**, **OpenAI** and **Google Gemini**. A check mark shows when a key is configured, and the eye icon reveals or hides a key while you type. YourSSH stores the keys in the system credential store. See [AI chat](/user-guide/ai-chat). + +## Keyboard + +Click **Configure** next to **Keyboard Shortcuts** to open the shortcuts screen. Click a shortcut, or its pencil icon, then press the new key combination. Press `Esc` to cancel. Changes are saved immediately. + + + ![The Keyboard Shortcuts screen listing eight actions with their key combinations](/images/14-settings/14-hotkeys-screen.png) + + +| Action | Default | +|---|---| +| Command Palette | `Ctrl+K` (`Cmd+K` on macOS) | +| New Session | `Ctrl+T` | +| Close Session | `Ctrl+W` | +| Next Session | `Ctrl+Tab` | +| Previous Session | `Ctrl+Shift+Tab` | +| Toggle Input Bar | `Ctrl+Shift+I` | +| Split Horizontal | `Ctrl+Shift+H` | +| Split Vertical | `Ctrl+Shift+E` | + +### Command palette + +Press `Cmd+K` / `Ctrl+K` anywhere in the app to open the command palette. It searches your hosts, sections of the app, snippets and app actions, so you can jump to a host or screen from the keyboard. + +## Updates + +Shows the **Current version** and a **Status** line. YourSSH checks GitHub for a newer stable release at launch and periodically while it runs. Click **Check for updates** to check right now. When a newer version exists, **Download & install** appears. + +Updates are never silent. YourSSH downloads the build for your operating system and hands it to the system installer, and you finish the install yourself: + +- **macOS**: opens the disk image. Drag the app to Applications. +- **Windows**: launches the installer. +- **Linux**: opens the package or archive with your default handler. + +If no build matches your platform, the releases page opens in your browser. + +## Notifications + +The bell at the top right of the window collects things that need your attention: + +- A new YourSSH version, with **Update** and **Details** buttons. +- A session that dropped unexpectedly, such as **Connection closed by the server.** +- A warning when a credential had to be stored without encryption. + +Opening the panel marks items as read. Dismiss items one by one, or click **Clear all**. + + + ![The notification panel open with two items](/images/19-notifications/02-bell-open.png) + + +## Related pages + +- [Sync](/user-guide/sync) +- [AI chat](/user-guide/ai-chat) +- [Keychain and credentials](/user-guide/keychain) diff --git a/user-guide/sftp.mdx b/user-guide/sftp.mdx new file mode 100644 index 0000000..5cd53b3 --- /dev/null +++ b/user-guide/sftp.mdx @@ -0,0 +1,156 @@ +--- +title: "SFTP" +description: "Browse and transfer files between your computer and remote hosts in a dual-panel file manager." +icon: "folder" +--- + +The **SFTP** screen shows two file panels side by side. Each panel can show your local files or any saved host, so you can copy local to remote, remote to local, or between two hosts. + + +![Dual-panel SFTP with the local filesystem on the left and Demo Server on the right](/images/07-sftp/03-dual-panel.png) + + +## Open SFTP + +Click the **SFTP** tab at the top, or **SFTP** in the sidebar. You can also choose **SFTP** from a host card menu. + +Each panel has a **source chip** at the top left. It starts as **Local** on the left. Click it to switch a panel to **Local** or to any saved host. A panel with no host shows **Connect to host** and a **Select host** button. + + +![Host picker for the remote SFTP panel](/images/07-sftp/02-host-picker.png) + + +SFTP uses the same stored credentials, [host key checks](/user-guide/host-keys) and [connection chain](/user-guide/hosts) as the terminal. Connections, paths and running transfers survive switching to other tabs. When you return to SFTP, it resumes where you left off. + +## Navigate + +- Click a row to select it. Double-click it, or press `Enter`, to open a folder or a file. +- Click a segment of the breadcrumb to jump to that folder. +- Click the pencil icon next to the breadcrumb to type or paste a path, then press `Enter`. Press `Esc` to cancel. +- Use the back and forward arrows to move through your visited folders, and the refresh icon to reload the listing. +- **Filter** narrows the current listing as you type. +- Click a column header (**Name**, **Modified**, **Size**, **Permissions**; the local panel also has **Kind**) to sort. + + +![A selected file row in the local panel](/images/07-sftp/06-select-single-click.png) + + +## Select files + +Use the checkbox on each row, or click rows with `Cmd` / `Ctrl` to add to the selection, or `Shift` to select a range. The header checkbox selects every entry that matches the current filter. The footer shows the item count or `1 selected`. + +## Transfer files + +Select entries in one panel, then: + +| Action | How | +|---|---| +| Upload | Select local files and click the arrow pointing right (**Copy →**), or drag them to the remote panel | +| Download | Select remote files and click the arrow pointing left (**Copy ←**), or drag them to the local panel | +| Copy to the other panel | Right-click and choose **Copy to target directory** | + +**Copy to target directory** is disabled, with a reason in the menu, when it can't run: no target panel, folders between two remote hosts, or both panels showing the same folder. Uploading or downloading a single file replaces a file with the same name. Uploading a folder skips remote files that already exist, and copying between two local folders skips existing files and reports how many. + +### Transfer queue + +A panel docked at the bottom shows progress per file. Transfers run in the background, so the panels stay usable, and starting another transfer queues it on the same panel. + + +![Transfer queue at the bottom of the SFTP screen showing Transferred 1 / 1 files](/images/07-sftp/10-upload-progress.png) + + +- Click **Minimize** to shrink the panel to a slim strip, and **Expand** to bring it back. +- A successful batch closes itself after a few seconds. A batch with errors stays until you close it. +- Click **Cancel** to stop everything still pending. After a batch finishes the button becomes **Close**. + +Large transfers keep running while you work in a terminal tab. + +## File menu + +Right-click an entry for its menu. The same menu serves the local and the remote panel. + + +![Remote entry context menu with Open, Copy to target directory, Rename, Delete, Refresh, New Folder, Edit Permissions and Copy path](/images/07-sftp/07-remote-context-menu.png) + + +| Item | What it does | +|---|---| +| **Open** | Opens a folder, or opens a file in the built-in editor or your default app | +| **View** | Read-only preview in the editor, with no save. Safe for logs and configuration | +| **Edit** | Opens the file in the built-in editor | +| **Open with** | Lists installed apps that can open the file type, plus **Choose…** for any app | +| **Copy to target directory** | Sends the entry to the folder shown in the other panel | +| **Rename** | Renames in place | +| **Delete** | Deletes permanently. There is no trash | +| **Refresh** | Reloads the current folder | +| **New Folder** | Creates a folder | +| **Edit Permissions** | Opens the permissions dialog (see below) | +| **Copy path** | Copies the entry's full path | + +**View**, **Edit** and **Open with** appear for files. The **Actions** menu in each panel header also offers **New Folder**, **Rename** and **Delete**, plus **New File** on a remote panel. + +### Rename, new folder and delete + +**Rename**, **New Folder** and **New File** open a small dialog where you type a name and confirm with **Rename** or **Create**. **Delete** asks you to confirm and names the entries: `Delete "…"? This cannot be undone.` + +If an operation fails, YourSSH shows a readable message instead of a raw error code. For example, creating a folder whose name exists shows `Create folder failed: "releases" already exists.` Other messages cover missing entries (`"x" no longer exists.`), `Permission denied for "x".`, and a lost connection. + + +![Error toast: Create folder failed, "releases" already exists](/images/07-sftp/15b-mkdir-existing.png) + + +## Edit permissions + +**Edit Permissions** opens a dialog titled **Permissions — name**. It has a grid of **Read**, **Write** and **Execute** checkboxes for **Owner**, **Group** and **Others**, kept in sync with an **Octal** field such as `644`, `0755` or `4755`. Special bits survive when you only change checkboxes. + +- The octal field accepts three or four octal digits. **Apply** stays disabled while the value is incomplete or invalid. +- For folders, **Apply recursively** runs `chmod -R`. The walk never follows symbolic links, so a link can't change files outside the tree. +- If the server doesn't report the current permissions and a stat also fails, the dialog warns **Current permissions unknown** and keeps **Apply** disabled until you set a mode. +- On the local panel, permissions use the system `chmod` and aren't available on Windows. + + +![Permissions dialog with rwx checkboxes and the octal field set to 644](/images/07-sftp/12-permissions-dialog.png) + + +## Edit files + +Double-clicking a text file, or choosing **Edit**, opens the built-in editor. On macOS it is the Monaco code editor with syntax highlighting for the file type. On Windows and Linux it is a plain text editor. Use the back button to return, and save to upload your changes. **View** opens the same editor read-only. + +The editor refuses files it can't edit safely: files with a binary extension, files larger than 5 MB, and files with a null byte near the start. YourSSH then offers **Cannot edit in-app** with an **Open externally** button. + +### Open with an external app + +**Open with** and **Open externally** download the file to a temporary folder and open it in the app you choose. YourSSH watches that local copy and uploads it back each time you save. A message confirms `Opened … — watching for changes`. + +For safety, YourSSH refuses to open executables from a server externally (for example `.exe`, `.bat`, `.lnk`, `.command` and `.desktop` files) and points you to download them instead. In the local panel, opening such a file asks first. + + +![Run this file? dialog with Cancel and Open anyway](/images/07-sftp/18-run-file-confirm.png) + + +## Sudo mode (root transfers) + +Each host has an **SFTP MODE** setting in the host editor: **Default**, **Sudo (root)** or **Custom command**. + +- **Sudo (root)** starts the remote SFTP server through `sudo`, so browsing, uploads, downloads, rename and delete all run as root. YourSSH finds the server's path across common distributions. +- With a `NOPASSWD` sudoers entry it works silently. Otherwise YourSSH asks for the **Sudo password** and can remember it with **Remember in system keychain**. +- **Custom command** runs a command you provide, for example `sudo /usr/lib/openssh/sftp-server`. The field is required in this mode. +- A panel running elevated shows a root badge with the tooltip **SFTP runs elevated on this host**. + + +In sudo mode every file operation has root rights on that host. Use it only when you need it. + + +## Small windows + +Down to the 800 × 600 minimum window size, both panels stay usable and the layout adapts. + + +![SFTP screen in a small window](/images/20-small-window/04-sftp-900.png) + + +## Related pages + +- [Port forwarding](/user-guide/port-forwarding) to reach services behind a host. +- [Hosts](/user-guide/hosts) for credentials and connection chains used by SFTP. +- [Bulk actions](/user-guide/bulk-actions) to push files to many hosts at once. diff --git a/user-guide/snippets.mdx b/user-guide/snippets.mdx new file mode 100644 index 0000000..db41392 --- /dev/null +++ b/user-guide/snippets.mdx @@ -0,0 +1,87 @@ +--- +title: "Snippets" +description: "Save commands you run often and send them to a terminal session with one click." +icon: "code" +--- + +Snippets is a built-in plugin. It stores reusable shell commands and runs them in the terminal you are working in. The plugin is off until you turn it on in **Plugins** (sidebar). While it is off, the **Snippets** sidebar item and the terminal panel button are hidden. + +## The Snippets screen + +Once the plugin is on, click **Snippets** in the sidebar under **Tools**. The list shows each snippet with its label, a tag, the command and an optional description. The first time the plugin loads, it adds a few examples such as **Disk usage** (`df -h`) and **Open ports** (`ss -tlnp`). + + + ![Snippets screen listing Disk usage, Memory info, Running processes, Tail syslog, Network interfaces and Open ports with their commands and tags](/images/15-plugins/03-snippets-screen.png) + + +Type in **Search snippets…** to filter the list. + +### Add a snippet + + + + Click **NEW SNIPPET**. + + + Enter a **Label** and a **Command**. Both are required. **Description (optional)** and **Tag (optional)** are for your own organization. Snippets with the same tag are grouped together in the terminal panel. + + + Click **Add Snippet**. + + + +### Work with a snippet + +Hover a snippet to show its buttons: + +| Button | What it does | +|---|---| +| **Run in terminal** | Sends the command to the active session and presses Enter. | +| **Copy** | Copies the command to the clipboard. | +| **Delete** | Removes the snippet. | + +If no SSH session is active, YourSSH shows a notice and sends nothing. + + +The Snippets screen can add and delete snippets but has no edit form. To change a snippet, delete it and add a new one. + + +## The terminal side panel + +You don't have to leave the terminal to use snippets. In a connected session, click **Toggle Snippets Panel** in the terminal header. The panel opens beside the terminal without resizing the session. + + + ![Terminal session with the Snippets side panel showing the system and logs groups, each snippet with Run and Copy buttons](/images/03-first-connect/17-snippets-panel.png) + + +- Use **Search snippets…** to filter. +- Click **Run** to type the command into the focused session and press Enter. The panel shows **No active SSH pane selected** when there is no running session to receive it. +- Click **Copy** to copy the command instead. +- Click the close button to hide the panel. + +The panel works in SSH sessions and local terminals. It is hidden for RDP and VNC tabs. + + +**Run** executes the command immediately. Check what a snippet does before you run it on a production host. + + +## Snippets on mobile + +The **Snippets** tab in the Android app lists the same kind of snippets. Chips at the top filter by tag, with **All** showing everything. Tap a snippet to run it in the active session. The header shows which host receives it, or **No active session**. + + + ![Android Snippets tab with tag chips All, system and logs and three snippet cards](/images/M1-mobile/06-snippets.png) + + +See [Mobile](/user-guide/mobile) for the rest of the Android app. + +## Related pages + + + + Sessions, split view and the header. + + + Run a command on many hosts at once. + + diff --git a/user-guide/sync.mdx b/user-guide/sync.mdx new file mode 100644 index 0000000..43773bd --- /dev/null +++ b/user-guide/sync.mdx @@ -0,0 +1,161 @@ +--- +title: "Sync and device transfer" +description: "Keep your hosts in sync across devices with your own Supabase project, or move them once over your local network with a QR code." +icon: "refresh-cw" +--- + +YourSSH offers two ways to get your hosts onto another device. Both live in **Settings → Sync**. + + + + Continuous sync through a free Supabase project that you own. Everything is encrypted on your device before it's uploaded. + + + A one-time transfer between two devices on the same network, using a QR code. No account needed. + + + + + ![The Sync section with the Cloud Sync tab, Project URL and Anon key fields](/images/14-settings/09-sync.png) + + +## Cloud Sync + +### What syncs + +Cloud Sync uploads your **host list together with host passwords**. Nothing else goes into the payload: private key files, snippets, AI provider keys, known hosts and settings are not uploaded. + + +When newer data arrives from the cloud, it **replaces** the host list on the receiving device. A host that exists only on that device is removed, together with its saved secrets. + + +### How it's protected + +- YourSSH encrypts the data on your device with AES-256-GCM before upload. Supabase only ever stores ciphertext. +- The encryption key comes from a **12-character sync code** that YourSSH generates for you. The code never leaves your devices. +- The sync code is the only secret that protects your data. The Supabase **anon key** is just an API credential, and on its own it can't decrypt anything. +- The row that holds your data is named with a one-way hash of the sync code, not the code itself. +- YourSSH rejects older data that someone replays from the server, so a stale copy can't overwrite your newer hosts. + + +If you lose the sync code, the synced data can't be decrypted or recovered. Copy it somewhere safe. Someone who holds your anon key can still delete or overwrite the cloud row (you'd see this as a decrypt failure), so don't share the key publicly. + + +### Set it up + + + + Sign up at [supabase.com](https://supabase.com), click **New project**, choose a region close to you and set a database password. + + + In Supabase, open **Project Settings → API**. Copy the **Project URL** (`https://.supabase.co`) and the anon (publishable) key. + + + In **Settings → Sync → Cloud Sync**, paste the URL into **Project URL** and the key into **Anon key**, then click **Save & Test**. + + + If the `sync_data` table doesn't exist, YourSSH says **Table not found** and shows the SQL to run. Click **Copy SQL**, then **Open SQL Editor**, paste the SQL and run it. Click **Save & Test** again. + + ```sql + create table if not exists sync_data ( + sync_id text primary key, + payload text not null, + updated_at timestamptz not null default now() + ); + alter table sync_data drop constraint if exists sync_data_sync_id_check; + alter table sync_data enable row level security; + drop policy if exists "anon_rw" on sync_data; + create policy "anon_rw" on sync_data + for all + to anon + using (true) + with check (true); + ``` + + The policy lets anyone with your anon key read and write the table. That is safe for confidentiality because the data is encrypted with your sync code, which Supabase never sees. + + + When the status shows **Connected**, click **Generate** in the **Sync code** area. YourSSH shows a code like `XXXX-XXXX-XXXX`. Click the copy button and store it safely. + + + + + ![The Sync section showing Connected status, a Disconnect button and the Sync code field](/images/14-settings/15-sync-configured.png) + + +Sync turns on as soon as the project URL, anon key and sync code are all set. There's no separate switch. + +### Add another device + +On the new device, enter the **same Project URL and Anon key** and click **Save & Test**. Then type your existing sync code into the **Sync code** box and click **Save code**. The device downloads and decrypts your hosts and joins automatically. The code is case-insensitive and ignores dashes, so `abcd-2345-efgh` and `ABCD2345EFGH` are the same. + +### When it syncs + +- YourSSH pushes your changes each time you add, edit or delete a host. If a push fails, it retries every 30 seconds. +- It checks for newer data from other devices when the window regains focus. +- The status line below the controls reads **Syncing…**, **Synced**, or **Sync error:** followed by the reason. + +### Regenerate the code + +Click **Regenerate** (the **Generate** button after a code exists) to create a new code. YourSSH asks **Regenerate sync code?** first. A new code starts a new cloud record, and data tied to the old code is unreachable until you enter the old code again. + +### Disconnect + +Click **Disconnect** next to **Connected**. YourSSH asks **Disconnect sync?** and warns that it removes the Supabase URL, anon key and sync code from this device. Without the sync code, the synced data can't be recovered, so copy it first. + + + ![The Disconnect sync confirmation dialog](/images/14-settings/19-sync-disconnect-confirm.png) + + +### Troubleshooting + +| Message | What to do | +|---|---| +| **Table not found** | Run the SQL shown in the app in the Supabase SQL Editor. | +| An error from Supabase about an invalid API key | Re-copy the anon key from **Project Settings → API**. | +| **URL and Anon key are required** | Fill in both fields before **Save & Test**. | +| **Enter a valid 12-character sync code.** | Check the code. It must be exactly 12 characters (dashes are optional). | +| A decrypt error | Every device must use the same sync code. | + +## P2P Transfer over your network + +Use P2P Transfer to move your hosts to another device once, without any cloud account. It transfers **all hosts and their saved passwords**, the same payload as Cloud Sync, and nothing else. It isn't continuous sync. + + + ![The P2P Transfer tab with Show QR Code and Import via Code buttons](/images/14-settings/16-sync-p2p.png) + + +### Send from a desktop + + + + On the device that has your hosts, open **Settings → Sync → P2P Transfer** and click **Show QR Code**. The **Export via QR** dialog opens. + + + If the computer has more than one network connection (Wi-Fi, Ethernet, VPN), a **Network interface** list appears. Choose the one the other device can reach. Changing it restarts the timer. + + + The QR code is valid for 2 minutes, and a countdown shows the time left. The dialog says **Waiting for device to scan...**. When time runs out it says **Session expired.** Click **Cancel**, then **Show QR Code** again for a new code. + + + + + ![The Export via QR dialog with a QR code and a 1:58 countdown](/images/14-settings/17-sync-qr-dialog.png) + + +While the dialog is open, YourSSH runs a small server on a random port on your computer. The data is encrypted with a fresh random key that travels inside the QR code, so keep the QR visible only to the person receiving it. The server shuts down automatically after one successful transfer. + +### Receive + +- **On Android**, open the **Pair device** screen and tap **Scan QR code**. See [YourSSH for Android](/user-guide/mobile). An Android phone can also be the sender: its **Pair device** screen shows a QR code for another device to scan. +- **On desktop**, click **Import via Code**, paste the transfer code into **Import via Transfer Code** (or click **Load from file**), then click **Import**. On the sending device, click **Copy transfer code** in the **Export via QR** dialog to get the code. + + + ![The Import via Transfer Code dialog](/images/14-settings/18-sync-import-dialog.png) + + +The receiving device downloads the encrypted data, decrypts it and imports the hosts. The import **replaces** every host on the receiving device. YourSSH says **All previous hosts replaced.** when it finishes, and it refuses a transfer that contains no hosts. + + +Both devices must be on the same network, or at least the sending computer's address must be reachable from the receiver. If the transfer can't connect, pick a different **Network interface** on the sender. + diff --git a/user-guide/terminal-sharing.mdx b/user-guide/terminal-sharing.mdx new file mode 100644 index 0000000..6a43f02 --- /dev/null +++ b/user-guide/terminal-sharing.mdx @@ -0,0 +1,96 @@ +--- +title: "Terminal sharing" +description: "Share a live SSH session with up to five teammates, end-to-end encrypted, and hand over control when you choose." +icon: "screen-share" +--- + +Terminal sharing lets teammates watch your live SSH session in their own YourSSH window. Guests see the terminal in real time and are read-only until you grant one of them control. + +## How it works + +- The host streams terminal output through your own **Supabase** project using Supabase Realtime. +- You share a **share code** that looks like `ROOM-SECRET`, for example `A3K9PX-XXXXXXXXXXXXXXXX` (6 + 16 characters). +- The code is also the encryption key. The channel name is a hash of the code, and every message is encrypted with AES-256-GCM using a key derived from the code. Supabase and anyone who only holds your project's anon key see neither the terminal content nor the secret. +- A guest who joins late first receives a snapshot of the recent output (up to about 500 KB), then live output. + +## Requirements + +- YourSSH is open on both the host's and the guest's machine. +- Both use the same Supabase project, configured in **Settings → Sync**. See [Sync](/user-guide/sync). +- The session you share is a connected SSH session. Local terminals can't be shared. + +Without a configured Supabase project, the **Share** button and the **Join Shared Session** command are hidden. + +## Share a session + + + + In a connected SSH tab, click the **Share** button (the screen-share icon) at the right of the terminal header. Its tooltip reads **Share this terminal**. + + + In the **Share Terminal** dialog, click **Start Sharing**. The dialog notes that the session is end-to-end encrypted with the share code. The title changes to **Sharing Live** and the dialog shows the share code and a QR code. + + + Click the code to copy it (a **Code copied** message confirms), and send it to your teammate. The QR code encodes `yourssh://share/`. While you share, the header button is highlighted and its tooltip reads **Sharing active**. + + + Open the dialog again and click **Stop Sharing**. Guests see **Session ended by host**. + + + +Treat the share code like a password. Anyone who has it can join, up to five guests at once. Joins are accepted automatically. + +## Join a session + + + + Press `Cmd+K` / `Ctrl+K` and choose **Join Shared Session**. + + + Paste the full code into the **Join Shared Session** dialog and click **Join**. A code that isn't in the `XXXXXX-XXXXXXXXXXXXXXXX` shape is rejected with an error, and you see **Configure Supabase first (Settings → Sync)** if sync isn't set up. + + + +A new tab opens in watch mode. A banner above the terminal tells you where you stand: + +| Banner | Meaning | +|---|---| +| **Watching: … · Read-only** | You can see the session but your keystrokes are not accepted | +| **You have control** | The host granted you control, so your input reaches the host's shell | +| **Session ended by host** | The host stopped sharing or disconnected | + +Click **Leave** in the banner, or close the tab, to disconnect. This doesn't affect the host. If the host already has five guests, your join is rejected. + +The status bar shows **Watching** instead of **Connected** for a watch tab. + +## Hand over control + +Guests can't type until you allow it. In the sharing dialog, the guest list appears under **Grant control**. Each guest is shown by a short ID (the first 8 characters). + +- Click **Grant** next to a guest to give them control. The section becomes **Control granted**. +- Click **Revoke** to take control back. + +Only one guest can have control at a time. The host's shell accepts input only from the guest that currently has control, and your own typing always works. Input from any other guest is rejected. + + +A guest with control can run commands as your user on the remote host. Grant control only to people you trust, and revoke it when you are finished. + + +## Security notes + +- **Encryption.** Messages are end-to-end encrypted with a key derived from the share code, over the TLS connection to Supabase. The server doesn't hold the key. +- **Share code is the credential.** Anyone who learns the code can join while you share, until the five guest slots are full. Send it over a channel you trust and stop sharing when done. +- **Guests aren't authenticated individually.** There are no per-guest keys, so a guest who holds the code could pretend to be another guest. While you have granted control to one guest, treat all guests as able to act with that identity. +- **Auto-accept.** Join requests are accepted without confirmation. Watch the guest list in the dialog. + +## Limitations + +- Sharing needs a live Supabase Realtime connection. +- A maximum of five guests per shared session. +- When the host disconnects or stops sharing, every guest session ends. +- Only SSH sessions can be shared, not RDP, VNC or local shells. + +## Related pages + +- [Terminal](/user-guide/terminal) for panes, search and shortcuts. +- [Sync](/user-guide/sync) to configure the Supabase project that sharing uses. diff --git a/user-guide/terminal.mdx b/user-guide/terminal.mdx new file mode 100644 index 0000000..2cc8ac4 --- /dev/null +++ b/user-guide/terminal.mdx @@ -0,0 +1,270 @@ +--- +title: "Terminal" +description: "Work in SSH and local terminal sessions with tabs, splits, search, an input bar, shell integration and themes." +icon: "terminal" +--- + +YourSSH runs an `xterm-256color` terminal for every SSH session and local shell, and adds tabs, split panes, search, a command input bar and shell integration on top. + + +![Terminal connected to Demo Server with the tab bar, header chips and status bar](/images/03-first-connect/07-terminal-ls.png) + + +## Open a session + +Click a host card on the **Hosts** dashboard, or open the card menu and choose **Connect**. A new tab opens and the connection starts. See [Hosts](/user-guide/hosts) for adding and editing hosts. + +You can also use the **+** button at the right end of the tab bar: + +- **New SSH session** opens the host picker. +- **New local terminal** opens a shell on your own machine (see [Local terminal](#local-terminal)). Below it, **Platform default shell** and each detected shell open that shell directly. + +## Tabs + +Each session is a tab in the top bar, next to the pinned **Home** and **SFTP** tabs. A tab shows: + +- A **health dot** (see below). +- An **OS glyph** for the detected remote system. +- The tab name, plus small dots for a colour tag and for an active recording. + +### Connection health dot + +The dot comes from a latency ping sent over the live SSH connection on the keep-alive interval (**Settings → Connection → Keep-alive interval**). + +| Dot | Meaning | +|---|---| +| Green | Healthy: latency under 150 ms | +| Amber | Degraded: latency 150–500 ms | +| Red | Unreachable: latency over 500 ms, ping timed out, or error | +| Grey | Disconnected, or no reading yet | +| Pulsing amber | Connecting or reconnecting | + +The ping uses the open connection instead of a new one, so a 5-second timeout also catches half-open drops, where the network is gone but the shell has not closed yet. Hover the dot to see latency, uptime and how many times the session reconnected. + +### Manage tabs + +| Action | How | +|---|---| +| Rename | Double-click the tab, or right-click and choose **Rename** | +| Colour tag | Right-click, then **Color tag**, and pick one of eight colours | +| Pin | Right-click and choose **Pin**. Pinned tabs move to the front, hide their close button and ignore middle-click. Use **Close** in the menu to close one | +| Reorder | Drag a tab left or right. Pinned and unpinned tabs stay in their own zones | +| Close | Click the close button on the tab, middle-click it, or right-click and choose **Close** | + + +![Tab context menu with Rename, Pin, Color tag and Close](/images/03-first-connect/14-tab-context-menu.png) + + +Tab names, colours and pin state are kept per host across reconnects and app restarts. + +### Notification bell + +The bell at the right end of the tab bar collects in-app notifications behind an unread badge: sessions that drop unexpectedly (closing a tab yourself never notifies), new releases with inline **Update** and **Details** buttons, and alerts about agent forwarding, insecure credential storage and refused `yourssh://` links. Opening the panel marks everything read. Dismiss items one by one or use **Clear all**. Notifications live in memory and reset when you restart the app. + +## Terminal header and status bar + +The header above the terminal has two sides: + +- **Left:** chips for the host name, `user@host`, the first two tags and the current directory. The directory appears when [shell integration](#shell-integration) is active. +- **Right:** layout buttons (**Single**, **Split Horizontal**, **Split Vertical**, **Quad**), the **Toggle Snippets Panel** button (only while the Snippets plugin is on), the **Toggle Terminal Settings** button, and **Broadcast** when more than one pane is open. Depending on your setup you also see the network stats widget, **Share** (see [Terminal sharing](/user-guide/terminal-sharing)) and **AI** (see [AI chat](/user-guide/ai-chat)). + +The status bar at the bottom shows the connection state (**Connected**, **Connecting…**, **Disconnected**, **Error**), `user@host`, the jump chain (`via …`) when the host uses a [connection chain](/user-guide/hosts), the agent forwarding state, the requested `TERM`, the size in columns × rows, and `REC` with an elapsed timer while you record. + + +![Terminal in a small window with header, layout buttons and status bar](/images/20-small-window/03-terminal-900.png) + + +## Split panes + +Use the layout buttons in the header, or the shortcuts, to show more than one session at once: + +| Layout | Button | Shortcut | +|---|---|---| +| Single pane | **Single** | | +| Two panes side by side | **Split Horizontal** | `Ctrl+Shift+H` | +| Two panes stacked | **Split Vertical** | `Ctrl+Shift+E` | +| Four panes | **Quad** | | + +Each pane shows one of your open sessions. A pane without a session shows **No session in this pane**. Open another session with **+** in the tab bar and it appears there. Click a pane to make it the active one. + + +![Two terminals side by side, Demo Server and DB Internal](/images/05-more-hosts/10-split-two-sessions.png) + + + +![Two terminals stacked, Demo Server above DB Internal](/images/05-more-hosts/11-split-two-sessions-vertical.png) + + +### Broadcast + +When two or more panes are open, **Broadcast** appears in the header. Turn it on, open the [input bar](#input-bar), and every command you submit there goes to all panes. Each target gets its own entry in the [audit log](/user-guide/audit-log). Broadcast only affects the input bar. Keystrokes typed straight into a terminal still go to that pane alone. + + +Broadcast runs the same command on every pane. Check which sessions are open before you submit. + + +To run a command on many saved hosts without opening tabs, use [Bulk actions](/user-guide/bulk-actions). + +## Search + +Press `Cmd+F` / `Ctrl+F` to open the search bar over the scrollback. Type text to highlight every match and see a counter such as **1 of 6**. Press `Enter` for the next match and `Shift+Enter` for the previous one. The `.*` button switches to regular expressions. Press `Esc` or click the close button to leave search. + + +![Terminal search bar showing 1 of 6 matches for "demo"](/images/03-first-connect/09-terminal-search.png) + + +## Input bar + +The input bar is a command line at the bottom of the terminal with its own history and completion. Toggle it with `Ctrl+Shift+I`. + + +![Input bar below the terminal with the placeholder "Type command…"](/images/03-first-connect/10-input-bar.png) + + +- Press `Enter` to send the line to the session. +- Press `↑` and `↓` to move through the command history of the session. +- Press `Tab` to accept the highlighted suggestion. Use `↑` and `↓` to pick one while suggestions are showing. +- Press `Esc` to close the input bar. +- With [shell integration](#shell-integration) active, a path typed after `cd`, `cat`, `ls` and similar commands completes against the real remote directory, merged with your history. YourSSH reads that directory over SFTP. + +## Copy, paste and mouse + +Select text by dragging. Double-click selects a word. + +| Action | macOS | Windows and Linux | +|---|---|---| +| Copy | `Cmd+C` | `Ctrl+C` with a selection, or `Ctrl+Shift+C` | +| Paste | `Cmd+V` | `Ctrl+V` or `Ctrl+Shift+V` | +| Paste with the mouse | Middle-click | Middle-click | +| Context menu | Right-click | Right-click | + +On Windows and Linux, `Ctrl+C` copies only while text is selected, then clears the selection. Press it again to send `Ctrl+C` (SIGINT) to the running program as usual. + +Right-click opens a menu with **Copy**, **Paste**, **Select All** and **Reset Terminal**. **Copy** is disabled when nothing is selected. If a full-screen program crashes and leaves the terminal looking frozen, choose **Reset Terminal**. It is the local equivalent of running `reset`. + + +![Terminal context menu with Copy, Paste, Select All and Reset Terminal](/images/03-first-connect/13-terminal-context-menu.png) + + +Programs that capture the mouse (vim with `mouse=a`, htop, tmux with `mouse on`) keep receiving clicks instead of starting a selection or paste. + +### Scrolling + +The scrollback holds 10 000 lines per session. While you are scrolled up, new output does not pull the view back down. Typing or pressing `Enter` returns to the bottom. Use `Shift+PageUp` and `Shift+PageDown` to page through the scrollback from the keyboard. In full-screen programs that use the alternate screen, these keys go to the program instead. + +Inside full-screen programs that use the mouse, the wheel scrolls the program's own view. Programs without mouse support, such as `less` and `man`, receive arrow keys instead. + +## Shell integration + +On bash and zsh hosts, YourSSH installs a small prompt hook when you connect, so it can follow the remote shell through OSC 7 (working directory) and OSC 133 (command boundaries and exit status). The hook lives only in the live session. YourSSH never edits your `.bashrc` or `.zshrc`. + +The setup is silent. YourSSH waits until the shell is at a prompt, then sends the hook through a hidden handshake, so nothing appears in your terminal or recordings. If YourSSH can't confirm the shell is ready (an unusual shell, a full-screen program, or you started typing at once), it skips the hook for that session. + +Shell integration gives you: + +- **Working directory** in the header and in path completion. +- **Command gutter.** A thin strip at the left edge shows a dot beside each prompt: green for exit code 0, red for non-zero, grey for running or unknown. Click a dot to jump to that command. +- **Jump to prompt.** `Cmd+↑` / `Ctrl+↑` and `Cmd+↓` / `Ctrl+↓` scroll to the previous and next prompt. +- **Path completion** in the input bar. + +Shell integration is on by default. To turn it off: + +- For every host: **Settings → Connection → Shell Integration**. +- For one host: the **Shell integration** switch in the host editor. + +Sessions where a multiplexer strips the markers, such as some tmux setups, run without these features. + +## Keyword highlighting + +Keyword highlighting tints matching text in every terminal session, for example **Error**, **Fail** or **Warning**. Turn it on or off with the **Enable** switch under **KEYWORD HIGHLIGHTING** in the terminal settings panel, or with **Enable keyword highlighting** in **Settings → Keyword highlighting**. + +In **Settings → Keyword highlighting** you can add, edit and delete rules. A rule has a **Label**, a **Pattern**, **Regex** and **Case-sensitive** options, and a **Foreground** and **Background** colour (pick at least one). + +## Appearance and themes + +Click the **Toggle Terminal Settings** button (sliders icon) in the header to open the appearance panel beside the terminal. It holds the **Color theme**, the **Font size** (it previews live while you drag) and the **Terminal font**, plus the keyword highlighting switches. The same controls exist in **Settings**. + +Click the colour theme to open **Terminal Theme**, a grid of 46 themes with previews. **YourSSH Amber** is the default. Others include YourSSH Dark, Dracula, Tokyo Night, Nord, Solarized, Gruvbox, Catppuccin and Monokai, in dark and light variants. + + +![Terminal Theme picker with 46 themes and the terminal settings panel on the right](/images/03-first-connect/19-theme-picker.png) + + +## Snippets panel + +Click the **Toggle Snippets Panel** button (the `<>` icon) in the header to open your saved snippets beside the terminal. The button appears while the Snippets plugin is enabled. You can browse and search them, and run one against the active pane without leaving the terminal. Only one side panel is open at a time, so opening Snippets closes the appearance panel. Create and manage snippets in [Snippets](/user-guide/snippets). + + +![Snippets side panel open beside the terminal](/images/03-first-connect/17-snippets-panel.png) + + +## Recording + +Click **REC** at the top right of a terminal to record the session as an asciicast file. The status bar then shows the elapsed time. Click again to stop. See [Session recording](/user-guide/recording) for the library, playback and secret masking. + +## Auto-reconnect and tmux + +Set these in **Settings → Connection**: + +- **Auto-reconnect** reconnects when a connection drops. **Max reconnect attempts** accepts 1, 3, 5, 10 or **Unlimited**. +- **Keep-alive interval** sets how often YourSSH pings the server (10 s, 30 s, 60 s or **Off**). It also drives the health dot. +- **Tmux Integration** attaches to a tmux session on connect. It needs tmux on the server. A host can override the global value with **tmux: follow global**, **always on** or **always off** in the host editor. + +A session that drops without a pending reconnect adds an entry to the notification bell. + +## Local terminal + +Open **Local Terminal** in the sidebar, or choose **New local terminal** from the **+** menu, to start a shell on your own machine. Local shells are normal tabs. You can split them, record them and place them next to SSH panes. If the shell exits, the pane offers **Restart shell**, which relaunches the shell the tab started with. + +YourSSH detects the shells you have installed: + +- **Windows:** PowerShell, Command Prompt, PowerShell 7 (`pwsh`), Git Bash and one entry per WSL distribution. +- **macOS and Linux:** your `$SHELL` and everything listed in `/etc/shells`. + +Pick the default in **Settings → Terminal → Default local shell**, or choose another shell for one tab from the **+** menu. **Add custom shell…** in the same section accepts any executable with arguments. + +## Command palette + +Press `Cmd+K` / `Ctrl+K` to open the command palette. It searches saved hosts, navigation sections and app actions such as **New Host**, **Import SSH Config** and **Join Shared Session** (when sharing is available). Type to filter and press `Enter` to run the selected item. + +## Keyboard shortcuts + +The defaults below can be changed in **Settings → Keyboard → Configure**. + +| Action | Default | +|---|---| +| Command Palette | `Cmd+K` (macOS), `Ctrl+K` (Windows, Linux) | +| New Session | `Ctrl+T` | +| Close Session | `Ctrl+W` | +| Next Session | `Ctrl+Tab` | +| Previous Session | `Ctrl+Shift+Tab` | +| Toggle Input Bar | `Ctrl+Shift+I` | +| Split Horizontal | `Ctrl+Shift+H` | +| Split Vertical | `Ctrl+Shift+E` | + +Other keys in the terminal: + +| Action | Keys | +|---|---| +| Search the scrollback | `Cmd+F` / `Ctrl+F` | +| Previous or next command prompt | `Cmd+↑` `Cmd+↓` / `Ctrl+↑` `Ctrl+↓` | +| Page through the scrollback | `Shift+PageUp`, `Shift+PageDown` | + +When a key combination is a registered shortcut, YourSSH keeps it from reaching the shell. + +## Related pages + + + + Let teammates watch a live session. + + + Record sessions to asciicast files. + + + Save and run reusable commands. + + + Move files next to your terminal. + + diff --git a/user-guide/vnc.mdx b/user-guide/vnc.mdx new file mode 100644 index 0000000..fca9705 --- /dev/null +++ b/user-guide/vnc.mdx @@ -0,0 +1,87 @@ +--- +title: "VNC remote desktop" +description: "Connect to Linux VNC servers from a YourSSH tab, with an optional SSH tunnel to encrypt the connection." +icon: "cast" +--- + +YourSSH has a built-in VNC client for servers such as TigerVNC, x11vnc and TightVNC. A VNC session opens as a tab next to your SSH and RDP sessions. + +## Add a VNC host + + + + Click **New host** on the hosts dashboard, or **Edit** on an existing host. + + + Select **VNC** in the **SSH / RDP / VNC** switch at the top. The port changes to `5900`. A custom port is kept. + + + Enter the hostname or IP and the **Password**. The password is the VNC server password. A username is accepted, but most VNC servers ignore it. + + + Set **Accept remote clipboard** and, if you want, **SSH TUNNEL**, then click **Save**. + + + + + ![Host editor in VNC mode with hostname, port 5900, username, password, group, tags and the Accept remote clipboard switch](/images/13-vnc/01-editor-vnc-mode.png) + + +**Accept remote clipboard** lets the remote desktop replace your local clipboard. It is on by default and capped at 1 MiB. Turn it off for hosts you don't trust. + +**SSH TUNNEL** routes the VNC connection through one of your saved SSH hosts. Choose **Direct connection** (the default) or **via** a host. The selector only appears when you have at least one other SSH host saved. See [Hosts](/user-guide/hosts). + +VNC hosts carry a **VNC** badge on the hosts dashboard, in list rows and in the host panel header. + +## Connect + +Click the host card to connect. + + +Plain VNC has no encryption. There is no certificate dialog because there is no certificate, and the password exchange and the screen content travel unencrypted. Outside a trusted LAN, set an **SSH TUNNEL** so the session runs inside an encrypted SSH connection. + + +## Use the session + + + ![VNC session showing a remote Linux desktop, a toolbar with three icon buttons and the Connected status bar](/images/13-vnc/03-session-connected.png) + + +The toolbar at the top right has three buttons: + +| Button | What it does | +|---|---| +| **Push clipboard to remote** | Sends your local clipboard text to the remote desktop. | +| **Fullscreen** | Hides the app chrome. Available while connected. | +| **Disconnect** | Ends the session. | + +- **Keyboard and mouse.** Keys, clicks and scrolling go to the remote desktop. App shortcuts are not typed into it. +- **Clipboard.** Text copied on the remote desktop lands in your local clipboard, if **Accept remote clipboard** is on. YourSSH also sends your local clipboard when the VNC view gains focus, but only if the text changed since the last push. +- **Size.** The desktop uses the server's screen size and follows the server if it resizes. + +## Fullscreen + +Click **Fullscreen**. Move the mouse to the top edge to show a pill with **Push clipboard to remote** and **Exit fullscreen**. YourSSH leaves fullscreen on its own if the session disconnects or you switch tabs. + +## Disconnects and Retry + +If the server closes the connection or it drops, the tab shows a message and a **Retry** button. Unexpected drops also appear in the notification bell, and connects and disconnects are written to the [audit log](/user-guide/audit-log). + +Rename, color tag and pin work on VNC tabs like on SSH tabs. + +## Not supported + +- TLS or VeNCrypt, macOS Screen Sharing, RealVNC and UltraVNC logins. YourSSH supports servers with no authentication or a VNC password. +- Audio and file transfer. +- Recording, split view, the input bar and snippets. These are SSH-only and hidden on VNC tabs. + +## Related pages + + + + Connect to Windows and xrdp. + + + Add, group and tag hosts. + + diff --git a/user-guide/web-tools.mdx b/user-guide/web-tools.mdx new file mode 100644 index 0000000..8d7a765 --- /dev/null +++ b/user-guide/web-tools.mdx @@ -0,0 +1,102 @@ +--- +title: "Web tools" +description: "Send HTTP requests, encode and hash text, and browse web pages behind your port forwards without leaving YourSSH." +icon: "wrench" +--- + +Web Tools is a built-in plugin with four tools: **Browser**, **HTTP Client**, **Utilities** and **Port Tunnels**. Click **Web Tools** in the sidebar under **Tools** to open it. If it is missing, turn it on in **Plugins**. + + + ![Web Tools screen with Browser, HTTP Client, Utilities and Port Tunnels in the tool list](/images/18-web-tools/01-web-tools.png) + + +## HTTP Client + +**HTTP Client** is a small request builder, similar to Postman or Insomnia. The request runs from your computer. + + + + Pick the method from the list at the left of the URL bar: `GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `HEAD` or `OPTIONS`. Enter the URL. + + + Use the tabs under the URL bar: **Params**, **Auth**, **Headers** and **Body**. A tab shows a count or dot when it has content. + + + Click **Send**. + + + + + ![HTTP Client with the method dropdown open showing the HTTP methods](/images/18-web-tools/05-method-menu.png) + + +### Request tabs + +| Tab | What you set | +|---|---| +| **Params** | Query parameters as key and value rows. They are added to the URL. | +| **Auth** | **Auth Type**: **No Auth**, **Bearer Token**, **Basic Auth** or **API Key** (a **Key Name** and **Key Value**, sent in a **Header** or as a **Query Param** according to **Add to**). | +| **Headers** | Extra request headers as **Header** and **Value** rows. | +| **Body** | **JSON**, **URL Encoded** (key and value rows) or **None**. Methods that don't take a body show **Body not applicable for this method**. | + + + ![HTTP Client with a POST request, the Body tab set to JSON and the response headers on the right](/images/18-web-tools/06-post-body.png) + + +### Response + +The right side shows the status code, time and size. Switch between **Body** and **Headers**. JSON bodies are pretty-printed. Use the copy button to copy the body. + + + ![HTTP Client showing a GET request with query parameters and the formatted JSON response body](/images/18-web-tools/03-get-response.png) + + +### History + +Click the history button in the URL bar to open **History**. It lists earlier requests with method, URL and status (`ERR` when the request failed). Click one to load it again. Use the close button to hide the panel. + + + ![HTTP Client with the History panel listing earlier requests with their methods and status codes](/images/18-web-tools/08-history.png) + + + +Auth values and headers you type may contain secrets. They stay on your computer and are sent only to the URL you request. + + +## Utilities + +**Utilities** has four text tools. Type in **INPUT**, click a button and read **OUTPUT** (**HASH OUTPUT** on the Hash tool). The copy button copies the result. + +| Tool | Buttons | +|---|---| +| **Base64** | **Encode**, **Decode** | +| **URL** | **Encode**, **Decode** | +| **JSON** | **Format**, **Minify** | +| **Hash** | **SHA-256**, **SHA-512**, **SHA-1** | + +Bad input shows an error such as **Invalid JSON** or **Invalid Base64**. + + + ![Utilities screen with Base64, URL, JSON and Hash and empty input and output areas](/images/18-web-tools/09-utilities.png) + + +## Port tunnels and the browser + +**Port Tunnels** (the list is titled **Active Local Tunnels**) shows your active local port forwards as `http://127.0.0.1:` addresses. Click **Open** to load one in **Browser**, or the copy button to copy the address. This is a quick way to reach a web UI on a remote host. Set up the forward first in [Port forwarding](/user-guide/port-forwarding). + + + ![Port Tunnels list with one active tunnel, its local address, a copy button and an Open button](/images/18-web-tools/12-port-tunnels.png) + + +**Browser** is a simple built-in web view with back, forward and reload buttons and an address bar. It starts on `https://www.google.com`. It only loads `http` and `https` pages. Type a bare domain such as `example.com` and it adds `https://`. Any other text, including `file:` or `javascript:` addresses, becomes a Google search instead. + +## Related pages + + + + Create the tunnels that Web Tools can open. + + + Network tools, containers and more. + +