Skip to main content
HandsAI is configured through src/main/resources/application.properties. All settings have sensible defaults for local development.

​
Database Configuration

HandsAI uses SQLite as its embedded database with optimizations for concurrent access.
​
spring.datasource.url
string
SQLite database connection URL. The database file is created in the project root.Parameters:
  • journal_mode=WAL - Write-Ahead Logging for better concurrency
  • busy_timeout=5000 - 5-second timeout when database is locked
​
spring.datasource.driver-class-name
string
default:"org.sqlite.JDBC"
JDBC driver class for SQLite. Should not be modified.
​
spring.jpa.database-platform
string
default:"org.hibernate.community.dialect.SQLiteDialect"
Hibernate dialect for SQLite. Enables JPA compatibility with SQLite.
​
spring.jpa.hibernate.ddl-auto
string
default:"update"
Schema generation strategy. Options:
  • update - Update schema automatically (recommended for development)
  • create - Drop and recreate schema on startup
  • validate - Validate schema without changes
  • none - No schema management
​
spring.jpa.show-sql
boolean
default:"false"
Enable to log all SQL statements to console. Useful for debugging.

​
Connection Pool Settings

HandsAI uses HikariCP for database connection pooling:
​
spring.datasource.hikari.maximum-pool-size
number
default:"20"
Maximum number of connections in the pool. Increase for high-concurrency scenarios.
​
spring.datasource.hikari.minimum-idle
number
default:"5"
Minimum number of idle connections maintained in the pool.
​
spring.datasource.hikari.idle-timeout
number
default:"300000"
Maximum time (in milliseconds) that a connection can sit idle in the pool. Default: 5 minutes.
​
spring.datasource.hikari.max-lifetime
number
default:"600000"
Maximum lifetime (in milliseconds) of a connection in the pool. Default: 10 minutes.
​
spring.datasource.hikari.connection-timeout
number
default:"30000"
Maximum time (in milliseconds) to wait for a connection from the pool. Default: 30 seconds.

​
Server Configuration

​
spring.application.name
string
default:"handsaiv2"
Application name used in logs and Spring Boot actuators.
​
server.port
number
default:"8080"
HTTP port for the HandsAI server. Change if port 8080 is already in use.
server.port=8081

​
Encryption Configuration (Jasypt)

HandsAI uses Jasypt to encrypt sensitive values like API keys stored in the database.
​
jasypt.encryptor.password
string
default:"handsai-secret-key"
Master password for encrypting/decrypting sensitive data.
Change this in production! Set via environment variable:
export JASYPT_ENCRYPTOR_PASSWORD="your-secure-password-here"
./mvnw spring-boot:run
​
jasypt.encryptor.algorithm
string
default:"PBEWithMD5AndDES"
Encryption algorithm used by Jasypt. Should not be changed unless you have specific security requirements.
​
jasypt.encryptor.iv-generator-classname
string
default:"org.jasypt.iv.NoIvGenerator"
Initialization vector generator. Required for GraalVM compatibility.

​
Virtual Threads Configuration

HandsAI leverages Java 21’s virtual threads for high concurrency and scalability.
​
spring.threads.virtual.enabled
boolean
default:"true"
Enables virtual threads for all Spring Boot managed thread pools.Benefits:
  • Thousands of concurrent tool executions
  • Lower memory overhead per request
  • Better throughput for I/O-bound operations
Virtual threads are a Java 21+ feature. Do not disable unless you have compatibility issues.

​
Security Configuration

​
security.ssrf.allow-private-networks
boolean
default:"false"
Controls whether tools can call private network addresses (localhost, 192.168.x.x, 10.x.x.x, etc.).Set to true if you need to call APIs running on your local network:
security.ssrf.allow-private-networks=true
Enabling this can expose your internal network to SSRF attacks if malicious tool definitions are imported.

​
Logging Configuration

Customize logging levels for debugging and monitoring:
​
logging.level.org.springframework.orm.jpa
string
default:"INFO"
Spring Data JPA logging level.
​
logging.level.org.hibernate.SQL
string
default:"DEBUG"
SQL statement logging. Set to INFO or WARN in production to reduce log noise.
​
logging.level.org.hibernate.type.descriptor.sql.BasicBinder
string
default:"TRACE"
SQL parameter binding logging. Shows actual values passed to queries. Set to INFO in production.
logging.level.org.springframework.orm.jpa=WARN
logging.level.org.hibernate.SQL=WARN
logging.level.org.hibernate.type.descriptor.sql.BasicBinder=WARN
logging.level.org.dynamcorp.handsaiv2=INFO

​
Environment Variables

Sensitive configuration values should be set via environment variables: 
# Encryption password
export JASYPT_ENCRYPTOR_PASSWORD="your-production-secret"

# Custom database location
export SPRING_DATASOURCE_URL="jdbc:sqlite:/var/handsai/production.db?journal_mode=WAL&busy_timeout=5000"

# Custom port
export SERVER_PORT=8081

# Run HandsAI
./mvnw spring-boot:run

​
Configuration Examples

​
Development Configuration

Optimal for local development with verbose logging: 
spring.jpa.show-sql=true
logging.level.org.hibernate.SQL=DEBUG
security.ssrf.allow-private-networks=true
server.port=8080

​
Production Configuration

Optimized for production with minimal logging: 
spring.jpa.show-sql=false
logging.level.org.hibernate.SQL=WARN
security.ssrf.allow-private-networks=false
server.port=8080
jasypt.encryptor.password=${JASYPT_ENCRYPTOR_PASSWORD}

​
High-Concurrency Configuration

For scenarios with many concurrent tool executions: 
spring.datasource.hikari.maximum-pool-size=50
spring.datasource.hikari.minimum-idle=10
spring.threads.virtual.enabled=true

​
Troubleshooting

Increase the busy timeout:
spring.datasource.url=jdbc:sqlite:handsai.db?journal_mode=WAL&busy_timeout=10000
Or increase the connection pool size:
spring.datasource.hikari.maximum-pool-size=30
Change the server port:
server.port=8081
Or set via environment variable:
export SERVER_PORT=8081
./mvnw spring-boot:run
Ensure the JASYPT_ENCRYPTOR_PASSWORD environment variable matches the password used to encrypt the data:
export JASYPT_ENCRYPTOR_PASSWORD="your-original-password"

​
What’s Next?

Bridge Setup

Connect HandsAI to MCP clients like Claude Desktop

GraalVM Native

Compile to a native executable for instant startup

Build docs developers (and LLMs) love

Get started for freeTalk to us