---
title: "ランタイムとサンドボックス"
description: "サンドボックスのライフサイクル、注入される環境、トークンの種類、セッションの起動元となるイメージ。"
---

各セッションは独立した隔離環境で実行されます。 このページでは、サンドボックスのライフサイクル、起動時に Beeuni が注入する環境、トークンの種類、サンドボックスイメージについて説明します。セッションの概念については、[Sessions](/docs/ja/work/sessions)を参照してください。

<a id="sandbox-lifecycle"></a>

## サンドボックスのライフサイクル

セッションの行には `status` が含まれます。列挙型には `queued`、`branching`、`provisioning`、`running`、`stopped`、`failed`、`completed` が定義されていますが、Beeuni が設定するのは 4 つだけです。

| ステータス | 設定されるタイミング |
| --- | --- |
| `provisioning` | セッション作成時。Beeuni がセッションブランチを作成し、サンドボックスを要求します。 |
| `running` | サンドボックスが起動し、到達可能になった時点。 |
| `stopped` | 明示的な停止時、または非アクティブなサンドボックスを休止するアイドルスイープ時。 |
| `failed` | プロビジョニングに失敗した場合。 |

`queued`、`branching`、`completed` は列挙型に存在しますが、セッションフローでは使われません。実際に使われる状態として扱わないでください。

サンドボックス自体は、独自の行に別の `status` を持ち、独自の列挙型を使用します。

| ステータス | 設定されるタイミング |
| --- | --- |
| `provisioning` | プロバイダーがサンドボックスを起動したとき。 |
| `active` | プロバイダーがサンドボックスの稼働を確認したとき。 |
| `stopped` | 明示的な停止、アイドル時の自動停止、または再起動の途中。 |
| `error` | プロバイダーが起動または実行時の障害を報告したとき。 |
| `archived` | 終端状態。セッションを削除し、プロバイダーがサンドボックスを一時停止ではなく破棄したとき。 |

Beeuni は、アカウント単位でもプロジェクト単位でも、同時に実行できるセッション数に上限を設けていません。実行中のセッションはコンピューティング料金が発生します。クレジットが不足しているアカウントでは、作成時に `402` になります。

<a id="branch-model"></a>

### ブランチモデル

- セッションブランチの名前にはセッション ID（UUID）が使われます。`BEEUNI_SESSION_ID` と `BEEUNI_BRANCH_NAME` の値は同じです。
- Beeuni はセッション作成時に `base_ref` からブランチを作成します。デフォルトでは、プロジェクトのデフォルトブランチが使われます。
- トリガーは、対話型セッションと同じ方法でセッションブランチを作成します。
- デフォルトブランチに直接書き込む処理はありません。[change request](/docs/ja/work/change-requests) のマージ時にのみ書き込まれます。

<a id="reconcile-a-session-branch"></a>

### セッションブランチを同期する

ベースブランチが変更された場合は、セッションのコマンドパレットから **Ask Agent: Sync Branch & Reload** を使用します。エージェントはセッションブランチを調べ、ローカルの作業を保持したまま、最新の `base_ref` を取得し、競合を解決して、関連するテストを実行した後、同期結果をコミットします。Beeuni が競合のどちらか一方を選んだり、作業ツリーをリセットしたりすることはありません。

エージェントは `beeuni sessions reload "$BEEUNI_SESSION_ID" --project "$BEEUNI_PROJECT_ID" --no-repo --force --yes` で処理を完了します。エージェントがすでにブランチを同期しているため、`--no-repo` が必要です。置き換え後のランタイムが正常になってから、再読み込みによって標準ハーネスランタイムが置き換えられます。現在のターンは終了するため、ランタイムが戻った後に `continue` を送信してください。

セッションヘッダーには、サーバーが確認した再読み込みの各フェーズがリアルタイムで表示されます。Web からの再読み込みでは、セッションを確認し、エージェント設定をコンパイルして、ランタイムの置き換えを適用・検証し、アクティブな設定を確認します。リポジトリは更新しません。CLI では `--no-repo` を渡さない限り、リポジトリを更新できます。

<a id="config-convergence"></a>

### 設定の収束

<a id="where-a-box-gets-the-release"></a>

各セッションはベースブランチの設定を使います。変更をそのブランチにプッシュし、セッションを再読み込みしてください。更新は現在のターン終了まで待機します。Config Releases の独立したフラグはありません。

**Reload config** または `beeuni sessions reload <session id>` を使用します。読み込みに失敗した場合は、エラーの詳細を確認してプロジェクト設定を修正してください。

<a id="workspace-is-where-you-edit-the-base-branch-is-what-runs"></a>

#### `/workspace`は編集する場所、ベースブランチは実行される設定

セッションは常にベースブランチの最新の設定を実行します。セッションごとの設定モードはありません。

`/workspace`は編集可能なチェックアウトです。そこで設定を読み、そこで変更します。変更が実行中のセッションに反映されるのは、**ベースブランチにプッシュされた後**です。その後、通常の convergence によって取り込まれます。`/workspace`にしかない編集は、セッションの動作に影響しません。そのことは実行中のエージェントにも伝えられます。エージェントの指示には、設定の元になったコミットと、`/workspace`がそのコミットより古い可能性があることが記載されます。

リリースのコピーは読み取り専用なので、間違ったコピーを編集すると、何も起きないままになるのではなく、権限エラーになります。

<a id="when-the-configuration-no-longer-declares-a-sessions-agent"></a>

#### 設定からセッションのエージェントが削除された場合

セッションはエージェントを指定して作成されます。後のコミットでそのエージェントが削除または改名された場合、そのセッションの所有者がプロジェクトのデフォルトエージェントを使用できるときに限り、セッションは一度だけそのエージェントに切り替わります。Beeuni は切り替えを監査ログに記録し、実行中のエージェントの指示にも明記するため、セッションで何が起きたかが分かります。

所有者がデフォルトエージェントを使用できない場合、またはプロジェクトにデフォルトが設定されていない場合、セッションにはエージェントもエージェントへのアクセス権も設定されません。それでも起動し、理由が報告されます。エージェントを再度宣言するか、プロジェクトのデフォルトエージェントを設定するか、プロジェクトマネージャーにデフォルトエージェントへのアクセスを依頼してください。

<a id="what-the-session-header-shows"></a>

#### セッションヘッダーの表示内容

| 状態 | 条件 | ヘッダー |
| --- | --- | --- |
| 最新 | 古くなく、フォールバックなし | なし |
| 更新可能 | `stale: true` | 更新バッジと**Reload config** |
| フォールバック | `fallback_reason`が設定済み | 赤いチップ：**設定の読み込みに失敗しました** |

フォールバックで終了した再読み込みは、成功ではなくエラーを報告します。

<a id="reload-config"></a>

#### 設定を再読み込み

**Reload config**と`beeuni sessions reload <session id>`は、1回の操作で2つの処理を行い、それぞれの結果を示します。

1. 実行中のセッションを、ベースブランチの最新のエージェント、スキル、ツールに切り替えます。
2. `/workspace`チェックアウトを fast-forward し、そこで読むファイルをセッションで実行される設定と一致させます。

チェックアウトの pull は、セッション専用ブランチ上で fast-forward のみ行われるため、内容が失われることはありません。スキップするには、CLI で`--no-repo`を指定します。`base_ref`のコードをセッションブランチに取り込むには、**エージェントに同期を依頼**を使用してください。

<a id="turning-it-off"></a>

#### 無効にする

<a id="injected-environment"></a>

## 注入される環境変数

Beeuni は起動時にこれらの変数を注入します。`runtime`配信用に明示的に設定されたプロジェクトシークレットのみがサンドボックスに入ります。コネクターとモデルプロバイダーの認証情報は Beeuni サーバー上に保持されます。

| 変数 | 説明 |
| --- | --- |
| `BEEUNI_PROJECT_ID` | このプロジェクトの UUID。 |
| `BEEUNI_SESSION_ID` | このセッションの UUID。ブランチ名も兼ねます。 |
| `BEEUNI_BRANCH_NAME` | `BEEUNI_SESSION_ID`と同じ値。 |
| `BEEUNI_REPO_URL` | プロジェクトのリポジトリのクローン URL。 |
| `BEEUNI_DEFAULT_BRANCH` | プロジェクトのデフォルトブランチ。 |
| `BEEUNI_BASE_REF` | このセッションの分岐元の ref。 |
| `BEEUNI_API_URL` | プラットフォーム API のベース URL（`.../v1`）。 |
| `BEEUNI_AGENT_NAME` | セッションの作成に使用されたエージェント。 |
| `BEEUNI_MODEL` | 設定されている場合に実行するモデル。`BEEUNI_OPENCODE_MODEL`には、この名前が存在する前にビルドされたデーモン向けに同じ値が設定されます。 |
| `BEEUNI_LLM_BASE_URL` | Beeuni LLM ゲートウェイのベース URL。ゲートウェイはプロバイダーの認証情報をサーバー側で解決します。 |
| `BEEUNI_TOKEN` | セッションに紐づく Beeuni 認証情報。下記を参照してください。 |

Beeuni は`BEEUNI_WORKSPACE`を注入しません。イメージには`/workspace`が組み込まれており、セッションごとにこれを設定する手順はありません。また、Beeuni は git トークンも注入しません。デーモンは必要に応じて、有効期間の短いクローン用認証情報を取得します。[セッションからのプッシュ](#pushing-from-a-session)を参照してください。Beeuni は、`BEEUNI_*`プレフィックスで始まるユーザーシークレットを拒否します。このプレフィックスはプラットフォーム変数用に予約されています。

<a id="session-credential"></a>

## セッション認証情報

Beeuni には、自分で作成する外部トークンと、各サンドボックス内の認証情報が1つあります。

<a id="external-tokens"></a>

### 外部トークン

個人アクセストークン（PAT。プレフィックスは`beeuni_pat_`）またはサービスアカウント（プレフィックスは`beeuni_sa_`）は、サンドボックスの外部から Beeuni API、SDK、CLI を呼び出す際の認証に使用します。PAT のスコープ、サービスアカウントの設定方法、使い分けについては「認証」を参照してください。

<a id="in-sandbox-token"></a>

### サンドボックス内トークン

`BEEUNI_TOKEN`は、Beeuni がセッション環境を起動するときに発行されます。起動したユーザー、プロジェクト、セッション、エージェントの権限に紐づきます。 各 API ルートでは、それぞれ独自の権限チェックが行われます。

最初のプロンプトとターン台帳の識別子は、環境変数ではありません。起動後、デーモンが`BEEUNI_TOKEN`を使って API から取得します。

<a id="pushing-from-a-session"></a>

## セッションからのプッシュ

上流の Git トークンはサンドボックスに入りません。`git push origin HEAD`はコミットをセッションブランチに送信します。デフォルトブランチに反映するには、[変更リクエスト](/docs/ja/work/change-requests)をマージする必要があります。

<a id="the-sandbox-image"></a>

## サンドボックスイメージ

Dockerfile で基本環境を定義します。Beeuni はセッション用のツールとダッシュボードへの接続を提供します。

<a id="declare-a-template"></a>

### テンプレートを宣言する

`beeuni.yaml`内の`sandbox.templates`で、Dockerfile を名前付きテンプレートとして参照します。

```yaml
sandbox:
  templates:
    - slug: dev
      name: Dev box
      dockerfile: Dockerfile.dev
  default: dev
```

各エントリには`dockerfile`または`image`のどちらか一方だけを設定してください。Dockerfile のパスはリポジトリ内に収める必要があります。セッションで使用するテンプレートのスラッグを`default`に設定してください。省略すると、プラットフォームのデフォルトイメージが使われます。`beeuni.toml`上の古いプロジェクトも同じフィールドを使用します。詳細は[レガシー`beeuni.toml`](/docs/ja/project/legacy-toml)を参照してください。フィールドの一覧は[マニフェストのリファレンス](/docs/ja/project/manifest)を参照してください。

<a id="constraints"></a>

### 制約

| ルール | 理由 |
| --- | --- |
| `ENTRYPOINT`または`CMD`を設定しないでください。 | Beeuni はデーモンを起動するため、両方を上書きします。 |
| ポート`8000`を使用しないでください。 | デーモンのリバースプロキシ用に予約されています。開発サーバーには別のポートを使用してください。 |
| Debian または Ubuntu ベースを`FROM`してください。 | ランタイムレイヤーは`apt-get`を実行します。Alpine、Fedora、Arch ではビルドに失敗します。 |
| `rm -rf /var/lib/apt/lists/*`なしで`apt-get clean`を実行しないでください。 | ランタイムレイヤーは`apt-get update`を再実行します。キャッシュが壊れているとビルドに失敗します。 |
| 認証情報をイメージに組み込まないでください。 | 名前を`env:`で宣言し、値をプロジェクトのシークレットとして設定してください。Beeuni はセッション開始時に値を注入します。 |

<a id="hardware-spec"></a>

### ハードウェア仕様

テンプレートエントリの`cpu`、`memory`、`disk`でサンドボックスのサイズを設定します。いずれも省略可能です。省略したフィールドには、プラットフォームのデフォルトである 2 vCPU、4 GiB メモリ、20 GiB ディスクが適用されます。

```yaml
sandbox:
  templates:
    - slug: big
      image: ubuntu:24.04
      cpu: 4
      memory: 8
      disk: 50
```

`cpu`は 1～32 コア、`memory`は 1～128 GiB、`disk`は 1～500 GiB を指定できます。これらの上限を超える値は、上限値まで切り下げられます。Beeuni は GPU をサポートしていません。テンプレートに`gpu`キーがあると、エラーではなく警告が表示されます。

仕様はテンプレートのスナップショットに含まれ、セッションごとの設定ではありません。変更するとスナップショットが再構築され、次のセッションから適用されます。現在のセッションには、すでに起動済みの仕様が適用されます。

<a id="docker-in-the-sandbox"></a>

### サンドボックス内の Docker

テンプレートで`container_runtime: true`を設定すると、サンドボックス内で Docker を実行できます。ブリッジネットワークとユーザー定義ネットワーク、`overlayfs`ストレージドライバー、NAT による外向き通信が利用できます。`supabase start`や`docker compose`などのローカルスタックも、ノート PC 上と同じように動作します。

```yaml
sandbox:
  templates:
    - slug: dev
      dockerfile: .beeuni/Dockerfile.dev
      container_runtime: true
```

<a id="ports-and-preview-urls"></a>

### ポートとプレビュー URL

デーモンはポート`8000`をリッスンし、サンドボックス内でアプリが使用するその他のポートにプロキシします。プロキシでブロックされるのはポート`8000`自体だけです。

ダッシュボードからサンドボックスのポートにアクセスする方法は 2 つあります。

- **パスベース**: `https://<api-host>/v1/p/<sandbox-id>/<port>/...`。これはデフォルトの形式で、WebSocket アップグレードをサポートする唯一の形式です。
- **サブドメインベース**: `https://p<port>-<sandbox-id>.<api-host>/...`。Next.js や Vite の開発サーバーなど、ルート相対パスや Cookie を必要とするアプリには、この形式を使用してください。この形式では、現在 WebSocket アップグレードは動作しません。

プレビュープロキシは`X-Frame-Options`と、あらゆる`frame-ancestors`ポリシーを削除します。そのため、セッションでは特別な設定なしでアプリのプレビューを iframe に埋め込めます。

セッションのプレビューは、閲覧のみまたは操作可能なモードで、公開リンクから共有することもできます。公開共有リンクでは、ポート`22`、`4096`、`8000`と静的ファイル共有用ポートがブロックされます。

<a id="snapshot-rebuilds"></a>

### スナップショットの再構築

イメージや環境設定を変更すると、後続のセッション用に環境が再構築されます。設定に変更がなければ、既存のイメージを再利用します。再構築が必要な最初のセッションには「イメージを準備中」と表示され、以降のセッションではそのビルドを再利用します。

セッション内で Dockerfile を編集した場合、変更が反映されるのは現在のセッションではなく、次のセッションです。変更リクエストがマージされて初めて、変更は`main`に反映されます。詳細は[変更リクエスト](/docs/ja/work/change-requests)を参照してください。