Installation Guide

CLI installation and project initialization

Install the signed CLI, run it from the Spring Boot project, and select Quick or Custom. Every path shows the planned files, dependencies, infrastructure, and Docker action before mutation.

Step 1 - Install the CLI

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

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

Step 2 - Diagnose and initialize

cd your-spring-project
contexa init --check   # optional, read-only
contexa init

Step 3 - Understand generated state

• Merge: updates the build, writes application-contexa.yml, and changes the main source only when automatic annotation was selected. The host application.yml is preserved.
• Standalone integration: writes Contexa YAML and a Gradle/Maven fragment in a separate directory. Host build, YAML, and source remain unchanged; the user wires the generated fragment.
• Standalone infrastructure: PostgreSQL plus Ollama only when Ollama is among the selected providers.
• Distributed infrastructure: PostgreSQL, Redis, ZooKeeper, Kafka, plus Ollama only when selected.
• Skip infrastructure: no Compose file and no Docker mutation.

Step 4 - Run, inspect, and reset

./gradlew bootRun
contexa status
contexa reset

reset restores only CLI-owned state recorded by the manifest. It does not silently overwrite a user-modified file or remove unrelated infrastructure.

Legacy System Integration (SANDBOX Mode)

If the project already owns authentication and authorization, use SANDBOX/HOST_OWNED. Contexa receives the authenticated host principal through the bridge and runs its Zero Trust runtime independently.

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

Contexa CLI Command Reference

Detailed overview of the primary commands provided by the Contexa CLI. You can execute them in your terminal via contexa <command> [options].

Prerequisites

Required for both CLI and manual installation:

Manual Installation

If you prefer not to use the CLI, use the stable artifacts from Maven Central. A normal consumer build needs only mavenCentral().

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. Configure only selected features

The Starter provides common defaults through auto-configuration. Manual dependency-only integration needs no provider, database, or Docker configuration. Add those items only when you activate the corresponding feature.

Troubleshooting

@EnableAISecurity startup error guide

You may hit the following errors if you add @EnableAISecurity to a manual dependency-only integration, select external infrastructure in Custom but omit required provider or database settings, or remove generated configuration. Quick generates the selected provider dependency, source annotation, and Standalone database configuration together. Each error below shows the exact message, root cause, and fix.

Error 1 — contexa.datasource.url must be configured for @EnableAISecurity

Root cause — Contexa stores security policy, sessions and the vector index in a dedicated PostgreSQL instance, isolated from your application database. When @EnableAISecurity is on, contexa.datasource.url must be set or ContexaDataSourceIsolation fails fast.

Fix — add a Contexa-owned datasource block to your application.yml:

contexa:
  datasource:
    url: jdbc:postgresql://localhost:5432/contexa
    username: ${CONTEXA_DB_USERNAME:contexa}
    password: ${CONTEXA_DB_PASSWORD:contexa1234!@#}
    driver-class-name: org.postgresql.Driver
    isolation:
      contexa-owned-application: true

You may share the application's PostgreSQL instance via a separate schema if your operations team explicitly approves it. The default is a separate database (recommended).

Error 2 — No Spring AI ChatModel is configured for CONTEXA

Root cause — Contexa's tiered LLM auto-configuration (CoreLLMTieredAutoConfiguration) requires a ChatModel bean, but no Spring AI provider starter is on the classpath. spring-boot-starter-contexa intentionally does not pull a ChatModel starter as a transitive dependency — the choice of provider (Ollama / OpenAI / Anthropic) is yours.

Fix — add at least one provider starter to your build and configure the matching contexa.llm.* block (Contexa bypasses Spring AI's default autoconfiguration and manages model creation via its dedicated contexa.llm namespace):

dependencies {
    implementation 'ai.ctxa:spring-boot-starter-contexa:0.1.0'
    // Add only when you declare @EnableAISecurity (one provider or more)
    implementation 'org.springframework.ai:spring-ai-starter-model-ollama'
}

contexa:
  llm:
    selection:
      chat:
        mode: dynamic-priority
        priority: ollama,openai,anthropic
    chat:
      ollama:
        baseUrl: ${CONTEXA_CHAT_OLLAMA_BASE_URL:http://127.0.0.1:11434}
        model: ${CONTEXA_CHAT_OLLAMA_MODEL:qwen2.5:7b}
        keepAlive: ${CONTEXA_OLLAMA_CHAT_KEEP_ALIVE:30m}
    embedding:
      ollama:
        dedicatedRuntimeEnabled: false
        model: ${CONTEXA_EMBEDDING_OLLAMA_MODEL:mxbai-embed-large}
        dimensions: ${CONTEXA_EMBEDDING_OLLAMA_DIMENSIONS:1024}

For OpenAI or Anthropic, swap in spring-ai-starter-model-openai / spring-ai-starter-model-anthropic and set the API key under contexa.llm.openai.* / contexa.llm.anthropic.*.

Error 3 — rag-vector capability unresolved / SecurityDecisionPostProcessor not created

Root cause — the @EnableAISecurity decision post-processor (SecurityDecisionPostProcessor) depends on UnifiedVectorService, which in turn requires a Spring AI VectorStore bean. Without the pgvector vector-store starter on the classpath, the rag-vector capability stays unresolved and the downstream bean tree never wires up.

Fix — add the pgvector vector-store starter and configure contexa.vectorstore.pgvector.*. Use the pgvector/pgvector:pg16 Docker image so the vector extension is enabled out of the box.

dependencies {
    implementation 'org.springframework.ai:spring-ai-starter-vector-store-pgvector'
}

contexa:
  vectorstore:
    pgvector:
      dimensions: 1024
      initialize-schema: true

Infrastructure issues

Container name conflict — The container name "/contexa-postgres" is already in use

Root cause — a container with the same name (contexa-postgres, contexa-ollama, ...) already exists on the host. The Docker daemon does not allow two containers to share a name. Two common cases:

• A previous contexa init run left those containers up — safe to reuse as-is.
• Another project occupies the same name — clean it up, or switch to the isolated simulate mode.

Option 1 — keep the existing containers (recommended, preserves data)

# 1) confirm the containers are running
docker ps --filter "name=contexa-" --format "table {{.Names}}\t{{.Status}}"

# 2) leave them up and just start the app
./gradlew bootRun

Option 2 — remove and recreate (DATA LOSS WARNING)

# Stop + remove (volumes are preserved)
docker rm -f contexa-postgres contexa-ollama
# Distributed mode also needs:
docker rm -f contexa-redis contexa-zookeeper contexa-kafka

# Recreate
contexa init --distributed

Option 3 — switch to the isolated simulation mode (protects production containers)

contexa init --simulate

--simulate namespaces the containers under the ctxa-sim- prefix and shifts ports by +20000, so the simulation stack runs side-by-side with production without colliding.