AI Keyholder

Overview

The AI Keyholder is an automated keyholder powered by large language models (LLMs). It maintains the dominant-submissive dynamic while managing your chastity session through chat interactions. The AI can add/remove time, assign tasks, request verification photos and execute shocks.

Capabilities

Capability	Description
Chat	Natural conversation with persona-based responses
Time Control	Add time, remove time, or freeze the lock
Card Game	Add red cards to the deck
Task Assignment	Assign predefined tasks from your lock's task module
Photo Verification	Request verification photos (requires vision-enabled model)
Shocks	Execute shocks on supported devices (Cellmate Pro 3 or Cagink Metal Shake)

Available Commands

The AI can use these commands during chat:

Command	Effect
{'{add30m}'}, {'{add1h}'}, {'{add2h}'}, {'{add3h}'}, {'{add4h}'}, {'{add5h}'}, {'{add6h}'}	Add time to lock
{'{remove30m}'}, {'{remove1h}'}, {'{remove2h}'}, {'{remove3h}'}	Remove time (requires time adjustment enabled)
{'{add1redcard}'}, {'{add2redcard}'}, {'{add3redcard}'}	Add red cards to deck
{'{freeze1h}'}, {'{freeze2h}'}, {'{freeze3h}'}, {'{freeze6h}'}, {'{freeze12h}'}	Freeze the timer
{'{task=title}'}	Assign a predefined task (requires task module)
{'{shock:SECONDS}'}	Send shock/vibration (30-300s, requires supported device + consent)
{'{request_verification}'}	Request a verification photo (requires vision-enabled model)

Model Setup

OpenRouter (Recommended)

You need your own OpenRouter API key. It is encrypted and stored securely in the database.

• Supports many models including GPT, Claude, Gemini, and open-source alternatives
• Vision support available on many models for photo verification

Self-Hosted (LM Studio / Ollama)

Run models locally for privacy and cost savings.

1. Start your model in LM Studio or Ollama
2. Use a tunnel service to expose it without port forwarding:
   • Cloudflare Tunnel: cloudflare tunnel --url http://localhost:1234
   • ms.devtools: Alternative tunneling solution
3. Enter the tunnel URL in the AI Keyholder setup

Enabling the AI Keyholder

When you enable the AI Keyholder, the system performs a connection check to verify your API endpoint is accessible:

• Success: The AI Keyholder is enabled and sends a greeting message that appears in the chat modal
• If you don't see the greeting: Reload the page - the message arrives and is saved to DB but sometimes the realtime socket event doesn't arrive

Model Requirements

The AI Keyholder requires a model with strong instruction-following capabilities:

• Instruction Following: The model must follow complex instructions to use command syntax correctly (e.g., {'{add1h}'} )
• Character Consistency: The model needs to maintain persona without breaking character or leaking system prompts
• Minimum Size: Models below 30B parameters often struggle with these requirements and may:
  • Reveal internal instructions or system prompts in messages
  • Expose command syntax to the user
  • Break character and meta-comment on its role
  • Fail to use commands properly

Recommended models (30B+ or high-quality commercial APIs):

OpenRouter (Cloud):

• Claude, GPT, Gemini (best instruction following but may refuse to engage in NSFW chats)
• Llama 3.1 70B Instruct
• Qwen 2.5 32B Instruct
• Any high-quality model with strong instruction following but which also engages in NSFW chats

Local (Self-Hosted):

• Qwen 2.5 32B Instruct or Qwen 3 Coder 30B (recommended)
• Llama 3.1 70B Instruct
• mistral-small-3.2-24b-instruct-2506 (excellent vision + text, correctly verifies chastity status)

Models that will underperform:

• 7B, 11B, 13B models will definitely struggle with command syntax and character consistency

Hardware Requirements:

• 24B models (e.g., mistral-small-3.2-24b): RTX 5080 with 16GB VRAM but still struggles a little
• 30B+ models: RTX 5090 with 24GB VRAM required

Prompt Optimization

The AI Keyholder uses smart prompt optimization to reduce token usage and costs. It alternates between full and minimal system prompts.

When Full Prompts Are Sent

A full prompt (500-800 tokens) is sent when:

• Prompt optimization is disabled
• It's a new session or first message
• Configuration changed (persona, intensity, name)
• Last full prompt was more than 6 hours ago
• More than 12 messages since last full prompt

Full prompts include: complete persona description, intensity modifiers, all rules, command examples, scenarios, and game state.

When Minimal Prompts Are Sent

A minimal prompt (150-250 tokens) is sent when:

• Prompt optimization is enabled
• Same session with unchanged configuration
• Last full prompt was less than 6 hours ago
• 12 or fewer messages since last full prompt

Minimal prompts include: persona name, basic rules, command list, and current game state.

Adaptive Ratio

The system tracks the ratio of full to minimal prompts. If too few full prompts are sent (ratio below 30%), it forces a full prompt earlier to maintain quality.

Token Savings

Prompt optimization saves approximately 60-70% on input tokens during active conversations while maintaining the AI's behavior and responsiveness.

Safety & Limits

Command Limits

These are the limits which are enforced by the command parser, even if the AI keyholder adds more it will be capped by these values.

Command	Per Command	Per Day	Cooldown
Add Time	Max 6 hours	12h (soft) / 24h (medium) / 48h (hard)	5 min
Remove Time	Max 12 hours	10 commands	10 min
Add Red Cards	Max 3 cards	15 commands	10 min
Freeze	Max 12 hours	1 command	30 min
Shock	30-300 seconds	50 commands	30 sec
Verification	-	3 requests	2 hours
Task Assignment	-	3 assignments	1 hour

Device Control Safety

• Explicit Consent Required: Shock commands require user consent
• Native Socket Check: Requires active Android app connection for shock delivery

Image Verification

Currently image verification is only for lock verification (verifying the wearer is locked in chastity), not for task completion.

The AI uses a strict verification prompt:

You are a strict Task Verification Officer.
You will receive an image and a task description.
You must output JSON only.
Return: {"verified": boolean, "reason": string, "message": string}

How Images Are Sent:

Provider	Image Format	Description
OpenAI	URL	Direct URL passed to API
OpenRouter	URL	Direct URL passed to API
Local (LM Studio/Ollama)	Base64	Image fetched, converted to base64, sent as data URL

The system uses OpenAI-compatible vision format:

{
  "role": "user",
  "content": [
    { "type": "text", "text": "task description here" },
    { "type": "image_url", "image_url": { "url": "..." } }
  ]
}

Image Processing:

• WebP images automatically converted to JPEG (90% quality)
• Self-hosted models: image fetched and encoded as base64 data URL
• Response format: JSON object with verified, reason, and message fields

Requirements:

• Vision-enabled model (e.g., mistral-small-3.2-24b-instruct-2506)
• The model analyzes the uploaded image and returns structured JSON
• Used with the {'{request_verification}'} command

Note: Task verification (verifying completed tasks) is not currently supported.