> ## Documentation Index
> Fetch the complete documentation index at: https://cogno.studio/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# リモートサーバーに接続する

> Cognoデスクトップアプリの 設定 → マシン一覧 から、sshで開発サーバーをセットアップ・接続します。

リモートサーバーは、あなた自身のコンピューターと同じようにエージェントの作業を実行します。Cognoデスクトップアプリの **設定 → マシン一覧** から一度セットアップすれば、以降はアカウントにサインインしている他のコンピューターと同じように **あなたのマシン** に並びます。

Cognoは、デスクトップアプリが動いているコンピューターからsshでサーバーに接続します。sshの鍵・`known_hosts`・`~/.ssh/config` は今までどおりあなたのものが使われます。Cognoが鍵を管理することはありません。

## はじめる前に

* あなたのコンピューターから `ssh <接続先>` がパスワード入力なしで通ることを確認します。
* sshのユーザー名を含めます。例: `deploy@build-01`
* macOSサーバーでは **システム設定 → 一般 → 共有 → リモートログイン** をONにします。

対応しているサーバーはLinuxとmacOSです。

## 新しいサーバーをセットアップする

**設定 → マシン一覧** の下部にある **サーバーを追加 → SSHでセットアップ** を使います。ssh接続先を入れるだけで、サーバーが登録済み・接続済みのマシンになります。

**1. サーバーを入力する**

**新しいサーバーの ssh 接続先** に普段使っている接続先(例: `deploy@build-01`)を入力し、**エンジンを選ぶ** で **Claude Code** か **Codex** を選びます。

**2. サーバーをセットアップ**

**サーバーをセットアップ** を選びます。進捗はステップごとに表示されます: **サーバーを確認** → **Cogno CLI をインストール** → **マシン情報を取得** → **認証情報を発行** → **デーモンを登録** → **接続**。

**3. 完了**

セットアップが終わると、サーバーは接続済みの状態で **あなたのマシン** に表示され、すぐに作業を実行できます。

sshがそのサーバーに初めて接続する場合は **このサーバーを信頼しますか？** とホスト鍵フィンガープリントが表示されます。サーバーの管理者から伝えられたフィンガープリントと一致する場合のみ接続してください。

セットアップが止まった場合は、原因が「次にやること」として表示されます — 例えば **サーバーにあなたの ssh 鍵が登録されていません** や **この手順には管理者権限が要ります** など — そして「〈ステップ〉で止まりました」の状態で待機します。原因を解消してもう一度 **サーバーをセットアップ** を押すと安全に再開します。アプリ内の別の画面に移動しても進捗は保持されます。

> [!NOTE]
>
> コーディングエンジンの導入はサーバー登録とは別の処理です。エンジンのインストールに失敗しても、サーバー自体のセットアップと接続は完了します。

## サーバー上でセットアップする

**設定 → マシン一覧 → サーバーを追加 → サーバー上でセットアップ** を開きます。WebとDesktopのどちらからも登録手順を確認できます。サーバーのターミナルや、承認済みの管理ツールで実行してください。

**1. サーバーで実行する**

**CLIのインストール手順** からCogno CLIを導入します。コーディングエージェントを選択し、表示されたコマンドをサーバーのOSアカウントで実行します。

```bash theme={"system"}
cogno server install --engine claude
```

**2. 登録を承認する**

**登録コードを入力** を選び、サーバーに表示されたコードを入力します。ホスト名、OSアカウント、Workspaceを確認して **このマシンを承認** を選びます。ホスト名とOSアカウントはサーバーの自己申告です。承認したアカウントのマシンとして登録されます。

**3. 準備を確認する**

**マシン一覧を開く** を選び、サービスの起動と実行準備を確認します。Projectの実行設定から、このマシン上の作業フォルダを設定します。

> [!NOTE]
>
> 登録の承認後も、サービスの起動、エージェントの認証、Projectの準備が必要な場合があります。SSHなしの遠隔操作には、対象WorkspaceでのRelayの有効化と必要な外向き通信の許可が必要です。有効化はCogno運用者が行います。

**ネットワーク要件** で、Cogno API、CLI・Engineの配布先、コーディングエージェントへのHTTPS通信と、RelayへのWebSocket通信が必要なことを確認できます。

## 踏み台・SSM・IAP経由のSSH

**SSHでセットアップ** の **踏み台・SSM・IAP経由の接続** を開きます。`~/.ssh/config`の`ProxyJump`や`ProxyCommand`を設定し、そのエイリアスを接続先に入力します。SSHと転送の許可が必要です。クラウドの認証はセットアップ前に済ませてください。

## 登録済みのサーバーに接続する

すでに登録されているサーバー(以前あなたが登録したもの、または同じアカウントの別のコンピューターから登録されたもの)には、**あなたのマシン** の行から接続します。

**1. マシンを見つける**

**設定 → マシン一覧** を開き、**あなたのマシン** からサーバーを探します。

**2. ssh接続先を入力する**

行の入力欄に接続先を入れます(`user@host または ssh エイリアス`)。お使いの ssh でそのまま接続します — 鍵・config のエイリアス・known hosts が適用されます。

**3. 接続**

**接続** を選びます。サーバーに到達すると行に **トンネル接続中 · 〈接続先〉** と表示されます。

接続が切れると行に **トンネルが切断 — 再接続中…** と表示され、接続が戻るか **切断** を選ぶまでCognoが再試行します。

デスクトップアプリを起動し直すと、前回接続していたサーバーには自動で再接続します。自分で **切断** したサーバーは、もう一度接続するまで自動再接続の対象になりません。

## 1台のサーバーを複数人で使う

マシンは「1つのホストの1つの OS アカウント」です。複数人で同じサーバーを使う場合は、それぞれが自分の OS アカウントとssh接続先でセットアップし、アカウントごとに別のマシンとして表示されます。同じ名前のマシンが並ぶときは、行に OS アカウントも表示されるので見分けられます。

## Remote Engine の更新を管理する

Desktop または `cogno server install` で新しくセットアップしたサーバーは、Engine の自動更新が有効になります。サーバー自身が、そのチャネルの署名済み最新リリースを取得します。Desktop を閉じている間も更新を確認し、実行中のエージェントの作業とバックグラウンドタスクが終わってから再起動します。更新後の動作確認に失敗した場合は、前の版に戻します。

Web・Desktop の **設定 → マシン一覧** で、サーバーの **Engine の自動更新** を切り替えられます。オフにするとインストール済みの版を保持します。ssh で接続したときもこの設定が適用されます。既存サーバーの更新方針は、設定を変更するまで保持します。古いサーバーでは、CLI を更新してから一度 `cogno server update --latest` を実行し、この設定に対応したランタイムを導入します。

サーバー管理者は、サーバー上でも同じ設定を操作できます。

```bash theme={"system"}
# 自動更新をオフにし、Web・Desktop からの変更を禁止する。
cogno server updates --automatic=false --lock

# 自動更新をオンにし、マシン所有者からの変更を許可する。
cogno server updates --automatic=true --lock=false

# ローカルの設定を確認する。
cogno server updates

# 署名済みの最新 Engine に手動で更新する。
cogno server update --latest
```

新規サーバーで手動更新を選ぶ場合は、`cogno server install --automatic-updates=false` でインストールします。本番は本番の安定版、stg は独立した stg のリリースチャネルを使用します。

## サーバーが待ち受けているポートを開く

リモートマシンで起動した開発サーバーは、そのマシンの `localhost` で待ち受けます。手元の `localhost` ではないので、出力に出た `http://localhost:5173` をそのままブラウザで開いても届きません。タスクのターミナルの隣にある **ポート** タブが、Cogno がすでに張っている接続の上で転送し、開きます。

このタブは別のマシンで動いているタスクにだけ出ます。この PC で動く作業はもともと `localhost` で応答するので、転送するものがありません。

**1. ポートタブを開く**

タスクのターミナル欄で **ポート** を選びます。Cogno がマシンに待ち受けの状況を聞き、**ポート**、**転送先アドレス**、**プロセス** の列で並べます。

**2. ポートを開く**

行を選ぶと転送を張り、ブラウザで開きます。**転送先アドレス** にはこの PC 側のアドレスが出ます。通常は同じ番号なので、サーバーの `http://localhost:5173` はこちらでも `http://localhost:5173` です。

**3. あとから使う**

転送済みの行にカーソルを合わせると **アドレスをコピー**、**ブラウザで開く**、**転送をやめる** が出ます。**ポート** タブの数字は転送中の本数です。

**ポートを取り直す** を選ぶともう一度マシンに聞きます。タブを開いたあとに起動したサーバーはそこで出ます。自動で転送されるものはありません。

### 一覧に出ないポート

一覧に並ぶのは、マシンが 1024 番より上で待ち受けていると報告したものです。それ以外は **ポートを追加** から開きます。1024 番未満のもの、公開ポート経由で届くコンテナのようにマシンが待ち受けとして報告しないものが対象です。欄の表示どおり、番号でもアドレス付きでも受け付けます: `5173 または 10.0.0.4:5173`。

こうして足した行も他の行と同じで、転送をやめるか、そのマシンとの接続が切れるまで残ります。

> [!NOTE]
>
> **プロセス** はマシンがそのソケットについて返した名前です。Linux では自分のアカウントのプロセスしか名前を返さないので、空欄はよく起きます。
>
> 同じ番号がこの PC ですでに使われている場合は別の番号に転送し、**転送先アドレス** にどれになったかが出ます。転送は macOS と Linux から使えます。Windows ではその旨が表示されます。

## マシンの Engine ログを収集する

**あなたのマシン** に並ぶマシンでは Cogno Engine（Cogno にチェックインし、エージェントの作業を実行するバックグラウンドサービス）が動いています。マシンの様子がおかしいときは、そのマシンにサインインしなくても、自分のコンピューターから Engine のログを読めます。一覧にあるマシンなら、このコンピューター・リモートサーバー・ヘッドレスなインストールのどれでも、チェックインしている限り使えます。

**1. マシンのログを開く**

**あなたのマシン** で行の **Engine のログ** ボタンを選びます。パネルに最終収集の日時、または **まだログはありません** と表示されます。

**2. ログを収集する**

**ログを収集** を選びます。パネルに **〜にリクエスト · マシンの次回チェックインを待っています（通常 1 分以内）** と表示されます。マシンは次回のチェックイン時に Engine のログファイルの末尾を送ります。このコンピューターの場合は数秒で応答します。

**3. ログを読む**

収集ごとに **〜に収集 · Engine バージョン 〈バージョン〉** の行が並び、含まれるファイルとサイズが表示されます。行を開くとテキストを読めます。**コピー** でサポートへの連絡などに貼り付けられます。

チェックインしていないマシンは応答できません。パネルには **このマシンはチェックインしていません。復帰時に応答します** と表示され、そのマシンの Engine が再び動き出すまでリクエストは保持されます。

> [!NOTE]
>
> マシンが送るのはログの末尾です — `engine.log` は最大 512 KiB、`pty-host.log` は最大 128 KiB。行にはファイル全体のうちどれだけが含まれるかが表示されます（例: **engine.log · 全 9.3 MiB のうち末尾 512 KiB**）。マシンごとに直近 5 回分の収集が保持されます。マシンの所有者のアカウントだけがログをリクエスト・閲覧できます。

## サーバーの利用をやめる

**あなたのマシン** で行の **削除** ボタンを選びます。認証情報が失効し、次の通信が拒否された時点で作業の実行を停止します。そのコンピューターで再度サインインするか、サーバーをセットアップし直すと元に戻せます。

## Relay経由で作業フォルダを設定する

WorkspaceでRelayが有効になっている場合は、**設定 → あなたのマシン**で
サーバーの**作業フォルダを設定**を選びます。Projectを選択し、`/srv/project`
などの絶対パスを入力してください。Cognoがディレクトリを確認して登録します。
設定済みのフォルダがある場合は、置き換える前に画面に表示します。待機中の
サーバーへの接続には最大45秒かかることがあります。

自分の実行環境を管理する権限と、あなたのアカウントにサインインして稼働中の
サーバーが必要です。設定権限の有効期限は2分で、選択したProjectとディレクトリに
限定されます。設定が完了すると接続を閉じます。

Desktopで**TaskにRelayを使う**を選ぶと、このウィンドウでそのサーバーへの
Task通信にRelayを使用し、SSHトンネルを閉じます。**TaskにSSHを使う**を選ぶと
SSH経由に戻ります。**接続**でトンネルを開いてください。選択した方式は設定を
示し、実際の接続権限はTaskを開いたときに確認します。

サーバーからCogno Coreと設定済みRelayへのHTTPS・WebSocket通信をポート443で
許可してください。組織の方針に合わせ、プロキシと信頼する証明書も設定します。
[エンタープライズのリモートサーバー運用](/docs/ja/enterprise-remote-execution.md)を参照してください。

## トラブルシューティング

セットアップの失敗は「次にやること」としてアプリに表示されます。主なもの:

| アプリの表示 | 対処 |
| - | - |
| **サーバーにあなたの ssh 鍵が登録されていません** | `ssh-copy-id` で追加するか、サーバー側の該当アカウントの `~/.ssh/authorized_keys` に公開鍵を追記します。 |
| **そのホスト名が解決できません** | 綴りを確認します。自分のネットワーク上のMacなら、たいてい `.local` を付ける必要があります。 |
| **接続先にユーザー名が要ります** | `user@host` の形で書きます。例: `ubuntu@192.168.1.9` |
| **サーバーが ssh を受け付けていません** | Macなら **システム設定 → 一般 → 共有 → リモートログイン** をONに。Linuxならsshサーバーを起動します。 |
| **サーバーから応答がありません** | マシンがスリープしているか、別のネットワークにあるか、ファイアウォールが22番ポートを落としている可能性があります。 |
| **このホストは Cogno が記憶しているマシンと違います** | ホスト鍵が変わっています。心当たりがあれば `ssh-keygen -R` で古い記録を消してからセットアップし直します。心当たりがなければ接続しないでください。 |
| **この Mac は画面にサインインしていません** | 自動ログインをONにして一度サインインするか、sshで入って端末から `cogno server install` を実行します(ログイン不要のboot serviceを登録します)。 |
| **この手順には管理者権限が要ります** | マシンの端末で `cogno server install` を実行するか、そのアカウントにパスワード不要のsudoを許可します。 |
| **セットアップが root で実行されました** | サーバーが作業するアカウントで実行し直します。権限が必要な手順だけはセットアップが自分で昇格します。 |
| **macOS が Cogno のローカルネットワーク接続を止めています** | **システム設定 → プライバシーとセキュリティ → ローカルネットワーク** でCognoをONにしてから、もう一度セットアップします。 |
| **このサーバーの Cogno CLI が古いです** | サーバー側のCLIを更新してから、もう一度セットアップします。 |

より一般的な症状:

| 症状 | 対処 |
| - | - |
| セットアップカードや接続の操作が見当たらない | Cognoをデスクトップアプリで開きます。ブラウザーからはローカルのsshを使えません。 |
| サーバーでプロジェクトの作業が始まらない | プロジェクトのフォルダーを **プロジェクト設定** で設定します。[プロジェクトを設定する](/docs/ja/projects.md)を参照してください。 |

## 関連ドキュメント

* [エンタープライズのリモートサーバー運用](/docs/ja/enterprise-remote-execution.md)
* [プロジェクトを設定する](/docs/ja/projects.md)
* [タスクでエージェントを実行する](/docs/ja/agents.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.