CI/CD workflow guide
Integration tests are most effective when they are set up to be executed continuously whenever the test subject changes. The CI toolchain that is provided with the Intrinsic SDK allows to set up continous integration for any software asset. It covers building, installing, and operating the assets with a test environment (deployed solution) as well as the logging required to determine proper functionality.
An exemplary setup of a CI workflow has been added to the sdk-examples repository. The repository itself uses the CI toolchain in a configured GitHub workflow that tests selected example assets (see GitHub workflow). Additionally, the workflow and its tooling are described in a README. You can use this information to set up your own continuous integration workflows in your development tooling.
The following steps are the most important parts of such a continuous integration workflow; they are covered in this guide:
- Select and deploy a solution to test with
- Build assets to test from their source
- Install the created assets to the test solution
- Check whether assets have been properly installed and instantiated
- Check how assets operate together and if they meet the expected behavior
All those steps are realized through command line tooling (see
inctl) and Python scripting
with the
SolutionBuildingLibrary.
Prerequisites
Before you begin, ensure you have a
working development environment
and have authenticated to your organization using inctl.
Start a solution on a VM
This workflow is particularly useful for automating solution testing within a continuous integration/continuous deployment (CI/CD) pipeline, or for validating a solution's compatibility against different versions of IntrinsicOS and the runtime. By following this guide, you can lease a virtual machine (VM) with specific software versions to ensure your solution works with both older and newer platform releases, independent of your project's own release schedule.
Step 1: Lease a VM from a pool
You can lease a VM from a pool for temporary use. Leases have an expiration time that can be set during creation and extended later.
There are multiple ways to get a VM. Choose depening on your requirements.
Lease a VM with default settings
To lease a VM from the default pool with an expiration time of 1 hour, run the following command:
inctl vm lease -d 1h --org <your-org>
Default lease duration (if not using -d flag): 30min
Maximum initial lease duration: 48h
Maximum lease extension : 120h . For example, you can request a four hour lease extension with inctl vm expire-in 4h.
Lease a VM from a specific Pool
If you want to lease from a specific pool instead of the default pool, you can list all pools available to you:
inctl vm pool list --org <your-org>
# Example output:
Idx Name Current_status Desired_status Runtime Intrinsic_os Hardware_template Tier
0 bathtub RUNNING RUNNING intrinsic.platform.20251023.RC05 20250912.RC01 default ad_hoc_single
1 default RUNNING RUNNING 0.20251208.0-RC02 20251126.RC01 default custom
2 default-gpu RUNNING RUNNING 0.20251208.0-RC02 20251126.RC01 gpu custom
For the purpose of this example, we want a VM with a GPU. Under
Hardware_template the pool default-gpu matches our requirement.
We lease a VM from a specific pool using the --pool flag:
inctl vm lease --pool=<pool-name> --org <your-org>
Lease a VM with dedicated versions
You can request a VM with specific versions of the runtime and IntrinsicOS. This is useful for testing backward compatibility or preparing for an upcoming release.
To list available versions:
inctl asset list_released_versions --asset_types=data ai.intrinsic.runtime --org <your-org>
inctl asset list_released_versions --asset_types=data ai.intrinsic.os --org <your-org>
To lease a VM with a specific runtime, use the --runtime flag. Likewise use
the --intrinsic-os flag to specify the the os version to use. If any of the
version flags is omitted, the latest version is used.
inctl vm lease --runtime 0.20251208.0-RC02 --intrinsic-os 20251126.RC01 --org=<your-org>
Leasing a VM with specific versions can take 3-10 minutes.
Create your own pool with VMs to lease from
For more control over the virtual machine (VM) configurations available to your team, you can create your own custom VM pools. This allows you to define specific combinations of hardware, software, and sizing to meet your development and testing needs. By specifying a tier (size of the VMPool), hardware template (computing hardware used for the VMs), IntrinsicOS Version and Runtime you can create your own VMPool.
inctl vm pool list-tiers --org=<your-org> #See all available tiers
#Example Output
Description Name
This pool has no ready VMs and can hold at most one VM at a time. The VM will be started on an incoming lease request. ad_hoc_single
Pool sized for a team of people working with VMs. multi_client
inctl vm pool list-hwtemplates --org=<your-org> #See all available hardware templates
#Example Output
Name Description Has_gpu
gpu CPU & GPU hardware on board with medium Power true
default The beloved original (without GPU) that everyone talks about. false
Create a pool (Optional flags:
--runtime,--intrinsic-os,--tier,--hwtemplate):
inctl vm pool create \
--pool=jacuzzi \
--org=<your-org>
By default, if not specified using the optional flags, a pool will be of tier
ad_hoc_single and will have the latest versions of IntrinsicOS and Runtime.
Update a VM pool
You can update both custom and default VM pools with zero downtime. This means you can roll out new versions of IntrinsicOS or the runtime without interrupting developers who are actively using previously leased VMs.
When a pool is updated, the system creates a new set of VMs with the updated software versions. Existing leases are not affected and will continue to run on their original VMs with the older software until the lease expires or is returned. All new lease requests will be directed to the new, updated VMs. If a lease request is made while an update is in progress, it will be served by the existing, older VMs to ensure there is no disruption. Once the new VMs are ready, the system seamlessly switches to using them for all subsequent leases.
Default pools are managed by the Intrinsic platform and are automatically updated to the latest runtime and IntrinsicOS versions. For self-service default pool management, please contact Intrinsic support to request access.
To execute updates on pools that you are allowed to modify, you can use the
inctl vm pool update command to change the runtime and IntrinsicOS versions.
To update a pool to the latest runtime and IntrinsicOS versions, provide an
empty string to the --runtime and --intrinsic-os flags:
inctl vm pool update --pool <your-pool-name> --runtime "" --intrinsic-os "" --org=<your-org>
You can also update only one of them:
inctl vm pool update --pool <your-pool-name> --runtime "" --org=<your-org>
Or update to a specific version:
inctl vm pool update --pool <your-pool-name> --runtime 0.20251208.0-RC02 --org=<your-org>
When you run the update command, the system begins a process to update the
pool in the background. The response from the command will include a
reconciling flag. If this flag is true, it means the update is still in
progress.
To check the status of the update, you can re-run the same update command. The
VMPool API is idempotent, meaning that running the same command multiple times
will not have any unintended side effects. If the reconciling flag in the
response is false, the update is complete.
If an update is already in progress for a pool, any new update requests for that same pool will be ignored, and the response will show the ongoing reconciling configuration.
You can use inctl vm pool [pause|delete|resume] --pool=<pool-name> --org=<your-org> to manage your pool.
| Pool States | What it means for you |
|---|---|
| UNINITIALIZED | This is the initial state before the pool is created. It's a temporary state while the system sets things up in the background. |
| INITIALIZING | The pool is starting up, and VMs are being prepared. You can't lease VMs just yet, but they will be available soon. |
| RUNNING | The pool is active and ready for use. You can lease new VMs from it. |
| PAUSING | The pool is in the process of becoming inactive. No new leases are accepted, and any unused VMs are being removed. |
| PAUSED | The pool is temporarily inactive. You cannot lease new VMs, but any VMs you have already leased will continue to run. |
| STOPPING | The pool is in the process of shutting down completely. All VMs, including those you have leased, are being waited for return or expiration and deleted. |
| STOPPED | The pool is completely inactive. All VMs have been deleted, and no resources are being used. |
| DELETING | The pool and all its associated resources are being permanently removed from the system. |
| DELETED | The pool has been successfully and permanently removed. |
Any of the status changing commands will change the desired status. How — and whether — the pool reaches the desired status is handled by the platform internals.
The inctl vm pool leases command is used to manage and view information about
leases on pools. It allows you to list all the current leases for a specific VM
pool and to terminate a lease if you are administrator of that pool.
Users with the role vmpoolAdmin are allowed to administer all pools inside
their organization.
Step 2: Start your solution
Once you have leased a VM, you can start a solution on it. To do this, you will
need the name of the cluster (which is the name of your leased VM) and the ID of
the solution you want to start. You can find the VM name in the output of the
inctl vm lease command. To find the solution ID, navigate to the solution in
the Flowstate Editor, click the three-dot menu, and select Copy solution ID.
Run the following command to start your solution:
inctl solution start --cluster <vm-name> <solution-id>
For example:
inctl solution start --cluster vmp-3f30-acycyldt 685d7f00-4f11-4707-b279-e9daf5275f64_BRANCH
This will deploy and start your solution on the specified VM.
Step 3: Access the Solution in the Flowstate Editor
After starting your solution, you can access it in the Flowstate Editor. The
inctl vm lease command you ran in Step 1 provides a direct link to the
Solution Editor for your leased VM.
Check the output from the lease command for a line similar to this:
- Frontend URL: https://flowstate.intrinsic.ai/solution-editor/<your-project>/<vm-name>/
Step 4: Return the VM
When you are finished with your work, you can return the VM to the pool. This will make its resources available for other users and prevent unnecessary use of your organization's VM quota. All data on the VM will be lost when it is returned.
To return the VM, use the inctl vm return command:
inctl vm return <vm-name> --org <your-org>
This will end your lease and free up the compute resources.