Backend Discovery
CradleXC uses external backend plugins to generate target-specific files.
Backend plugins are separate executables and are not built into CradleXC.
CradleXC discovers compatible backend executables from supported search locations and exposes them through the CLI.
Backend executable naming
Compatible backend executables follow this naming convention:
cxc-backend-<name>
For example:
cxc-backend-vagrant
The backend name is the portion after:
cxc-backend-
In this example, the backend name is:
vagrant
That backend can then be selected when generating target-specific files.
Discovery locations
CradleXC discovers compatible backend executables from:
PATH
and:
~/.cxc/plugins/
and the default system-wide installation directory:
/opt/cxc/plugins/
Conceptually:
A backend only becomes available to CradleXC when its executable can be discovered through one of the supported locations.
List available backends
Use:
cxc plugin list
to list the backend plugins currently discovered by CradleXC.
Run this command after installing a backend to confirm that the plugin is available.
For example:
cxc plugin list
The exact output depends on the backend plugins installed on the current system.
Install a backend plugin
See the CRADLE release repository for the full list of published plugins and their installable names.
Install a supported backend plugin with:
sudo cxc plugin install <plugin_name>
For example:
sudo cxc plugin install vagrant
After installation, confirm that the backend can be discovered:
cxc plugin list
The release repository is the authoritative list of published plugin names.
Plugin directories
By default, sudo cxc plugin install <plugin_name> installs into:
/opt/cxc/plugins/
Passing --user installs into the per-user directory instead:
CradleXC also searches:
~/.cxc/plugins/
for compatible backend executables.
For example:
~/.cxc/plugins/
└── cxc-backend-vagrant
A backend executable stored in this directory should follow the expected naming convention:
cxc-backend-<name>
System PATH
Backend plugins can also be discovered through the system PATH.
You can inspect your current PATH with:
echo "$PATH"
To check whether a backend executable can be found directly:
which cxc-backend-<name>
For example:
which cxc-backend-vagrant
If a path is returned, the executable is available through the current shell environment.
Discovery workflow
A typical backend setup flow is:
- install the backend plugin
- confirm that the executable is available
- list discovered backends
- generate target-specific files with the selected backend
For example:
sudo cxc plugin install vagrant
Then:
cxc plugin list
Once the backend is available:
cxc build \
-i scenarios/HelloWorld.cradle \
--target vagrant \
-o ./output
The overall relationship is:
cxc plugin listcxc buildSelecting a backend
A discovered backend can be selected through cxc build.
The general form is:
cxc build \
-i <scenario.cradle> \
--target <plugin_name> \
-o <output_directory>
For example:
cxc build \
-i scenarios/HelloWorld.cradle \
--target vagrant \
-o ./output
The value supplied to:
--target
selects the backend used for target-specific generation.
Backend discovery and configuration
Backend discovery determines whether CradleXC can locate a compatible backend executable.
Backend configuration determines how that backend behaves.
These are separate concerns.
| Area | Purpose |
|---|---|
| Backend discovery | Determines whether CradleXC can locate the backend executable. |
| Backend configuration | Controls behavior specific to that backend or target. |
| CRADLE source | Describes the scenario itself. |
A backend can expose target-specific or provider-specific settings without adding those settings to the CRADLE language.
Provider configuration
A backend can generate configuration for another target or provider.
For example:
A Vagrant backend could generate configuration for a provider such as
libvirt or another provider supported by that backend.
The provider is therefore configured through the backend rather than being built directly into CRADLE or CradleXC.
Backend dependencies
Some backend plugins can depend on additional external tools.
Check the current environment with:
cxc doctor
If installation guidance is available for missing dependencies:
cxc install-deps
Backend-specific documentation can also define additional dependencies that are not part of the core CradleXC installation.
A backend being discoverable does not necessarily mean every dependency required by that backend is installed.
Backend not listed
If:
cxc plugin list
does not show the expected backend, check the following.
Confirm installation
If the backend is distributed through the CRADLE plugin system, install it with:
sudo cxc plugin install <plugin_name>
Then check again:
cxc plugin list
Confirm the executable name
The executable should follow:
cxc-backend-<name>
For example:
cxc-backend-vagrant
Check ~/.cxc/plugins/
Inspect the plugin directory:
ls -la ~/.cxc/plugins/
Confirm that the expected backend executable is present.
Check the system PATH
Try:
which cxc-backend-<name>
For example:
which cxc-backend-vagrant
If no path is returned, the executable is not available through the current shell PATH.
Check executable permissions
If the backend exists but cannot be executed, inspect its permissions:
ls -l ~/.cxc/plugins/
A backend executable needs appropriate execution permissions for the current user.
Check dependencies
Run:
cxc doctor
and review any reported issues.
Backend discovered but generation fails
A backend can be discovered successfully while cxc build still fails.
First validate the scenario:
cxc validate -i <scenario.cradle>
Then confirm the backend:
cxc plugin list
Retry generation:
cxc build \
-i <scenario.cradle> \
--target <plugin_name> \
-o <output_directory>
If generation still fails, check:
- backend-specific configuration
- backend-specific dependencies
- whether the backend supports the requested scenario features
- the diagnostics returned by CradleXC
- the diagnostics returned by the backend
For additional guidance, see Troubleshooting.
Discovery does not imply feature compatibility
CradleXC discovering a backend means the backend executable is available.
It does not guarantee that the backend supports every CRADLE feature.
For example, a backend can support only a subset of:
- instance configuration
- network behavior
- artifact handling
- provider-specific settings
- event-related generation
Check the documentation for the selected backend before assuming a scenario feature is supported by that target.
CradleXC and backend boundaries
The responsibility split remains:
| Component | Responsibility |
|---|---|
| CRADLE source | Defines the scenario. |
| CradleXC | Validates and processes CRADLE source. |
| Backend discovery | Locates compatible external backend executables. |
| Backend plugin | Generates target-specific files. |
| Target tooling | Uses the generated files in the user's testbed. |
CradleXC does not automatically execute target-specific files generated by a backend.
Related documentation
Next steps
Continue with CLI Outputs to understand the main outputs produced by CradleXC and its backend plugins.