system-docs/02_COMPONENTES/internos/captain_claude_api_v3.md

Captain Claude API v3

API para interactuar con Claude Code desde aplicaciones móviles/web.

Información General

Campo	Valor
Servidor	ARCHITECT (69.62.126.110)
Puerto	3030
Protocolo	HTTP + WebSocket
Dominio externo	captain.tzzrarchitect.me
Ubicación código	/home/architect/captain-claude/apps/captain-mobile-v2/backend/captain_api_v3.py

Autenticación

JWT Bearer Token. Obtener via /auth/login.

curl -X POST https://captain.tzzrarchitect.me/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"***"}'

Respuesta:

{
  "token": "eyJ...",
  "username": "admin"
}

Endpoints REST

GET /health

Estado del servicio.

{"status": "ok", "version": "3.0.0"}

POST /auth/login

Autenticación.

Request:

{
  "username": "string",
  "password": "string"
}

Response:

{
  "token": "string",
  "username": "string"
}

GET /sessions

Lista sesiones activas. Requiere Bearer token.

Response:

[
  {
    "session_id": "abc123...",
    "name": "Mi sesión"
  }
]

POST /sessions

Crear nueva sesión. Requiere Bearer token.

Request:

{
  "name": "Nombre de la sesión"
}

Response:

{
  "session_id": "abc123...",
  "name": "Nombre de la sesión"
}

WebSocket

Endpoint

wss://captain.tzzrarchitect.me/ws/chat

Flujo de conexión

1. Conectar al WebSocket
2. Enviar autenticación:

   {"type": "auth", "token": "eyJ..."}
   

3. Recibir confirmación con sesiones existentes:

   {
     "type": "init",
     "sessions": [{"session_id": "...", "name": "..."}]
   }
   

Mensajes Cliente → Servidor

Crear sesión

{
  "type": "create_session",
  "name": "Nombre de la sesión"
}

Conectar a sesión existente

{
  "type": "connect_session",
  "session_id": "abc123..."
}

Enviar mensaje a Claude

{
  "type": "message",
  "content": "Hola Claude"
}

Mensajes Servidor → Cliente

Sesión creada

{
  "type": "session_created",
  "session_id": "abc123...",
  "name": "Nombre"
}

Conectado a sesión

{
  "type": "session_connected",
  "session_id": "abc123...",
  "name": "Nombre"
}

Output de Claude (streaming)

{
  "type": "output",
  "content": "Texto de respuesta..."
}

Respuesta completada

{
  "type": "done",
  "session_id": "uuid-de-claude"
}

Error

{
  "type": "error",
  "message": "Descripción del error"
}

Arquitectura

┌─────────────┐     HTTPS/WSS      ┌─────────────┐
│ App Móvil   │ ◄────────────────► │ Caddy       │
│ (Flutter)   │                    │ (reverse    │
└─────────────┘                    │  proxy)     │
                                   └──────┬──────┘
                                          │ :3030
                                   ┌──────▼──────┐
                                   │ Captain API │
                                   │ v3 (uvicorn)│
                                   └──────┬──────┘
                                          │ subprocess
                                   ┌──────▼──────┐
                                   │ Claude Code │
                                   │ (claude -p) │
                                   └─────────────┘

Notas

• Sin screen: v3 usa claude -p directamente como subprocess, no sesiones screen
• Session ID: El session_id inicial es temporal. Después del primer mensaje, se actualiza con el UUID real de Claude para poder hacer --resume
• Streaming: Las respuestas se envían en tiempo real vía WebSocket
• Concurrencia: Una sesión solo procesa un mensaje a la vez

Servicio systemd

[Unit]
Description=Captain Claude API v3
After=network.target

[Service]
Type=simple
User=architect
WorkingDirectory=/home/architect/captain-claude/apps/captain-mobile-v2/backend
ExecStart=/home/architect/captain-claude/apps/captain-mobile-v2/backend/venv/bin/uvicorn captain_api_v3:app --host 0.0.0.0 --port 3030
Restart=always

[Install]
WantedBy=multi-user.target

---

Última actualización: 2026-01-21