Skip to main content
HandsAI is a Spring Boot application built with Java 21 that requires minimal setup. The database is automatically configured using SQLite, so you can get started immediately.

​
Prerequisites

Before installing HandsAI, ensure you have the following installed:
1

Java 21 LTS

HandsAI requires Java 21 LTS or later. Verify your installation:
java -version
You should see output indicating Java 21 or higher. Download from Oracle or Adoptium.
2

Maven 3.8+

Apache Maven 3.8 or later is required for building the project.
mvn -version
Download from Apache Maven if needed.
HandsAI includes a Maven wrapper (./mvnw), so you can skip this step if you prefer to use the wrapper.
3

GraalVM (Optional)

For native compilation and ultra-fast startup times (< 1.5s), install GraalVM 21:
# Verify GraalVM installation
native-image --version
See GraalVM Native Compilation for detailed instructions.

​
Installation Steps

1

Clone the Repository

Clone the HandsAI repository from GitHub:
git clone https://github.com/Vrivaans/handsaiv3.git
cd handsaiv3
2

Database Setup (Automatic)

HandsAI uses SQLite with zero configuration required. On first run, the application automatically creates a handsai.db file in the project root directory.The database is configured with:
  • WAL Mode (Write-Ahead Logging) for high concurrency
  • Batch Processing for optimal performance
  • 5-second busy timeout to handle concurrent requests
No manual database installation or configuration is needed. SQLite is embedded and managed automatically.
3

Run with Maven

Start HandsAI using the Maven wrapper:
./mvnw spring-boot:run
The application will:
  1. Download all dependencies (first run only)
  2. Create the SQLite database if it doesn’t exist
  3. Start the Spring Boot application
  4. Listen on http://localhost:8080
You should see output similar to:
Started Handsaiv2Application in 3.456 seconds (process running for 3.789)
4

Verify Installation

Open your browser and navigate to:
http://localhost:8080
You should see the HandsAI web interface with the tool management dashboard.
Test the MCP API endpoint at http://localhost:8080/mcp/tools/list to verify the API is responding.

​
Docker Installation (Alternative)

If you prefer to run HandsAI in a container: 
# Build stage
FROM maven:3.9.6-eclipse-temurin-21-alpine AS build
WORKDIR /app
COPY pom.xml .
COPY src ./src
RUN mvn clean package -DskipTests

# Run stage
FROM eclipse-temurin:21-jre-alpine
WORKDIR /app
COPY --from=build /app/target/*.jar app.jar
EXPOSE 8080
ENTRYPOINT ["java", "-jar", "app.jar"]
Build and run: 
# Build the Docker image
docker build -t handsai:latest .

# Run the container
docker run -p 8080:8080 -v $(pwd)/handsai.db:/app/handsai.db handsai:latest
When running in Docker, mount a volume for handsai.db to persist your tool configurations between container restarts.

​
What’s Next?

Configuration

Configure database settings, encryption, and server options

Bridge Setup

Connect HandsAI to Claude Desktop, VS Code, or other MCP clients

Native Compilation

Build a native executable for sub-second startup times

Quickstart

Register your first API and start using tools

Build docs developers (and LLMs) love

Get started for freeTalk to us