Installation Guide

Quick Install (Recommended)

Install the Contexa CLI and set up everything automatically with a single command.

Step 1 - Install CLI

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

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

Step 2 - Initialize your project

cd your-spring-project
contexa init

The CLI will guide you through an interactive setup:

• Project type - New project (FULL) or legacy system (SANDBOX)
• AI security mode - Monitor only or block threats immediately
• AI / LLM Model - Ollama (local), OpenAI, or Anthropic
• Infrastructure - Standard (PostgreSQL + Ollama) or Distributed (+ Redis + Kafka)

The CLI automatically:

• Adds spring-boot-starter-contexa dependency to your build file
• Configures application.yml with the correct settings
• Generates docker-compose.yml for infrastructure
• Starts Docker containers and pulls AI models

Step 3 - Add annotations

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

// Protect any endpoint with AI Zero Trust
@Protectable
@GetMapping("/api/customers")
public List<Customer> getCustomers() { ... }

Step 4 - Start your application

./gradlew bootRun

Legacy System Integration (SANDBOX Mode)

If your project already has its own authentication system, use SANDBOX mode. Contexa adds AI security on top of your existing login — without modifying it.

@EnableAISecurity(
    mode = SecurityMode.SANDBOX,
    authObjectLocation = AuthObjectLocation.SESSION,
    authObjectAttribute = "loginUser"  // your legacy session attribute name
)
@SpringBootApplication
public class LegacyApplication { }

Prerequisites

Required for both CLI and manual installation:

Manual Installation

If you prefer not to use the CLI, follow these steps manually.

1. Add Dependency

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

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

2. Start Infrastructure

# Standard mode (PostgreSQL + Ollama)
docker compose up -d

# Distributed mode (+ Redis + Kafka)
docker compose --profile distributed up -d

# Pull AI models
docker exec contexa-ollama ollama pull qwen3.5:9b
docker exec contexa-ollama ollama pull mxbai-embed-large

3. Infrastructure Services

Troubleshooting