Skip to main content
ubx’s engine system is built on a plugin architecture. Each execution engine (Pulumi, Terraform, OpenTofu) is a separate binary that communicates with the ubx CLI over gRPC.

​
Architecture

ubx CLI
  │
  │  IR JSON (over stdin / gRPC)
  ▼
Plugin binary (ubx-plugin-<name>)
  │
  │  Compile → artifact_uri
  │  Plan    → preview summary
  │  Apply   → ProgressEvent stream
  │  Destroy → ProgressEvent stream
  ▼
Cloud Provider API
The plugin protocol is defined in ubx-plugin-protocol (Protocol Buffers / gRPC). Any binary that implements the protocol can be used as a ubx engine.

​
Plugin discovery

ubx finds plugins by searching in order:
  1. ~/.ubx/plugins/<name>/ubx-plugin-<name> — installed via ubx plugin install
  2. ubx-plugin-<name> on $PATH — any binary in the system path
The binary must be a regular executable file (not a directory or symlink to a non-executable).

​
Plugin launch

ubx launches the plugin binary with the environment variable UBX_PLUGIN_LAUNCH=1. The plugin starts a gRPC server on a random local port and prints the port to stdout. ubx connects and communicates via gRPC.

​
Official plugins

PluginEngineRuntime
ubx-plugin-pulumiPulumiPython, TypeScript, Go
ubx-plugin-terraformTerraform(wraps terraform CLI)
ubx-plugin-opentofuOpenTofu(wraps tofu CLI)

​
Installing plugins

ubx plugin install pulumi
ubx plugin install terraform
ubx plugin install opentofu
Or from a specific GitHub release: 
ubx plugin install github://ubiquex/ubx-plugin-pulumi@v1.2.0
Or from a local binary: 
ubx plugin install file:///path/to/ubx-plugin-myengine

​
Plugin lock file

After installing, ubx writes .ubx/plugin.lock with the source and SHA256 of each installed plugin.

​
Writing a custom plugin

See Writing a Plugin for the full guide. Custom plugins implement the same gRPC protocol as the official plugins.