Quick Start

Get Started

Use the verified CLI to configure Contexa in a Spring Boot project. Choose Quick for a ready-to-run local setup or Custom for exact control over integration, security ownership, providers, infrastructure, and Docker startup.

Prerequisites

Java and Spring Boot are always required. Docker is optional when you generate Compose only, while Quick can provision its selected PostgreSQL and Ollama services automatically.

Requirement	Version	Notes
Java	17+	LTS release
Spring Boot	3.x	Current validation baseline: 3.5.4; 4.x is not supported
15+	Quick generates a dedicated service; manual dependency-only integration does not require it
Ollama Optional	Latest	Required only when Ollama is selected as the AI provider

Optional: Database setup

Quick generates a dedicated PostgreSQL service. Create the database manually only when Custom uses external infrastructure or when you follow the manual dependency path.

SQL

CREATE DATABASE contexa;
\c contexa
CREATE EXTENSION IF NOT EXISTS vector;
CREATE EXTENSION IF NOT EXISTS "uuid-ossp";

Optional: Ollama models

Pull the selected chat and embedding models only when Ollama is your AI provider.

Shell

ollama pull qwen2.5:7b
ollama pull mxbai-embed-large

Recommended: initialize with the CLI

The installer adds only the verified contexa executable. A Spring project changes only after contexa init shows its plan and you confirm it.

1. Install and verify the CLI

Linux / macOS

curl -fsSL https://install.ctxa.ai/install.sh | sh

Windows PowerShell 5.1+

irm https://install.ctxa.ai/install.ps1 | iex

Verify

contexa --version

2. Choose Quick or Custom

Shell

cd your-spring-project
contexa init

Choice	Applied result	Use when
Quick	Merge, FULL, SHADOW, one provider, optional automatic `@EnableAISecurity`, Standalone infrastructure, and Docker startup when available	Ready-to-run local setup with the fewest questions
Custom	Choose Merge/Standalone, FULL/SANDBOX, SHADOW/ENFORCE, providers, Standalone/Distributed/Skip infrastructure, paths, and Docker startup	Host-owned IAM, external infrastructure, or exact deployment requirements

Quick is not dependency-only. Pressing Enter selects Quick. It asks for a provider and automatic annotation, adds the Starter and selected Spring AI dependencies, writes application-contexa.yml, optionally annotates the main class, generates PostgreSQL plus an Ollama Compose service only when Ollama is selected, and starts them when Docker is available. The host application.yml remains unchanged.

--yes default — Ollama, automatic annotation, Standalone PostgreSQL/Ollama infrastructure, and Docker startup when available. Add --no-docker to generate Compose without starting containers.

3. Explicit examples

Shell

contexa init --yes --provider openai --no-docker
contexa init --standalone --security-mode sandbox --provider openai --no-docker
contexa init --yes --distributed --provider openai --no-docker

Merge integration applies selected dependencies and optional source annotation while keeping Contexa configuration in its own overlay. Standalone integration leaves host build, YAML, and source unchanged and produces configuration plus a build fragment for manual wiring. Standalone integration and Standalone infrastructure are different choices.

4. Inspect, simulate, and reset

Shell

contexa status
contexa reset
contexa init --simulate --yes --no-docker
contexa reset --simulate --yes

Simulation requires a project that already has the Starter. Each reset restores only resources in its matching ownership manifest; normal and simulation state remain independent.

Manual dependency-only is separate. If you manually add only ai.ctxa:spring-boot-starter-contexa:0.1.0 without @EnableAISecurity, AI security remains inactive and the host retains authentication, authorization, and SecurityContext ownership. This is not the CLI Quick result.

1

Manual install: add the Starter dependency

If you do not use the CLI, add one Starter dependency from Maven Central. Stable releases need no milestone or snapshot repository beyond mavenCentral().

Gradle (Kotlin DSL)

dependencies {
    implementation("ai.ctxa:spring-boot-starter-contexa:0.1.0")
}

Gradle (Groovy)

dependencies {
    implementation 'ai.ctxa:spring-boot-starter-contexa:0.1.0'
}

Maven

<dependency>
    <groupId>ai.ctxa</groupId>
    <artifactId>spring-boot-starter-contexa</artifactId>
    <version>0.1.0</version>
</dependency>

Optional dependencies — For manual setup, add exactly the provider starter or provider starters you selected and the storage driver required by that path. Do not add unused providers.

2

Optional: enable AI security

Add @EnableAISecurity for manual AI Zero Trust activation. Use SANDBOX when the host owns authentication; Contexa consumes the existing principal as bridge input without replacing host IAM.

Java

@SpringBootApplication
@EnableAISecurity(mode = SecurityMode.SANDBOX)
public class MyApplication {

    public static void main(String[] args) {
        SpringApplication.run(MyApplication.class, args);
    }
}

Ownership contract — Default SANDBOX maps to HOST_OWNED; explicit FULL maps to CONTEXA_OWNED. Keep legacy applications in SANDBOX so Contexa does not replace or modify host IAM.

3

Configure only selected features

Common defaults live in the Starter's *Properties classes. Do not copy settings for unused features into application.yml; configure only the provider, database, or distributed infrastructure you explicitly selected.

YAML

# Manual dependency-only install
# No additional application.yml settings

# Add settings only for explicitly selected AI security, provider,
# database, or distributed infrastructure features.

LLM settings — Configure an API key or local endpoint only after enabling AI security and selecting that provider. Manual dependency-only applications need no LLM settings.

When Ollama is selected — See the AI configuration reference for detailed options. Configure only the runtime and models you actually use.

Advanced provider selection — Multi-provider priority and fallback are not installation requirements. Verify one provider first, then configure fallback only when needed.

4

Run & Verify

Start the host application in its normal way. Verify dependency-only and explicitly activated AI-security states separately.

Shell

# Gradle
./gradlew bootRun

# Maven
mvn spring-boot:run

Verify: Auto-Configuration Report

Run with the --debug flag to see which Contexa auto-configurations were applied:

Shell

./gradlew bootRun --args='--debug'

When @EnableAISecurity is present, verify only the Contexa auto-configurations required by the selected features. In dependency-only state, no Contexa security filter or provider should be active.

Verify: Actuator Health Endpoint

Add spring-boot-starter-actuator to your dependencies if not already present, then check the health endpoint:

Shell

curl http://localhost:8080/actuator/health

Conditional database — Manual dependency-only state does not require a Contexa database. Verify a dedicated PostgreSQL connection and privileges only after enabling persistence, IAM, or vector features. The runtime creates and validates its tables during server startup; the CLI does not create product tables.

Method-Level Security

Protect Your First Method

After explicitly enabling AI security, add @Protectable only to methods that require Zero Trust analysis. sync = true applies the final decision before the method returns; the default sync = false lets the host request proceed while recording asynchronous analysis evidence.

Java

@Service
public class OrderService {

    @Protectable
    public Order getOrder(Long orderId) {
        return orderRepository.findById(orderId)
                .orElseThrow(() -> new OrderNotFoundException(orderId));
    }
}

Database policy contract — Access decisions combine active, approved database policies that apply to the resource. When no database policy applies to that resource, the Contexa policy layer permits by default; the host application's existing authentication and authorization continue independently.

@Protectable Attributes

Attribute	Type	Default	Description
`ownerField`	`String`	`""`	Field name on the return type used to identify the resource owner for ownership-based authorization checks.
`sync`	`boolean`	`false`	When `true`, the Zero Trust evaluation completes synchronously before the method returns. When `false` (default), evaluation runs asynchronously and the method proceeds immediately.

AI Decisions

What Happens Next — Zero Trust Actions

Every request evaluated by Contexa produces one of the following ZeroTrustAction decisions. The AI engine determines the appropriate action based on behavioral analysis, threat assessment, and trust scoring.

Action	HTTP Status	TTL	Behavior
`ALLOW`	200	15s	Request proceeds normally
`BLOCK`	403	Permanent	Request is denied; user receives `ROLE_BLOCKED`
`CHALLENGE`	401	1800s	Additional authentication required (MFA); user receives `ROLE_MFA_REQUIRED`
`ESCALATE`	423	300s	Request held for manual review; user receives `ROLE_REVIEW_REQUIRED`
`PENDING_ANALYSIS`	503	0s	AI analysis in progress; user receives `ROLE_PENDING_ANALYSIS` and request is deferred until evaluation completes

AI-Driven Decisions — Unlike traditional rule-based systems, Contexa's LLM engine determines the appropriate action for each request based on real-time behavioral analysis. No static rules to configure — the AI learns and adapts to your application's traffic patterns.

Next Steps

Explore the full documentation to learn about advanced features, configuration options, and architecture details.

Get Started

Prerequisites

Optional: Database setup

Optional: Ollama models

Recommended: initialize with the CLI

1. Install and verify the CLI

2. Choose Quick or Custom

3. Explicit examples

4. Inspect, simulate, and reset

Manual install: add the Starter dependency

Optional: enable AI security

Configure only selected features

Run & Verify

Verify: Auto-Configuration Report

Verify: Actuator Health Endpoint

Protect Your First Method

@Protectable Attributes

What Happens Next — Zero Trust Actions

Next Steps

Spring Boot Integration

Core — AI Engine

Zero Trust Architecture

@Protectable Reference

Configuration Reference

Shadow Mode Guide