blaxel

Blaxel スキルリファレンス

Blaxel とは

Blaxel（https://blaxel.ai）は、AI エージェントに専用のコンピューティング環境を提供するクラウドプラットフォームです。主力製品は永続的なサンドボックスです。スタンバイ状態から 25ms 未満で再開する、即座に起動するマイクロ VM で、数秒間操作がないとゼロまでスケールします。

Blaxel は主に次の用途に使用します。

• サンドボックスを起動し、依存関係をインストールして開発サーバーを実行し、ライブプレビュー URL を公開する
• サンドボックスのテンプレート（カスタム Docker イメージ）をビルドしてデプロイし、再利用可能な環境を作成する
• AI エージェント、MCP サーバー、バッチジョブをサーバーレスエンドポイントとしてデプロイする

SDK：TypeScript（@blaxel/core）と Python（blaxel） CLI：bl（https://docs.blaxel.ai/cli-reference/introduction からインストール） ドキュメント：https://docs.blaxel.ai

認証

SDK は、次の認証情報を優先順位順に使用します。

1. ログイン済みの場合は Blaxel CLI
2. .env ファイル内の環境変数（BL_WORKSPACE、BL_API_KEY）
3. システム環境変数
4. Blaxel 設定ファイル（~/.blaxel/config.yaml）

ローカルでログインします（開発時に推奨）。

bl login YOUR-WORKSPACE

または、環境変数を設定します（リモート／CI 環境の場合）。

export BL_WORKSPACE=your-workspace
export BL_API_KEY=your-api-key

Blaxel 自体で実行する場合、認証は自動的に行われます。

サンドボックスのワークフロー（主な用途）

最も一般的なワークフローは、サンドボックスを作成し、その中でコマンドを実行して、プレビュー URL を取得することです。

ステップ 1：サンドボックスを作成する

Blaxel Hub（https://github.com/blaxel-ai/sandbox/tree/main/hub）の公開イメージを使用します。

• blaxel/base-image:latest — 最小構成の Linux
• blaxel/node:latest — Node.js
• blaxel/nextjs:latest — Next.js
• blaxel/vite:latest — Vite
• blaxel/expo:latest — Expo（React Native）
• blaxel/py-app:latest — Python

または、自分でデプロイしたカスタムテンプレートイメージを使用します。

作成時に必要なポートを指定してください。作成後にポートを追加することはできません。ポート 80、443、8080 は予約済みです。

import { SandboxInstance } from "@blaxel/core";

const sandbox = await SandboxInstance.createIfNotExists({
  name: "my-sandbox",
  image: "blaxel/base-image:latest",
  memory: 4096,
  ports: [{ target: 3000, protocol: "HTTP" }],
});

from blaxel.core import SandboxInstance

sandbox = await SandboxInstance.create_if_not_exists({
  "name": "my-sandbox",
  "image": "blaxel/base-image:latest",
  "memory": 4096,
  "ports": [{"target": 3000, "protocol": "HTTP"}],
})

createIfNotExists／create_if_not_exists を使用すると、名前で既存のサンドボックスを再利用するか、新しいサンドボックスを作成できます。

ステップ 2：ファイルを書き込み、コマンドを実行する

// Write files
await sandbox.fs.write("/app/package.json", JSON.stringify({
  name: "my-app",
  scripts: { dev: "astro dev --host 0.0.0.0 --port 3000" },
  dependencies: { "astro": "latest" }
}));

// Or write multiple files at once
await sandbox.fs.writeTree([
  { path: "src/pages/index.astro", content: "<h1>Hello</h1>" },
  { path: "astro.config.mjs", content: "import { defineConfig } from 'astro/config';\nexport default defineConfig({});" },
], "/app");

// Execute a command and wait for it to finish
const install = await sandbox.process.exec({
  name: "install",
  command: "npm install",
  workingDir: "/app",
  waitForCompletion: true,
  timeout: 60000,
});

// Start a long-running dev server (don't wait for completion)
const devServer = await sandbox.process.exec({
  name: "dev-server",
  command: "npm run dev",
  workingDir: "/app",
  waitForPorts: [3000],  // returns once port 3000 is open
});

await sandbox.fs.write("/app/package.json", '{"name":"my-app","scripts":{"dev":"astro dev --host 0.0.0.0 --port 3000"},"dependencies":{"astro":"latest"}}')

await sandbox.fs.write_tree([
  {"path": "src/pages/index.astro", "content": "<h1>Hello</h1>"},
  {"path": "astro.config.mjs", "content": "import { defineConfig } from 'astro/config';\nexport default defineConfig({});"},
], "/app")

install = await sandbox.process.exec({
  "name": "install",
  "command": "npm install",
  "working_dir": "/app",
  "wait_for_completion": True,
  "timeout": 60000,
})

dev_server = await sandbox.process.exec({
  "name": "dev-server",
  "command": "npm run dev",
  "working_dir": "/app",
  "wait_for_ports": [3000],
})

重要：プレビュー URL からアクセスできるように、開発サーバーは localhost ではなく 0.0.0.0 にバインドする必要があります。--host 0.0.0.0 または HOST 環境変数を使用してください。

ステップ 3：プレビュー URL を作成する

const preview = await sandbox.previews.createIfNotExists({
  metadata: { name: "app-preview" },
  spec: { port: 3000, public: true },
});
const url = preview.spec?.url;
// url => https://xxxx.us-pdx-1.preview.bl.run

preview = await sandbox.previews.create_if_not_exists({
  "metadata": {"name": "app-preview"},
  "spec": {"port": 3000, "public": True},
})
url = preview.spec.url

プレビューを非公開にするには、public: false を設定してトークンを作成します。

const preview = await sandbox.previews.createIfNotExists({
  metadata: { name: "private-preview" },
  spec: { port: 3000, public: false },
});
const token = await preview.tokens.create(new Date(Date.now() + 10 * 60 * 1000));
// Access: preview.spec?.url + "?bl_preview_token=" + token.value

ステップ 4：サンドボックスを管理する

// Reconnect to an existing sandbox
const sandbox = await SandboxInstance.get("my-sandbox");

// List files
const { subdirectories, files } = await sandbox.fs.ls("/app");

// Read a file
const content = await sandbox.fs.read("/app/src/pages/index.astro");

// Get process info / logs
const proc = await sandbox.process.get("dev-server");
const logs = proc.logs; // available if waitForCompletion was true

// Kill a process
await sandbox.process.kill("dev-server");

// Delete the sandbox (all data is erased)
await sandbox.delete();

sandbox = await SandboxInstance.get("my-sandbox")

result = await sandbox.fs.ls("/app")
content = await sandbox.fs.read("/app/src/pages/index.astro")

proc = await sandbox.process.get("dev-server")
# proc.logs available if wait_for_completion was True
await sandbox.process.kill("dev-server")
await sandbox.delete()

サンドボックスのテンプレート（カスタムイメージ）

再利用可能な環境（依存関係をすべて事前インストールした Astro プロジェクトなど）が必要な場合は、テンプレートを作成します。

bl new sandbox my-astro-template
cd my-astro-template

これにより、blaxel.toml、Dockerfile、entrypoint.sh、Makefile が作成されます。

Dockerfile をカスタマイズします。必ず sandbox-api バイナリを含めてください。

FROM node:22-alpine
WORKDIR /app
COPY --from=ghcr.io/blaxel-ai/sandbox:latest /sandbox-api /usr/local/bin/sandbox-api
RUN npm install -g astro
COPY entrypoint.sh /entrypoint.sh
RUN chmod +x /entrypoint.sh
ENTRYPOINT ["/entrypoint.sh"]

entrypoint.sh では sandbox-api を起動する必要があります。

#!/bin/sh
/usr/local/bin/sandbox-api &
while ! nc -z 127.0.0.1 8080; do sleep 0.1; done
echo "Sandbox API ready"
# Optionally start a process via the sandbox API:
# curl http://127.0.0.1:8080/process -X POST -d '{"workingDir":"/app","command":"npm run dev","waitForCompletion":false}' -H "Content-Type: application/json"
wait

テンプレートをデプロイします。

bl deploy

次に IMAGE_ID を取得し、それを使用してサンドボックスを作成します。

bl get sandboxes my-astro-template -ojson | jq -r '.[0].spec.runtime.image'

const sandbox = await SandboxInstance.createIfNotExists({
  name: "project-sandbox",
  image: "IMAGE_ID",
  memory: 4096,
  ports: [{ target: 3000, protocol: "HTTP" }],
});

チュートリアルと例

サンドボックス

Astro：https://docs.blaxel.ai/Tutorials/Astro Expo：https://docs.blaxel.ai/Tutorials/Expo Next.js：https://docs.blaxel.ai/Tutorials/Nextjs

エージェント

概要：https://docs.blaxel.ai/Tutorials/Agents-Overview

CLI の基本コマンド

確認などの入力を求められることがある CLI コマンドを、非対話型／TTY なしの環境（スクリプト、CI、エージェントなど）で実行する場合は、-y を追加して自動的に確認してください。

コマンド	用途
bl login	ワークスペースに認証します
bl new sandbox|agent|job|mcp NAME	テンプレートから新しいリソースを初期化します
bl deploy	リソースをビルドして Blaxel にデプロイします
bl deploy -d DIR	指定したディレクトリからデプロイします
bl serve	テスト用にリソースをローカルで実行します
bl serve --hotreload	ホットリロードを有効にしてローカルで実行します
bl get sandboxes|agents|jobs|functions	リソースを一覧表示します
bl get sandbox NAME --watch	サンドボックスのデプロイ状況を監視します
bl delete sandbox|agent|job|function NAME	リソースを削除します
bl connect sandbox NAME	サンドボックス内で対話型ターミナルを開きます
bl chat AGENT-NAME	デプロイ済みエージェントと対話型チャットを行います
bl run job NAME --data JSON	デプロイ済みのバッチジョブを実行します

blaxel.toml の構造

name = "my-resource"
type = "sandbox"  # sandbox, agent, function, job, volume-template

[env]
NODE_ENV = "development"  # NOT for secrets — use Variables-and-secrets

[runtime]
memory = 4096       # MB
generation = "mk3"
# timeout = 900     # seconds (agents max 900, jobs max 86400)

# Ports (sandbox only)
[[runtime.ports]]
name = "dev-server"
target = 3000
protocol = "tcp"

特に注意すべき点

• ポートはサンドボックスの作成時に宣言する必要があります。後から追加することはできません
• ポート 80、443、8080 は Blaxel によって予約されています
• プレビュー URL を機能させるには、開発サーバーを localhost ではなく 0.0.0.0 にバインドする必要があります
• サンドボックスのメモリの約 50% はメモリ内ファイルシステム（tmpfs）用に予約されています。追加のストレージにはボリュームを使用してください
• サンドボックスは約 5 秒間操作がないと、自動的にゼロまでスケールします。状態はスタンバイ中も保持され、25 ミリ秒未満で再開します
• waitForCompletion の最大タイムアウトは 60 秒です。それより長いプロセスには、maxWait を指定して process.wait() を使用してください
• シークレットを [env] に記述しないでください。Console の Variables-and-secrets ページを使用してください

Agent Drive（共有ファイルシステム）

Agent Drive は SeaweedFS を基盤とする分散ファイルシステムで、すでに稼働中の場合も含め、いつでも複数のサンドボックスやエージェントにマウントできます。サンドボックスの作成時にのみ接続できるブロックストレージであるボリュームとは異なり、ドライブは複数のサンドボックスからの同時読み書きをサポートし、動的に接続／切断できます。

この機能は現在、プライベートプレビュー中です。プレビュー期間中、Agent Drive は us-was-1 リージョンでのみ利用できます。ドライブとサンドボックスの両方をこのリージョンに配置する必要があります。

使用例：

• 中間サービスを介さずにサンドボックス間でデータを受け渡す
• 他のエージェント向けにツールの出力やコンテキスト履歴を保存する
• 複数のエージェント間でデータセットを共有する
• パッケージ依存関係用の共有ファイルシステムキャッシュを作成する

ドライブを作成する

import { DriveInstance } from "@blaxel/core";

const drive = await DriveInstance.createIfNotExists({
  name: "my-drive",
  region: "us-was-1",
  displayName: "My Project Drive",     // optional; defaults to name
  labels: { env: "dev", project: "x" }, // optional
});

from blaxel.core.drive import DriveInstance

drive = await DriveInstance.create_if_not_exists(
    {
        "name": "my-drive",
        "region": "us-was-1",
        "display_name": "My Project Drive",
        "labels": {"env": "dev", "project": "x"},
    }
)

ドライブをサンドボックスにマウントする

import { SandboxInstance } from "@blaxel/core";

const sandbox = await SandboxInstance.get("my-sandbox");

await sandbox.drives.mount({
  driveName: "my-drive",
  mountPath: "/mnt/data",
  drivePath: "/",   // optional; defaults to root of the drive
});

from blaxel.core import SandboxInstance

sandbox = await SandboxInstance.get("my-sandbox")

await sandbox.drives.mount(
    drive_name="my-drive",
    mount_path="/mnt/data",
    drive_path="/",
)

マウントすると、サンドボックス内のマウントパスに書き込まれたファイルはドライブに保存され、サンドボックスを削除した後も保持されます。

サブディレクトリをマウントする

await sandbox.drives.mount({
  driveName: "my-drive",
  mountPath: "/app/project",
  drivePath: "/projects/alpha",
});

await sandbox.drives.mount(
    drive_name="my-drive",
    mount_path="/app/project",
    drive_path="/projects/alpha",
)

ドライブの一覧表示、アンマウント、削除

// List mounted drives on a sandbox
const mounts = await sandbox.drives.list();

// List all drives
const drives = await DriveInstance.list();

// Unmount
await sandbox.drives.unmount("/mnt/data");

// Delete a drive
await DriveInstance.delete("my-drive");
// or instance-level:
const drive = await DriveInstance.get("my-drive");
await drive.delete();

mounts = await sandbox.drives.list()

drives = await DriveInstance.list()

await sandbox.drives.unmount("/mnt/data")

await DriveInstance.delete("my-drive")
# or instance-level:
drive = await DriveInstance.get("my-drive")
await drive.delete()

CLI：bl get drives

Agent Drive の完全な例

import { SandboxInstance, DriveInstance } from "@blaxel/core";

// 1. Create a drive
const drive = await DriveInstance.createIfNotExists({
  name: "agent-storage",
  region: "us-was-1",
});

// 2. Create a sandbox (use image ID from custom template)
const sandbox = await SandboxInstance.createIfNotExists({
  name: "my-agent-sandbox",
  image: "my-sandbox-image-id",
  memory: 2048,
  region: "us-was-1",
});

// 3. Mount the drive
await sandbox.drives.mount({
  driveName: "agent-storage",
  mountPath: "/mnt/storage",
  drivePath: "/",
});

// 4. Write a file to the mounted drive
await sandbox.fs.write("/mnt/storage/hello.txt", "Hello from the drive!");

// 5. Read it back
const content = await sandbox.fs.read("/mnt/storage/hello.txt");
console.log(content); // "Hello from the drive!"

// 6. List mounted drives
const mounts = await sandbox.drives.list();
console.log(mounts);

import asyncio
from blaxel.core.drive import DriveInstance
from blaxel.core import SandboxInstance

async def main():
    drive = await DriveInstance.create_if_not_exists(
        {"name": "agent-storage", "region": "us-was-1"}
    )

    sandbox = await SandboxInstance.create_if_not_exists(
        {
            "name": "my-agent-sandbox",
            "image": "my-sandbox-image-id",
            "memory": 2048,
            "region": "us-was-1",
        }
    )

    await sandbox.drives.mount(
        drive_name="agent-storage",
        mount_path="/mnt/storage",
        drive_path="/",
    )

    await sandbox.fs.write("/mnt/storage/hello.txt", "Hello from the drive!")

    content = await sandbox.fs.read("/mnt/storage/hello.txt")
    print(content)

    mounts = await sandbox.drives.list()
    print(mounts)

asyncio.run(main())

ドキュメント：https://docs.blaxel.ai/Agent-drive/Overview

その他の Blaxel リソース

エージェントのホスティング

AI エージェントを、サーバーレスで自動スケーリングする HTTP エンドポイントとしてデプロイします。フレームワークに依存しません（LangChain、CrewAI、Claude SDK など）。

bl new agent
# develop in src/agent.ts or src/agent.py
bl serve            # test locally
bl deploy           # deploy
bl chat AGENT-NAME  # query

同期エンドポイントは最大 100 秒、非同期エンドポイントは最大 10 分間リクエストを処理します。 ドキュメント：https://docs.blaxel.ai/Agents/Overview

MCP サーバーのホスティング

MCP プロトコルに準拠したカスタムツールサーバーをデプロイします。

bl new mcp
# implement in src/server.ts or src/server.py
bl serve --hotreload  # test locally
bl deploy

エージェントは SDK を介して、デプロイ済みの MCP サーバーに接続します：

const tools = await blTools(["functions/my-mcp-server"]);

各サンドボックスは、プロセス管理、ファイルシステム、コード生成用のツールを備えた、組み込みの MCP サーバーも https://<SANDBOX_URL>/mcp で公開します。 ドキュメント：https://docs.blaxel.ai/Functions/Overview

バッチジョブ

並列バックグラウンドタスク（数分から数時間）向けのスケーラブルなコンピューティングです。

bl new job
# implement in src/index.ts or src/index.py
bl deploy
bl run job NAME --data '{"tasks": [...]}'

タスクあたりの最大実行時間は 24 時間です。blaxel.toml で maxConcurrentTasks を設定してください。 ドキュメント：https://docs.blaxel.ai/Jobs/Overview

リソース

• デプロイ設定のリファレンス：https://docs.blaxel.ai/deployment-reference
• CLI コマンドのリファレンス：https://docs.blaxel.ai/cli-reference/introduction

詳しい説明とコード例については、各 SDK ファイルをお読みください。

• ./references/sdk-python.md
• ./references/sdk-typescript.md

各 SDK の README には、次の内容が含まれています。

• SDK の概要
• 要件
• サンドボックス、ボリューム、エージェント、バッチジョブ、MCP を操作するコード例
• その他の役立つ情報

追加のドキュメントについては、https://docs.blaxel.ai/llms.txt をご覧ください。