@himeyama/carnelian

v1.1.0

Published

a month ago

AWS EC2 一覧・SSM 接続ローカルツール

0High
0Medium
0Low

himeyama

carnelian

AWS の EC2 インスタンスを一覧・SSM/Instance Connect で接続できるローカルツール。

EC2 一覧を表示し、画面内の仮想コンソール（ドラッグ可能なウィンドウ）から SSM セッションまたは Instance Connect で対象インスタンスに接続できる。EC2 情報取得と接続処理はバックグラウンドで AWS CLI を利用する。

インストーラ版・npm / npx 版のどちらも既定でデスクトップアプリ（Electron）として起動する。中身は同じローカルサーバで、Electron はそれを WebView ウィンドウに表示しているだけ。 --no-electron を付けるとブラウザ版（ローカルサーバ起動 + 既定ブラウザで表示）で動く。

前提条件

AWS CLI v2（PATH 通過済み・aws configure でプロファイル設定済み）
AWS Session Manager Plugin（SSM セッションマネージャー接続に必須）
OpenSSH クライアント（ssh / ssh-keygen が PATH 通過済み。Instance Connect 接続に必須。 Windows 10/11 は C:\Windows\System32\OpenSSH に既定で同梱）
Node.js 18 以上 … npm 経由で使う場合のみ（インストーラ版は Node を同梱するため不要）
対象 EC2 側の前提:
- SSM 管理下（SSM Agent 導入済み）… セッションマネージャー接続時
- パブリック IP が無い場合は同一 VPC に EC2 Instance Connect Endpoint が必要 … Instance Connect 接続時

AWS CLI / Session Manager Plugin / OpenSSH は外部バイナリのため、どの配布形態でも別途インストールが必要。

インストール

1. Windows インストーラ（推奨）

carnelian-Setup-<version>.exe を実行する。ユーザー単位インストールのため管理者権限は不要で、デスクトップとスタートメニューにショートカットが作られる。

2. npm

npm install -g @himeyama/carnelian
carnelian

グローバルインストール時にデスクトップショートカットを自動作成する。不要なら CARNELIAN_NO_SHORTCUT=1 を設定してインストールする。ショートカットは後から carnelian --install-shortcut / carnelian --remove-shortcut で追加・削除できる。

3. npx（インストールなし）

npx @himeyama/carnelian

ショートカットは作成されない。

起動

インストーラ版はショートカットから起動する（アプリウィンドウが開く）。

npm / npx 版はコマンドを実行すると既定で Electron のアプリウィンドウが開く。 --no-electron を付けるとローカルサーバが起動し、既定ブラウザが自動で開く（127.0.0.1 のみ待受、外部には公開しない。ポートが使用中の場合は自動で次のポートへフォールバックする）。

オプション

Usage: carnelian [options]

Options:
  --electron        open the Electron desktop window (default)
  --no-electron     run the browser version instead (headless server + default browser)
  --port <number>   listen port, browser version only (default: 3000)
  --host <address>  listen host, browser version only (default: 127.0.0.1)
  --open            open the default browser after startup, browser version only (default)
  --no-open         do not open the browser, browser version only
  --install-shortcut  create a desktop shortcut and exit
  --remove-shortcut   remove the desktop shortcut and exit
  -h, --help        show this help
  -V, --version     show version

開発

pnpm install          # postinstall で xterm.js を public/vendor/ にコピー
pnpm start            # ブラウザ版（node app.js）
pnpm electron         # Electron 版

CARNELIAN_PORT を設定すると Electron 版のリッスンポートを固定できる（既定は空きポート自動選択）。

配布物のビルド

pnpm run icon         # build/icon.ico を再生成（アイコンを変えたときだけ）
pnpm run pack         # dist/win-unpacked/ に展開（インストーラは作らない）
pnpm run dist         # dist/carnelian-Setup-<version>.exe（NSIS）
pnpm pack             # npm 配布用 tarball

インストーラは未署名のため、初回実行時に SmartScreen の警告が出る。

使い方

ヘッダーでプロファイル / リージョンを選択すると EC2 一覧が表示される。
Instance ID・Private IP・Public IP はコピーアイコンでクリップボードにコピーできる。
一覧の「接続」から仮想コンソールウィンドウを開き、SSM セッションマネージャーまたは Instance Connect でシェルに接続する（複数インスタンスへ同時接続可）。

接続方法はヘッダーで切り替え可能（既定: セッションマネージャー）。Instance Connect 接続時の OS ユーザーは既定 ec2-user、環境変数 CARNELIAN_EIC_OS_USER で変更できる。

ドキュメント

DESIGN.md — 設計判断・ディレクトリ構成・API / WebSocket 仕様
TROUBLESHOOTING.md — 発生した問題の原因・対応・再発時の確認手順

ライセンス

MIT

終了

インストーラ版・npm / npx 版（既定の Electron）: ウィンドウを閉じるとサーバと全接続セッションを終了する。ターミナルからの Ctrl+C でも終了する。
npm / npx 版 + --no-electron: Ctrl+C（SIGINT）でサーバと全接続セッションを正常終了する。

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme