agent-backend

AI Chat Agent backend service for Vultisig mobile apps. Handles natural language conversations using LLMs via OpenRouter and coordinates with Vultisig plugins via the MCP server.

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
JWT_SECRET	Yes	-	HMAC-SHA256 secret for JWT issuance and validation
JWT_TTL_HOURS	No	24	JWT token lifetime in hours
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
MCP_SERVER_URL	Yes	-	Vultisig MCP server URL (tools + skills)
VERIFIER_URL	No	""	Verifier service base URL (optional; only for plugin skills)
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 JWT_SECRET="replace-with-strong-random-secret"
export AI_API_KEY="sk-or-v1-..."
export MCP_SERVER_URL="http://localhost:8081"

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 JWT_SECRET="replace-with-strong-random-secret" \
  -e AI_API_KEY="sk-or-v1-..." \
  -e MCP_SERVER_URL="http://mcp-server: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	Auth	Description
GET	/healthz	None	Health check
POST	/auth/token	None	Vault ECDSA signature → JWT
POST	/agent/conversations	JWT	Create conversation
POST	/agent/conversations/list	JWT	List conversations
POST	/agent/conversations/:id	JWT	Get conversation
POST	/agent/conversations/:id/messages	JWT	Send message
DELETE	/agent/conversations/:id	JWT	Delete conversation

Development

Run tests:

make test

Run linter:

make lint

Architecture

cmd/server/          # Main entrypoint
cmd/scheduler/       # Scheduler entrypoint
internal/
  api/               # HTTP handlers, middleware, auth
  auth/              # Local JWT issuance and validation
  service/           # Business logic layer
  storage/postgres/  # PostgreSQL repositories + migrations
  cache/redis/       # Redis caching
  ai/                # AI client (OpenRouter-compatible)
  mcp/               # Internal MCP client
  config/            # Configuration loading
  types/             # Shared types