Permission configuration

Function

BT maintains compatibility behavior by default, allowing scripts to use all standard library capabilities. Production environments can tighten permissions via environment variables to deny file, process, network, HTTP, MySQL, device, environment variables, desktop, screen capture, and FFI capabilities at standard library boundaries.

Permission checking only occurs at standard library construction or method call boundaries and does not enter the VM ordinary instruction loop.

Syntax

View the current configuration when running:

Parameters

Environment variable	Type	Required	Default value	Description
BT_PERMISSION_ALLOW	String	No	Not configured	List of allowed capabilities. After configuration, only the capabilities in the list are allowed; comma, semicolon or blank separation is supported.
BT_PERMISSION_DENY	String	No	Not configured	Deny capability list. Deny lists have higher priority than allow lists.

Capability name:

Name	Capability
fs	`fs()` File reading and writing, directory operations.
process	`process()` child process capability.
net	`net()`, `net.listen()`, `net.connect()`, DNS and interface information.
http	`reqwest()` HTTP client capability, also supports the alias `reqwest`.
mysql	`mysql()` database capabilities.
device	`device()`, serial port scanning and serial port reading and writing.
env	`BT.env()`, `BT.set_env()`, `BT.envs()` and PATH overlays.
desktop	`bt_app` Desktop bridging commands, including windows, system dialog boxes, trays, clipboards, notifications, drag-in file events and application-level desktop operations.
screen	Screen reading for `window.bt.screen.pick_color()` and `capture_area()`; supports aliases `capture`, `screenshot`.
ffi	Controls dynamic library loading and native function calling, and also supports the alias `native`.

Special value:

Value	Description
all	Indicates all abilities.
none	Indicates an empty capability list.

Return Value

BT.stats().permission Return object:

Field	Type	Description
denied	Int	The number of permission denials in the current process.
config	Object	Snapshot of current permission configuration.

config Field:

Field	Type	Description
allow_configured	Bool	Whether `BT_PERMISSION_ALLOW` is explicitly configured.
allow	Array	Names of capabilities in the allow list. Returns all capabilities when not configured.
deny	Array	Names of capabilities in the deny list.
allowed	Array	The name of the currently allowed capability.
config_error	String / Empty	Permission configuration error; if there is no error, it is `empty`.

Code Examples

Notes

When BT_PERMISSION_ALLOW and BT_PERMISSION_DENY are not set by default, BT allows full capabilities and is compatible with existing scripts.
If both allow and deny are configured, the deny list takes effect first. For example, when BT_PERMISSION_ALLOW=all and BT_PERMISSION_DENY=process, process() will be rejected.

- Permission denied throws a Chinese runtime error, does not return empty or fails silently.

The permission configuration is cached after being read for the first time in the process; after the resident process modifies the environment variables, the process needs to be restarted to take effect.
desktop controls window.bt.window, window.bt.dialog, window.bt.tray, window.bt.clipboard, window.bt.notify, window.bt.drag, window.bt.app and initialization project commands; window.bt.call() is still a long-term VM business channel and is used internally by the called BT function fs, process, net and other capabilities continue to be checked according to their respective permissions.

- screen is an additional sensitive permission; the public screen API must pass both desktop and screen so that production environments can retain the normal window/tray API and turn off screen reading alone.

ffi.close() does not check ffi permissions to ensure that created dynamic library resources can still be released after tightening permissions; ffi permissions are checked during loading and every native call.

- Permissions configuration regression example at examples/permission-stats.bt that verifies the allow/deny combination and the BT.stats().permission configuration snapshot.