AutoSSH Manager

AutoSSH Manager is a terminal management panel for macOS user-level AutoSSH tunnels.

It stores tunnel definitions in TOML, generates LaunchAgents, and gives you a TUI for grouped tunnel inventory, lifecycle control, diagnostics, logs, and tunnel creation.

Features

• Manage AutoSSH tunnels as durable local TOML definitions.
• Generate macOS user LaunchAgents with stable com.autossh-manager.<id> labels.
• Start, stop, restart, enable, disable, duplicate, edit, and delete managed tunnels.
• Organize tunnels with user-defined groups shown in configuration order.
• Discover existing user LaunchAgents that directly run autossh or call scripts containing autossh.
• Treat discovered external tunnels as read-only definitions while still supporting status, lifecycle actions, and logs.
• Create tunnels from built-in templates: local forward, multi local forward, dynamic remote target, and raw command.
• Apply common AutoSSH and SSH defaults so typical tunnels only require the core host and port fields.
• Show launchd state, PID, uptime, declared local forwards, recent logs, and local TCP health.
• Refresh the logs view every 5 seconds without using a streaming tail -f.

Scope

• macOS user LaunchAgents only.
• SSH-based AutoSSH tunnels only.
• Uses existing SSH config, keys, and ssh-agent.
• Does not store passwords or SSH key passphrases.
• Existing non-managed AutoSSH LaunchAgents are discovered as read-only external tunnels.
• Remote host probing is intentionally out of scope for the first version.

Requirements

• macOS with user launchctl support.
• Node.js 20 or newer.
• autossh available in PATH, or configured through [settings].autossh_path.
• ssh available in PATH.

Install AutoSSH with Homebrew if needed:

brew install autossh

Installation

For local use from this source checkout:

npm install
npm run build
npm install -g .
autossh-manager doctor

The global install exposes both commands:

autossh-manager
asm

For development without installing globally:

npm install
npm run dev
npm run dev -- doctor

After the package is published to npm:

npm install -g autossh-manager
autossh-manager

Usage

Open the TUI:

autossh-manager

Run diagnostics:

autossh-manager doctor

Print the installed version:

autossh-manager version

Export the current TOML configuration:

autossh-manager export

Configuration

Managed tunnel definitions live at:

~/.config/autossh-manager/config.toml

XDG_CONFIG_HOME and XDG_STATE_HOME are honored when present. Explicit overrides are also supported:

AUTOSSH_MANAGER_CONFIG_DIR
AUTOSSH_MANAGER_STATE_DIR
AUTOSSH_MANAGER_LAUNCH_AGENTS_DIR
AUTOSSH_MANAGER_AUTOSSH_PATH

Generated LaunchAgents live at:

~/Library/LaunchAgents/com.autossh-manager.<id>.plist

Managed logs live under:

~/.local/state/autossh-manager/logs/

Minimal example:

version = 1

[settings]
autossh_path = "autossh"

[[groups]]
id = "default"
name = "Default"

[[tunnels]]
id = "prod-postgres"
name = "Production Postgres"
group_id = "default"
template = "local_forward"
enabled = false

[tunnels.ssh]
user = "ubuntu"
host = "example.com"
port = 22

[[tunnels.forwards]]
type = "local"
local_host = "127.0.0.1"
local_port = 15432
target_host = "127.0.0.1"
target_port = 5432

[tunnels.launchd]
run_at_load = true
keep_alive = true

Dynamic Remote Target and Raw Command templates execute trusted local configuration. Do not put secrets in those commands.

Distribution

For a local tarball release:

npm run typecheck
npm test
npm run build
npm pack

This produces a file like autossh-manager-0.1.0.tgz. Install it on another machine with:

npm install -g ./autossh-manager-0.1.0.tgz
autossh-manager doctor

For an npm release:

npm login
npm run typecheck
npm test
npm run test:integration
npm pack --dry-run
npm publish

The package uses prepack to rebuild dist before npm pack or npm publish.

Development

npm run typecheck
npm test
npm run build

Tests use temporary directories and mocked command runners. They do not mutate the real launchd state.

For a real macOS user-domain launchd smoke test:

npm run test:integration

The integration test uses isolated temporary config/state/LaunchAgents directories and a fake autossh executable. It creates temporary test labels, verifies start/restart/stop, logs, health checks, dynamic targets, raw commands, external discovery, deletion, and cascade group deletion, then cleans up.

Architecture

• src/config.ts: TOML parsing, schema validation, atomic writes, and safe apply backups.
• src/plist.ts: LaunchAgent generation.
• src/launchd.ts: user-domain launchctl lifecycle operations.
• src/external.ts: external AutoSSH LaunchAgent discovery.
• src/health.ts: service and local port health classification.
• src/logs.ts: bounded log reads.
• src/service.ts: higher-level tunnel and group operations.
• src/ui/: Ink TUI state, form models, and view components.
• src/doctor.ts: dependency and local state diagnostics.

License

MIT