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

# クラウド環境セットアップ

> Agent が動作するコンテナ、ネットワーク、依存関係を選択する。

Environment は Session が実行されるコンテナテンプレートを定義します。環境タイプ、ネットワークポリシー、プリインストール依存関係、セットアップスクリプト、metadata を含みます。異なるシナリオに応じて異なる環境を作成できます。厳密に隔離されたセキュリティ監査環境、データサイエンスライブラリをプリインストールした分析環境、またはオープンネットワークの汎用開発環境などです。

## 環境とは

Environment は Session の基盤となるインフラストラクチャレイヤーです：

* **環境タイプ** - `cloud` はクラウドマネージドコンテナ、`self_hosted` はセルフホスト実行環境を示します
* **ネットワークポリシー** - コンテナのアウトバウンドネットワークアクセスを制御します
* **パッケージ** - プリインストールされるシステムパッケージ、Python パッケージ、Node.js パッケージ
* **セットアップスクリプト** - コンテナ準備段階でパッケージインストール後に実行されるユーザースクリプト

Session が起動すると、指定された Environment テンプレートに基づいて隔離されたランタイムが作成されます。

## フィールドリファレンス

| フィールド                 | 型            | 必須  | 説明                                       |
| --------------------- | ------------ | --- | ---------------------------------------- |
| `id`                  | string       | -   | システム生成、`env_` プレフィックス                    |
| `type`                | string       | -   | 固定値 `"environment"`                      |
| `name`                | string       | はい  | 環境名                                      |
| `description`         | string       | いいえ | 自由記述、デフォルトは `""`                         |
| `config`              | object       | はい  | 環境設定                                     |
| `config.type`         | string       | はい  | 環境タイプ：`"cloud"` または `"self_hosted"`      |
| `config.networking`   | object       | いいえ | `cloud` 環境のネットワークポリシー                    |
| `config.packages`     | object       | いいえ | `cloud` 環境のプリインストールパッケージ設定               |
| `config.setup_script` | string       | いいえ | sandbox 準備段階で実行される shell スクリプト（最大 64 KB） |
| `metadata`            | object       | いいえ | カスタム key/value metadata                  |
| `archived_at`         | string\|null | -   | アーカイブ時刻（ISO 8601）、未アーカイブ時は `null`        |
| `created_at`          | string       | -   | 作成時刻                                     |
| `updated_at`          | string       | -   | 最終更新時刻                                   |

## Config タイプ

`config.type` は `"cloud"` または `"self_hosted"` を指定できます。

`self_hosted` の config は以下の形式に厳密に従う必要があります：

```json theme={null}
{"type": "self_hosted"}
```

セルフホスト Environment はマネージドクラウドコンテナを起動しません。外部 worker は [Work API](/ja/cloud-agents/api/environments/work/poll) を使用して、その Environment の Session work をポーリング、確認応答、heartbeat、停止します。

`cloud` の config には `networking`、`packages`、`setup_script` を含めることができます。

## ネットワークポリシー

`config.networking` は 3 つのリクエストモードをサポートします。**すべてのモードでオブジェクト形式を使用する必要があります** — `"unrestricted"` のような文字列省略形は 400 エラーを返します。

| モード   | 値                                                     | 説明                               |
| ----- | ----------------------------------------------------- | -------------------------------- |
| 完全開放  | `{"type": "unrestricted"}`                            | コンテナは任意の外部アドレスにアクセス可能            |
| 制限付き  | `{"type": "limited", "allow_package_managers": true}` | 既知の安全な公開サービスとパッケージマネージャーのみアクセス可能 |
| 許可リスト | `{"type": "allowed_hosts", "allowed_hosts": [...]}`   | 指定されたホストのみアクセス可能                 |

Cloud Environment のレスポンスには以下の networking フィールドが含まれます。省略されたフィールドはデフォルト値で返されます。

| フィールド                    | 型         | デフォルト     |
| ------------------------ | --------- | --------- |
| `type`                   | string    | `limited` |
| `allowed_hosts`          | string 配列 | `[]`      |
| `allow_package_managers` | boolean   | `false`   |
| `allow_mcp_servers`      | boolean   | `false`   |

### 完全開放

```json theme={null}
{
  "config": {
    "type": "cloud",
    "networking": {"type": "unrestricted"}
  }
}
```

依存関係のダウンロードや外部 API 呼び出しが必要な汎用開発タスクに適しています。

### 制限付きモード

```json theme={null}
{
  "config": {
    "type": "cloud",
    "networking": {
      "type": "limited",
      "allow_package_managers": true
    }
  }
}
```

任意のアウトバウンドトラフィックは不要だが、パッケージマネージャーによる依存関係の取得が必要な場合に適しています。

### 許可リストモード

```json theme={null}
{
  "config": {
    "type": "cloud",
    "networking": {
      "type": "allowed_hosts",
      "allowed_hosts": [
        "api.github.com",
        "registry.npmjs.org",
        "pypi.org"
      ]
    }
  }
}
```

セキュリティ要件が高いワークロードで、アクセス可能な外部サービスを正確に制御する必要がある場合に適しています。

## プリインストールパッケージ

`config.packages` でコンテナ起動時にインストールされる依存関係を指定します：

```json theme={null}
{
  "config": {
    "type": "cloud",
    "networking": {"type": "unrestricted"},
    "packages": {
      "apt": ["git", "build-essential", "libssl-dev"],
      "pip": ["pandas", "numpy", "scikit-learn"],
      "npm": ["typescript", "eslint", "prettier"]
    }
  }
}
```

| パッケージマネージャー | フィールド          | 説明                      |
| ----------- | -------------- | ----------------------- |
| apt         | `packages.apt` | Debian/Ubuntu システムパッケージ |
| pip         | `packages.pip` | Python パッケージ            |
| npm         | `packages.npm` | Node.js パッケージ           |

<Note>
  プリインストールパッケージは環境の初期化時間を増加させます。本当に必要なパッケージのみを追加し、残りは Session 内でオンデマンドでインストールしてください。
</Note>

## セットアップスクリプト

`config.setup_script` は sandbox 準備段階で `packages` のインストール完了後に実行される shell スクリプトです。`/bin/bash -lc` インタープリターで実行されます。リポジトリのクローン、設定ファイルの作成、キャッシュのウォームアップなど、`packages` では表現できない初期化ステップに使用します。

| 制約       | 値                                 |
| -------- | --------------------------------- |
| 型        | string                            |
| 最大長      | 64 KB                             |
| インタープリター | `/bin/bash -lc`                   |
| タイムアウト   | 10 分                              |
| 実行タイミング  | sandbox 準備段階、`packages` インストール完了後 |

```bash theme={null}
# プロジェクトをクローンして依存関係キャッシュをウォームアップする環境を作成
curl -s -X POST https://api.qoder.com/api/v1/cloud/environments \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "node-with-init",
    "config": {
      "type": "cloud",
      "networking": {"type": "unrestricted"},
      "packages": {
        "npm": ["pnpm@9"]
      },
      "setup_script": "set -euo pipefail\n[ -d /workspace/.git ] || git clone https://github.com/me/repo /workspace\ncd /workspace && pnpm install --frozen-lockfile"
    }
  }' | jq .
```

実行成功後、sandbox 内に完了マーカーが書き込まれるため、同一 sandbox 内では再実行されません。sandbox が再作成されると再度実行されます。スクリプトがゼロ以外の終了コードで終了すると Session の起動が中断され、エラーレスポンスに exit code と stderr の抜粋が含まれます。

## 環境の作成

```bash theme={null}
# データサイエンス用環境を作成
curl -s -X POST https://api.qoder.com/api/v1/cloud/environments \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "data-science",
    "config": {
      "type": "cloud",
      "networking": {"type": "unrestricted"},
      "packages": {
        "apt": ["build-essential"],
        "pip": ["pandas", "numpy", "matplotlib", "scikit-learn", "jupyter"]
      }
    }
  }' | jq .
```

成功時は **200 OK** が返されます：

```json theme={null}
{
  "id": "env_019e44eb66bb748cabcd1489f6fa4428",
  "type": "environment",
  "name": "data-science",
  "description": "",
  "config": {
    "type": "cloud",
    "networking": {
      "type": "unrestricted",
      "allowed_hosts": [],
      "allow_package_managers": false,
      "allow_mcp_servers": false
    },
    "packages": {
      "type": "packages",
      "apt": ["build-essential"],
      "npm": [],
      "pip": ["pandas", "numpy", "matplotlib", "scikit-learn", "jupyter"]
    }
  },
  "metadata": {},
  "archived_at": null,
  "created_at": "2026-05-18T10:00:00Z",
  "updated_at": "2026-05-18T10:00:00Z"
}
```

## ネットワーク制限環境の作成

```bash theme={null}
# 内部 API のみアクセス可能なセキュア環境を作成
curl -s -X POST https://api.qoder.com/api/v1/cloud/environments \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "secure-internal",
    "config": {
      "type": "cloud",
      "networking": {
        "type": "allowed_hosts",
        "allowed_hosts": ["internal-api.mycompany.com", "git.mycompany.com"]
      },
      "packages": {
        "apt": ["git", "curl"]
      }
    }
  }' | jq .
```

## 環境の取得

```bash theme={null}
# すべての環境を一覧表示
curl -s https://api.qoder.com/api/v1/cloud/environments \
  -H "Authorization: Bearer $QODER_PAT"
```

```bash theme={null}
# 単一の環境を取得
curl -s https://api.qoder.com/api/v1/cloud/environments/env_ds456 \
  -H "Authorization: Bearer $QODER_PAT"
```

## 環境の更新

```bash theme={null}
# 既存の環境に新しい依存関係を追加
curl -s -X POST https://api.qoder.com/api/v1/cloud/environments/env_ds456 \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "data-science",
    "config": {
      "type": "cloud",
      "networking": {"type": "unrestricted"},
      "packages": {
        "apt": ["build-essential", "libpq-dev"],
        "pip": ["pandas", "numpy", "matplotlib", "scikit-learn", "jupyter", "sqlalchemy"]
      }
    }
  }' | jq .
```

<Note>
  環境を更新しても実行中の Session には影響しません。新しい設定は更新後に作成された Session にのみ適用されます。
</Note>

## 環境選定ガイド

| シナリオ      | 推奨設定                                         |
| --------- | -------------------------------------------- |
| 汎用開発      | `default` 環境、追加設定不要                          |
| データ分析     | pandas/numpy をプリインストール、オープンネットワーク            |
| セキュリティ監査  | 許可リストネットワーク、最小限の依存関係                         |
| フロントエンド開発 | Node.js ツールチェーンをプリインストール、npm レジストリへのオープンアクセス |
| CI/CD 統合  | git/docker CLI をプリインストール、許可リストモード            |

## よくある質問

**Q: 環境を作成した後、使用できるまでどのくらい待つ必要がありますか？**

A: 環境は作成後すぐに使用可能です。コンテナの実際のプロビジョニング（依存関係のインストールを含む）は Session の起動時に行われます。

**Q: パッケージのバージョンを固定できますか？**

A: pip と npm パッケージはバージョン指定をサポートしています。例：`"pandas==2.1.0"` や `"typescript@5.0.0"`。apt パッケージはシステムリポジトリのデフォルトバージョンが使用されます。

**Q: ネットワーク設定の誤りで Agent が動作しない場合はどうすればよいですか？**

A: 新しい環境を作成するか（または既存の環境を更新して）、ネットワークポリシーを修正した後、新しい Session を起動してください。

**Q: アカウントごとに作成できる環境の数に上限はありますか？**

A: ハードリミットはありません。実際の必要に応じて作成し、命名規則を使って整理することを推奨します。

## 次のステップ

<CardGroup cols={2}>
  <Card title="Session の開始" icon="play" href="/ja/cloud-agents/sessions">
    Agent と Environment を組み合わせてタスクを実行する。
  </Card>

  <Card title="Agent の定義" icon="user-gear" href="/ja/cloud-agents/define-agent">
    Agent 設定を確認する。
  </Card>
</CardGroup>