agent-backend

AI Chat Agent backend service for Vultisig mobile apps. This service handles natural language conversations using LLMs via OpenRouter and coordinates with existing Vultisig plugins (app-recurring, feeplugin) via the verifier.

Prerequisites

• Go 1.25+
• PostgreSQL 14+
• Redis 6+
• Docker (optional, for containerized deployment)

Environment Variables

Variable	Required	Default	Description
SERVER_HOST	No	0.0.0.0	Server bind address
SERVER_PORT	No	8080	Server port
DATABASE_DSN	Yes	-	PostgreSQL connection string
REDIS_URI	Yes	-	Redis connection URI
AUTH_CACHE_KEY_SECRET	Yes	-	HMAC secret for auth cache key derivation
AUTH_CACHE_TTL_SECONDS	No	180	Auth cache TTL (seconds)
AI_API_KEY	Yes	-	OpenRouter API key
AI_MODEL	No	anthropic/claude-sonnet-4.5	Model to use (OpenRouter format)
AI_SUMMARY_MODEL	No	anthropic/claude-haiku-4.5	Model for conversation summarization
AI_BASE_URL	No	https://openrouter.ai/api/v1	AI provider base URL
AI_APP_NAME	No	vultisig-agent	App name sent to OpenRouter
AI_APP_URL	No	-	App URL sent to OpenRouter
VERIFIER_URL	Yes	-	Verifier service base URL
LOG_FORMAT	No	json	Log format (json or text)

Running Locally

1. Set required environment variables:

export DATABASE_DSN="postgres://user:pass@localhost:5432/agent?sslmode=disable"
export REDIS_URI="redis://localhost:6379"
export AUTH_CACHE_KEY_SECRET="replace-with-strong-random-secret"
export AI_API_KEY="sk-or-v1-..."
export VERIFIER_URL="http://localhost:8080"

2. Run the server:

make run

Or build and run:

make build
./bin/server

Docker

Build the Docker image:

make docker-build

Run with Docker:

docker run -p 8080:8080 \
  -e DATABASE_DSN="postgres://..." \
  -e REDIS_URI="redis://..." \
  -e AI_API_KEY="sk-or-v1-..." \
  -e VERIFIER_URL="http://verifier:8080" \
  agent-backend:latest

Database Migrations

Run migrations:

export DATABASE_DSN="postgres://user:pass@localhost:5432/agent?sslmode=disable"
make migrate-up

Rollback:

make migrate-down

API Endpoints

Method	Path	Description
GET	/healthz	Health check
POST	/agent/conversations	Create conversation
POST	/agent/conversations/list	List conversations
POST	/agent/conversations/:id	Get conversation
POST	/agent/conversations/:id/messages	Send message
DELETE	/agent/conversations/:id	Delete conversation

Development

Run tests:

make test

Run linter:

make lint

Architecture

cmd/server/          # Main entrypoint
internal/
  api/               # HTTP handlers and middleware
  service/           # Business logic layer
  storage/postgres/  # PostgreSQL repositories + migrations
  cache/redis/       # Redis caching
  ai/               # AI client (OpenRouter-compatible)
  config/            # Configuration loading
  types/             # Shared types