ローカル実習環境および接続ガイド

xkatプラットフォームは、基本的にWebブラウザのみで快適なプログラミング実習を提供します。
Arduinoや組み込みハードウェア制御、または独立したUbuntu Lab VMが必要な講義では、**ローカルエージェント（xkat-cli）**を使用してブラウザとPCを安全に連携します。

セキュリティに関するご案内: ローカルエージェントは外部インターネットにポートを開放せず、お使いのPC内部（localhost:127.0.0.1）でのみ通信します。コマンドはお客様の承認に基づいて実行されます。

1. クイックスタート (Quick Start)

PCのターミナル（PowerShell、ターミナル、Bash）を開き、以下の1行コマンドを実行してください：

# 1. グローバルインストールなしで即時実行（推奨）
npx -y xkat-cli@latest up

# 2. またはグローバルインストール後に実行
npm install -g xkat-cli@latest
xkat-cli up

コマンドが実行されると、数秒以内にxkat Webプレイヤーの状態が**[オンライン]**に自動で切り替わります。

ターミナル: PowerShell または Windows Terminal（またはコマンドプロンプト CMD）を開きます。
実行コマンド:
npx -y xkat-cli@latest up
仮想マシン（Ubuntu Lab VM）利用時:
- Windows 10/11 64-bit環境を推奨します。
- タスクマネージャー（Ctrl+Shift+Esc）→ [パフォーマンス] タブで、仮想化: 有効になっていることを確認してください。

実習環境の接続中にエラーが発生した場合は、以下をご確認ください。

1. 'npx' または 'node' コマンドが見つからない場合

Node.js ランタイムがインストールされていない場合に発生します。

Windows: Node.js 公式サイトから LTS版 をインストールするか、PowerShellで以下を実行してください：
winget install OpenJS.NodeJS.LTS
macOS: 公式サイトのインストーラー、または Homebrew でインストールします：
brew install node

Linux (Ubuntu/Debian):

sudo apt update && sudo apt install -y nodejs npm

インストール完了後、ターミナルを一度閉じて再起動してから再度 npx -y xkat-cli@latest up を実行してください。

2. 画面で「接続待機中」が続く、または接続に失敗する場合

ターミナル確認: エージェントを実行したターミナル画面が閉じられていないか確認してください。
ポートの解放と再起動: ポート（38000–38050）が使用中の場合は、以下を実行して再起動してください：
npx -y xkat-cli@latest down npx -y xkat-cli@latest up
セキュリティソフトの確認: セキュリティソフトや社内VPNが 127.0.0.1 への内部通信を遮断していないかご確認ください。

3. 仮想マシン（Ubuntu Lab VM）の作成や起動に失敗する場合

Windows 仮想化機能の確認:
- タスクマネージャーで「仮想化」が無効になっている場合は、PC再起動時にBIOS/UEFI設定で Intel VT-x または AMD SVM を有効化してください。
仮想マシンの完全初期化（Reset）:
- 以下のコマンドでクリーンな状態に再生成できます：
  npx -y xkat-cli@latest lab reset

4. 実習終了後にエージェントを停止したい場合

以下のコマンドを実行すると、バックグラウンドのエージェントが安全に停止します：

npx -y xkat-cli@latest down