Skip to content
Fluxzero Fluxzero Fluxzero Fluxzero

SDK installation

Use this page when you want to configure SDK dependencies directly. For an agent-led start, set up your agent. For the native CLI, Homebrew, WinGet and updates, use Install and update.

SDK 2.x requires Java 25. Use JDK 25.0.3 or newer for compilation. Java and Kotlin applications use the same SDK artifacts and BOM.

Start with a coding agent

Section titled “Start with a coding agent”

Follow the plugin setup, then start an app or explore a working example. The agent selects matching SDK documentation and manages the local development environment.

Create a project with the CLI

Section titled “Create a project with the CLI”

The CLI guide describes project generation and local development. Follow the generated project’s build instructions; Maven and Gradle templates use different wrappers. To add Fluxzero to an existing project, use the dependency configuration below.

Manually

Section titled “Manually”

Maven

Section titled “Maven”

Add Fluxzero Packages to your pom.xml, inside <project>. Merge these entries with any existing repository sections. Dependencies and Maven build plugins use separate repository lists:

<repositories>
    <repository>
        <id>fluxzero</id>
        <url>https://packages.fluxzero.io/maven</url>
        <snapshots><enabled>false</enabled></snapshots>
    </repository>
</repositories>
<pluginRepositories>
    <pluginRepository>
        <id>fluxzero-plugins</id>
        <url>https://packages.fluxzero.io/maven</url>
        <snapshots><enabled>false</enabled></snapshots>
    </pluginRepository>
</pluginRepositories>

Downloads are public and require no account or credentials. Existing artifacts remain on Maven Central; from 1 October 2026, new Fluxzero releases will be published only at Fluxzero Packages.

Import the Fluxzero BOM in your dependencyManagement section to centralize version management. Set fluxzero.version to the release you want from the BOM directory:

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>io.fluxzero</groupId>
            <artifactId>fluxzero-bom</artifactId>
            <version>${fluxzero.version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

Then declare only the dependencies you actually need (no version required):

<dependencies>
    <dependency>
        <groupId>io.fluxzero</groupId>
        <artifactId>sdk</artifactId>
    </dependency>
    <dependency>
        <groupId>io.fluxzero</groupId>
        <artifactId>sdk</artifactId>
        <classifier>tests</classifier>
        <scope>test</scope>
    </dependency>
    <dependency>
        <groupId>io.fluxzero</groupId>
        <artifactId>test-server</artifactId>
        <scope>test</scope>
    </dependency>
    <dependency>
        <groupId>io.fluxzero</groupId>
        <artifactId>proxy</artifactId>
        <scope>test</scope>
    </dependency>
</dependencies>

Annotation processing

Section titled “Annotation processing”

For Java versions above 21, you must explicitly register the Fluxzero SDK as an annotation processor. This ensures that all of Fluxzero’s annotations are properly detected during compilation.

Add the Fluxzero SDK to the annotationProcessorPaths of your maven-compiler-plugin:

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-compiler-plugin</artifactId>
    <configuration>
        <parameters>true</parameters>
        <annotationProcessorPaths>
            <path>
                <groupId>io.fluxzero</groupId>
                <artifactId>sdk</artifactId>
            </path>
        </annotationProcessorPaths>
    </configuration>
</plugin>

Gradle

Section titled “Gradle”

Add the Packages repository before Maven Central in build.gradle.kts or build.gradle. Maven Central remains available for other libraries. If your build centralizes repositories in settings.gradle(.kts), put these entries in dependencyResolutionManagement.repositories instead.

For Fluxzero Gradle plugins used through plugins {}, also add Packages in pluginManagement.repositories in settings.gradle.kts, before the Plugin Portal:

pluginManagement {
    repositories {
        maven { url = uri("https://packages.fluxzero.io/maven") }
        gradlePluginPortal()
    }
}

Keep pluginManagement at the start of the settings file. It is only needed for Gradle plugin resolution, not for using the SDK as a dependency. The same repository declarations work in Groovy settings with single-quoted strings.

Use platform BOM support to align dependency versions automatically:

Kotlin DSL (build.gradle.kts)
repositories {
    maven { url = uri("https://packages.fluxzero.io/maven") }
    mavenCentral()
}


dependencies {
    implementation(platform("io.fluxzero:fluxzero-bom:${fluxzeroVersion}"))
    implementation("io.fluxzero:sdk")
    testImplementation("io.fluxzero:sdk") {
        artifact { classifier = "tests" }
    }
    testImplementation("io.fluxzero:test-server")
    testImplementation("io.fluxzero:proxy")
    annotationProcessor("io.fluxzero:sdk")
}
Groovy DSL (build.gradle)
repositories {
    maven { url = uri('https://packages.fluxzero.io/maven') }
    mavenCentral()
}


dependencies {
    implementation platform("io.fluxzero:fluxzero-bom:${fluxzeroVersion}")
    implementation 'io.fluxzero:sdk'
    testImplementation('io.fluxzero:sdk') {
        artifact { classifier = 'tests' }
    }
    testImplementation 'io.fluxzero:test-server'
    testImplementation 'io.fluxzero:proxy'
    annotationProcessor 'io.fluxzero:sdk'
}

© 2026 Fluxzero