boxlang-configuration

BoxLang の設定

BoxLang は、開発者と AI エージェントが協力しながらアプリケーションを構築、モダナイズ、実行するための、AI ネイティブなソフトウェア生産性プラットフォームです。

概要

BoxLang のランタイムは boxlang.json で設定します。このファイルは初回起動時に BoxLang のホームディレクトリに自動作成されます。ファイルを変更せずに、環境変数または Java システムプロパティで、すべての設定を上書きできます。

Application.bx のアプリ固有の動作（this.name、ライフサイクルコールバック、アプリごとのスケジューラー／ウォッチャー、ネストされたアプリの 分離）に関する設定の場合は、 application-descriptor スキルと併せてご利用ください。

---

設定ファイルの場所

ランタイム	デフォルトの場所
OS／CLI／MiniServer	~/.boxlang/config/boxlang.json
CLI プロジェクトの上書き（v1.18+）	カレント作業ディレクトリ内の ./.boxlang.json。BOXLANG_CONFIG／--bx-config が設定されていない場合に使用されます
AWS Lambda	{lambdaRoot}/boxlang.json
Google Cloud Functions	{gcfRoot}/boxlang.json
CommandBox	~/.commandbox/servers/{home}/WEB-INF/boxlang/config/boxlang.json

起動時にホームディレクトリを上書きします。

boxlang --home /path/to/custom-home

---

環境変数による上書き

設定は、BOXLANG_ プレフィックス（スネークケース）または boxlang. プレフィックス（ドット記法）を使用して、 環境変数または JVM プロパティで上書きできます。

# Enable debug mode
BOXLANG_DEBUGMODE=true

# Set log level for runtime logger
boxlang.logging.loggers.runtime.level=TRACE

# Set as JVM argument
java -Dboxlang.debugMode=true -jar boxlang.jar

複雑な上書きには JSON 値を使用できます。

BOXLANG_DATASOURCES='{"mainDB":{"driver":"postgresql","host":"db.example.com"}}'

---

環境変数の置換

boxlang.json 内で ${env.VAR:default} を使用して、環境変数を参照します。

{
    "datasources": {
        "mainDB": {
            "driver":   "postgresql",
            "host":     "${env.DB_HOST:localhost}",
            "port":     "${env.DB_PORT:5432}",
            "database": "${env.DB_NAME:myapp}",
            "username": "${env.DB_USER:app}",
            "password": "${env.DB_PASSWORD}"
        }
    }
}

組み込みのパス置換変数：

変数	解決先
${boxlang-home}	BoxLang のホームディレクトリ
${user-home}	OS ユーザーのホームディレクトリ
${user-dir}	カレント作業ディレクトリ
${java-temp}	Java の一時ディレクトリ

---

コアディレクティブ

{
    // Compiled class output directory
    "classGenerationDirectory": "${boxlang-home}/classes",

    // Compiler backend: "asm" (default, best performance) or "java"
    "compiler": "asm",

    // Store compiled classes on disk (recommended: true for production)
    "storeClassFilesOnDisk": true,

    // Never re-check class files (recommended: true for production)
    "trustedCache": false,

    // Cache class resolver lookups (recommended: true)
    "classResolverCache": true,

    // Clear class files on startup (use only for debugging)
    "clearClassFilesOnStartup": false,

    // Global class paths (.bx file discovery)
    "classPaths": [
        "${boxlang-home}/global/classes"
    ],

    // Custom component directories
    "customComponentsDirectory": [
        "${boxlang-home}/global/components"
    ],

    // Default datasource name
    "defaultDatasource": "",

    // Max completed threads tracked per request
    "maxTrackedCompletedThreads": 1000,

    // Enable debug output in responses
    "debugMode": false
}

---

データソース

{
    "datasources": {
        "mainDB": {
            "driver":   "postgresql",
            "host":     "${env.DB_HOST:localhost}",
            "port":     5432,
            "database": "myapp",
            "username": "${env.DB_USER:app}",
            "password": "${env.DB_PASSWORD}"
        },
        "legacyMySQL": {
            "driver":   "mysql",
            "host":     "db2.internal",
            "port":     3306,
            "database": "legacy",
            "username": "${env.MYSQL_USER}",
            "password": "${env.MYSQL_PASS}",
            // Connection pool settings
            "connectionTimeout":   30,
            "maximumPoolSize":     10,
            "minimumIdle":         2
        }
    }
}

サポートされているドライバー：postgresql、mysql、mssql、oracle、derby、h2、sqlite。

---

キャッシュ

{
    "caches": {
        // Default cache (used when no cache name specified)
        "default": {
            "provider": "BoxCacheProvider",
            "properties": {
                "maxObjects":       1000,
                "defaultTimeout":   60,
                "defaultLastAccessTimeout": 0,
                "objectStore":      "ConcurrentStore"
            }
        },
        // Named cache for templates
        "templates": {
            "provider": "BoxCacheProvider",
            "properties": {
                "maxObjects": 500,
                "defaultTimeout": 120
            }
        }
    }
}

---

エグゼキューター

{
    "executors": {
        // Default executor for runAsync() — virtual threads
        "boxlang-tasks": {
            "type": "virtual",
            "coreThreads": 20
        },
        // CPU-bound work pool
        "cpu-work": {
            "type": "fixed",
            "coreThreads": 8
        },
        // Elastic pool for bursty I/O
        "io-tasks": {
            "type": "cached"
        },
        // Scheduler pool
        "scheduler": {
            "type": "scheduled",
            "coreThreads": 5
        }
    }
}

エグゼキューターの種類：virtual（デフォルト、Project Loom）、fixed、cached、scheduled、work_stealing。

---

ロギング

{
    "logging": {
        "logsDirectory": "${boxlang-home}/logs",
        "level": "WARN",   // Global default: TRACE, DEBUG, INFO, WARN, ERROR
        "loggers": {
            "runtime":    { "level": "INFO" },
            "scheduler":  { "level": "INFO", "async": true },
            "datasource": { "level": "WARN" },
            "cache":      { "level": "WARN" },
            "modules":    { "level": "INFO" }
        }
    }
}

---

セキュリティ

{
    "security": {
        // Regex patterns for blocked Java class imports
        "disallowedImports": [],
        // Blocked BIF names
        "disallowedBifs": [],
        // Blocked component names
        "disallowedComponents": [],
        // Whether Java system props/env are in server.system scope
        "populateServerSystemScope": true,
        // Explicit upload extension whitelist (overrides disallowed list)
        "allowedFileOperationExtensions": [],
        // Blocked file upload/move extensions
        "disallowedFileOperationExtensions": []
    }
}

---

モジュール

起動時に読み込まれるモジュールと、モジュール固有の設定を構成します。

{
    "modules": {
        // Modules to load on startup (in addition to auto-discovered modules)
        "load": [ "bx-compat-cfml", "bx-orm" ],
        // Modules to skip loading even if present
        "exclude": [],
        // Per-module settings
        "settings": {
            "bx-orm": {
                "autoManageSession": true,
                "dialect":           "PostgreSQLDialect"
            }
        }
    }
}

---

スケジューラー

{
    "scheduler": {
        // Default task timeout (0 = no timeout)
        "defaultTimeout": 0,
        // How long to wait for scheduled tasks to complete on shutdown
        "shutdownTimeout": 30,
        // Executor to use for scheduled tasks
        "executor": "scheduler"
    }
}

---

ウォッチャー

組み込みの WatcherService を設定して、ファイルシステムを監視します。ウォッチャーはファイルやディレクトリの変更に反応し、ホットリロード、アセットのビルド、カスタム自動化を実行できます。

{
    "watcher": {
        // Recurse into subdirectories by default
        "recursive": true,
        // Hold events until no new event arrives within this window (ms); 0 = off
        "debounce": 300,
        // Emit at most one event per window and drop the rest (ms); 0 = off
        "throttle": 0,
        // Suppress noisy intermediate events from atomic save patterns (temp + rename)
        "atomicWrites": true,
        // Startup delay before watchers begin processing events (ms)
        "delay": 0,
        // Auto-stop watcher after this many consecutive listener errors (0 = disabled)
        "errorThreshold": 10,
        // Named watcher definitions auto-started at runtime startup
        "definitions": {
            "hot-reload": {
                "paths":    "${user-dir}/src",
                "listener": "app.listeners.HotReloadListener"
            },
            "assets": {
                "paths":     [ "${user-dir}/resources/css", "${user-dir}/resources/js" ],
                "recursive": false,
                "throttle":  500,
                "listener":  "app.listeners.AssetPipelineListener"
            }
        }
    }
}

ウォッチャー定義のプロパティ

プロパティ	必須	説明
paths	はい	監視するディレクトリのパス、またはパスの配列
listener	はい	リスナーの動作を定義する BoxLang クラスのパス
recursive	いいえ	グローバルな再帰設定を上書きします
debounce	いいえ	ウォッチャーごとのデバウンス設定の上書き（ミリ秒）
throttle	いいえ	ウォッチャーごとのスロットル設定の上書き（ミリ秒）
atomicWrites	いいえ	ウォッチャーごとのアトミック書き込みフィルタリング設定の上書き
delay	いいえ	ウォッチャーごとの起動遅延設定の上書き（ミリ秒）
errorThreshold	いいえ	ウォッチャーごとのエラーしきい値設定の上書き

クロージャーや構造体ベースのリスナーを使用する場合は、boxlang.json ではなく、実行時に watcherNew() を使ってプログラムからウォッチャーを作成してください。

実行時のウォッチャー BIF

watcherNew()、watcherStart()、watcherStop()、watcherRestart()、watcherList()、watcherGet()、watcherExists()、watcherShutdown()、watcherStopAll()、watcherShutdownAll()

---

ランタイム設定

ユーザーが定義するグローバルな名前付き設定です。BoxLang は解釈しません。値には任意の型（文字列、数値、ブール値、構造体、配列）を指定でき、キーは一意です。

{
    "runtimeSettings": {
        "apiUrl":    "${env.API_URL:http://localhost}",
        "stripeKey": "bxsecret:AbC123...",
        "features":  { "beta": true, "regions": [ "us", "eu" ] }
    }
}

• ${env.VAR}、${env.VAR:default}、パス変数、bxsecret: の値は、配列内を含む任意の階層で解決されます。補間された値は文字列になります。デフォルト値のない未解決のプレースホルダーは、そのまま残ります。
• getRuntimeSetting( key, default ) BIF で読み取ります。ドット区切りのパス（features.beta）、1 始まりの配列インデックス（features.regions.1）を使用できます。引数を指定しないと、マージ済みの構造体全体が返されます。デフォルト値を指定せずに存在しないキーを指定すると、エラーが発生します。
• 値は深い階層まで読み取り専用です。
• Application.bx の this.runtimeSettings（または bx:application runtimeSettings={...}）は、グローバル構造体に対してディープマージされ、キーごとにアプリケーション側の値が優先されます。配列とスカラー値はマージされず、置き換えられます。
• グローバル値はランタイム設定の読み込み時に一度だけ解決されます。Application.bx レイヤーでは、記述子が再読み込みされるたびに ${...} と bxsecret: が再解決され、そのリクエスト中はキャッシュされます。アプリケーションレイヤーで ${...} 補間されるのは runtimeSettings のみです。
• これは、Java のシステムプロパティと環境変数を読み取る getSystemSetting() とは異なります。

---

試験的機能

開発中の BoxLang 機能に関するフラグです。これらの設定は変更または削除される場合があります。

{
    "experimental": {
        // Compiler backend: "asm" (default, direct bytecode) or "java" (transpile to Java first)
        "compiler": "asm",
        // Capture AST JSON to /grapher/data on each parse (for tooling/debugging only)
        "ASTCapture": false
    }
}

フラグ	デフォルト	説明
compiler	"asm"	"asm" はバイトコードに直接コンパイルします（本番環境でのデフォルト）。"java" は最初に Java ソースへ変換します
ASTCapture	false	解析のたびに /grapher/data に AST JSON を書き込みます。ツールとデバッグ専用であり、本番環境では使用しません

---

アプリケーションレベルの設定（Application.bx）

アプリケーションレベルの設定は、特定のアプリケーションに対してランタイム設定を上書きします。

class {
    // Application identity
    this.name             = "MyApp"
    this.sessionManagement = true
    this.sessionTimeout   = createTimeSpan( 0, 2, 0, 0 )

    // Datasource
    this.datasource = "mainDB"

    // Per-application datasource definition
    this.datasources = {
        localDB: {
            driver:   "h2",
            database: expandPath( "/db/local.h2" )
        }
    }

    // Java library paths
    this.javaSettings = {
        loadPaths: [ expandPath( "/lib/" ) ]
    }

    // Cache mappings
    this.caches = {
        objects: { provider: "BoxCacheProvider" }
    }

    // Directory mappings
    this.mappings = {
        "/models":   expandPath( "/app/models/" ),
        "/services": expandPath( "/app/services/" )
    }
}

---

本番環境の設定チェックリスト

• trustedCache: true — リクエストごとのディスクチェックを行いません
• classResolverCache: true — クラス解決をキャッシュします
• debugMode: false — レスポンスにデバッグ出力を含めません
• logging.level: "WARN" — 詳細なログを抑制します
• ${env.VAR} を使用してシークレットを設定します — boxlang.json に直接記述しないでください
• classGenerationDirectory を高速なディスク（SSD/tmpfs）に設定します
• 想定される同時実行数に合わせて接続プールのサイズを調整します
• システム環境変数が不要な場合は、security.populateServerSystemScope: false に設定します