Playbook P0 Prerrequisitos E2E

01

Arquitectura del ecosistema

El ecosistema mks-agentics tiene 5 componentes que deben estar vivos para los playbooks. Este diagrama muestra las conexiones entre ellos y por dónde fluye cada use case.

drag to pan · scroll to zoom · double-click to fit

1

Broker públicobroker.gateway.mks2508.systems · OIDC auth · SQLite peers/teams/inbox

prod vivo

API REST + WebSocket

/api/peers · /api/teams · /api/spawn · /api/runners · /ws/runner/:id · /ws/broker/peer/:id

AuthOIDC JWT + BROKER_ALLOWED_CLIENTS

Peersregister · unregister · message · inbox · status

Spawnspawn_order → runner → cliLauncher.launch()

Eventsring buffer 500 · metrics · healthz

https://broker.gateway.mks2508.systems/healthz

Workloads → Channels WSMCP tools RESTSpawn-plane routing

2

Workspace containerlab1-helsinki.api.mks2508.systems · Coolify project code-env

configurado

Container Docker con supervisord

entrypoint.sh → 17 setup functions → supervisord (gateway + codeserver + sshd + desktop)

Gatewaypull-on-startup desde GitHub Releases

gateway-server.js (bundle)
update-gateway.sh (baked)
supervisord autorestart=true

a2a-mcppull-on-startup desde GitHub Releases

a2a-mcp.js (bundle)
update-a2a-mcp.sh (baked)
wrapper /usr/local/bin/a2a-mcp

Claude Codebaked en imagen · multi-provider API keys

https://lab1-helsinki.api.mks2508.systems

Workloads → code-server :8443gateway-server :3456SSH :2222RDP :3389

3

Gateway-proxy públicoproxy.gateway.mks2508.systems · multi-provider · OIDC auth

prod vivo

Proxy HTTP multi-provider

Data-plane /v1/messages + Control-plane /v1/keys · /v1/usage · /auth/*

ProvidersGLM (z.ai) · MiniMax · DeepSeek

anthropic-native protocol
routing por model name + prefix

AuthVirtual keys sk-mks-* + OIDC admin session

SHA-256 hash storage
atomic writes chmod 600

Usagetracking tokens · quotas · rate limiting

https://proxy.gateway.mks2508.systems/health

Workloads → Tier-1 (usuarios auth)Tier-2 (público con rate limit)

02

F1 — Verificar broker público

5 min

Broker health + autenticación

curl -s https://broker.gateway.mks2508.systems/healthz → 200 OK Health check público sin auth
curl -s https://broker.gateway.mks2508.systems/api/peers → 401 Sin token JWT → rechazado
OIDC client_credentials → JWT válido → GET /api/peers → 200 + JSON array Con token JWT → autorizado
GET /api/runners → lista de runners conectados Verificar que hay al menos un runner (workspace container)

Verificación broker

Verificación broker público

# Health check público
$ curl -s https://broker.gateway.mks2508.systems/healthz | jq .
→ {"status":"ok","uptime":3600}

# Auth requerido para API
$ curl -s https://broker.gateway.mks2508.systems/api/peers
→ {"error":"MISSING_TOKEN","message":"Authorization header required"}

# Con JWT válido (client_credentials)
$ curl -s https://broker.gateway.mks2508.systems/api/peers \
    -H "Authorization: Bearer $JWT_TOKEN" | jq .
→ [
→   {"id":"...","kind":"operator","name":"...","status":"running"},
→   ...
→ ]

Credenciales OIDC necesarias

Para generar el JWT, se necesita:

OIDC_CLIENT_ID — cliente OIDC registrado en Pocket-ID
OIDC_CLIENT_SECRET — secret del cliente
OIDC_TOKEN_ENDPOINT — https://auth-provider.mks2508.systems/api/oidc/token

El cliente gateway-server-workspace-helsinki (46c6e32c-75c0-4428-b358-9104c688ebfc) existe en Pocket-ID. Sus credenciales están en Coolify como env vars del servicio mks-backend.

Para smoke local, usar las credenciales del cliente mcp-standalone-mac-waxin en .env.brk-extract.local.

03

F2 — Verificar workspace container

10 min

Workspace container vivo + servicios

curl -s https://lab1-helsinki.api.mks2508.systems/health → 200 OK Health del gateway-server dentro del workspace
curl -s https://lab1-helsinki.api.mks2508.systems/health → body contiene 'gateway' Verificar que es el gateway-server, no code-server
docker exec <container> which a2a-mcp → /usr/local/bin/a2a-mcp a2a-mcp wrapper existe en PATH
docker exec <container> cat /usr/local/bin/a2a-mcp → script bash válido El wrapper apunta a bun /opt/mks-agentics/agent2agent-mcp/a2a-mcp.js
docker exec <container> test -f /opt/mks-agentics/agent2agent-mcp/a2a-mcp.js → existe El bundle a2a-mcp.js fue descargado en startup
docker exec <container> supervisorctl status gateway → RUNNING Gateway server está corriendo como servicio supervisado
docker exec <container> env | grep GATEWAY_BROKER_URL → https://broker.gateway.mks2508.systems Env var GATEWAY_BROKER_URL seteada en el container
docker exec <container> env | grep OIDC_CLIENT_ID → valor presente Credenciales OIDC inyectadas vía Coolify env vars

Variables de entorno requeridas en el workspace

Env vars requeridas en el workspace container (Coolify)
Variable	Valor	Necesaria para	Estado
GATEWAY_BROKER_URL	https://broker.gateway.mks2508.systems	a2a-mcp + cli-launcher	seteada
OIDC_ISSUER	https://auth-provider.mks2508.systems	OIDC token generation	seteada
OIDC_TOKEN_ENDPOINT	https://auth-provider.mks2508.systems/api/oidc/token	OIDC client_credentials	seteada
OIDC_CLIENT_ID	46c6e32c-...	JWT para broker	seteada
OIDC_CLIENT_SECRET	(secret)	JWT para broker	seteada
GITHUB_TOKEN	ghp_...	Descargar bundles de GitHub Releases	seteada
MINIMAX_API_KEY	(secret)	Provider MiniMax	seteada
GLM_API_KEY	(secret)	Provider GLM	seteada
DEEPSEEK_API_KEY	(secret)	Provider DeepSeek	seteada

CI de imagen Docker roto

El pipeline build-push-base-image.yml (#27881812954) falla en build-ubuntu-amd64 y build-arch por un symlink huérfano en mks-terminal/bin/mesh-drop:

chmod: cannot operate on dangling symlink '/home/developer/dotfiles/mks-terminal/bin/mesh-drop'

El fix es cambiar chmod +x .../bin/* por find .../bin -type f -exec chmod +x {} \; en el Dockerfile.unified:649.

Impacto en playbooks: mientras el CI esté roto, la imagen Docker no se actualiza. La imagen actual (pre-fix) ya tiene update-a2a-mcp.sh baked (commit b0acfb7 sí entró en el último build verde). Los playbooks no están bloqueados — el workspace container actual ya tiene a2a-mcp funcional.

04

F3 — Verificar proxy público

5 min

Proxy health + virtual key

curl -s https://proxy.gateway.mks2508.systems/health → 200 OK Health del proxy público
curl -s https://proxy.gateway.mks2508.systems/v1/providers → 200 + provider list Lista de providers disponibles (data-plane, sin auth)
curl -s https://proxy.gateway.mks2508.systems/v1/keys → 401 (sin OIDC session) Control-plane requiere OIDC admin session

Virtual key para desarrollo local

Proxy local vs proxy público

# El proxy tiene dos modos de acceso:
#
# 1. Proxy público (proxy.gateway.mks2508.systems:443)
#    → Requiere virtual key sk-mks-* en header x-api-key
#    → Para producción / Tier-2
#
# 2. Proxy local (127.0.0.1:3200)
#    → Sin auth si PROXY_AUTH_REQUIRED=false
#    → Para desarrollo local con cl minimax proxy

# Para crear una virtual key (requiere OIDC admin session):
$ gateway-proxyctl key create --label playbook-test
→ sk-mks-a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

# Verificar que la key funciona:
$ curl -s https://proxy.gateway.mks2508.systems/v1/models \
    -H "x-api-key: sk-mks-..." | jq .

05

F4 — Verificar claudio en Mac

5 min

Claudio modos + channels

claudio minimax --env --channels → emite exports sin errores Verificar que mergea a2a MCP + dangerouslyLoadDevelopmentChannels
ls ~/.claude-minimax/settings.json → existe Provider dir creado con settings.json
python3 -c "import json; d=json.load(open('$HOME/.claude-minimax/settings.json')); print('agent2agent' in d.get('mcpServers',{}))" → True a2a MCP mergeado en settings.json del provider dir
python3 -c "import json; d=json.load(open('$HOME/.claude-minimax/settings.json')); print(d.get('dangerouslyLoadDevelopmentChannels',[]))" → ['server:agent2agent'] Channels habilitados en settings.json
cl minimax --proxy --channels → lanza Claude Code sin errores Smoke: Claude Code arranca con proxy + channels

Verificación del provider dir

Inspeccionar settings.json del provider dir

# Verificar que claudio --channels mergeó correctamente
$ python3 -c "
import json
d = json.load(open('$HOME/.claude-minimax/settings.json'))
print('mcpServers:', json.dumps(d.get('mcpServers', {}), indent=2))
print('channels:', d.get('dangerouslyLoadDevelopmentChannels', []))
print('tengu_harbor:', d.get('cachedGrowthBookFeatures', {}).get('tengu_harbor'))
"
→ mcpServers: {
→   "agent2agent": {
→     "command": "a2a-mcp",
→     "env": {
→       "GATEWAY_BASE_URL": "https://broker.gateway.mks2508.systems",
→       "A2A_CHANNEL_PUSH": "1"
→     }
→   }
→ }
→ channels: ['server:agent2agent']
→ tengu_harbor: true

06

F5 — Verificación final

Verificado3 checks

Broker público responde healthz https://broker.gateway.mks2508.systems/healthz → 200
Workspace container gateway-server responde https://lab1-helsinki.api.mks2508.systems/health → 200
Proxy público responde https://proxy.gateway.mks2508.systems/health → 200

Research pendiente1 check

a2a-mcp bundle existe en workspace Verificar que update-a2a-mcp.sh se ejecutó en el último boot

Pendiente2 checks

CI Docker image verde Fix symlink mesh-drop en Dockerfile.unified:649
Runner daemon en Mac para spawn-plane Necesario para UC4 (spawn local)

Configuración

Código

Q1

¿Está el broker respondiendo? crítico

Verificar con curl -s https://broker.gateway.mks2508.systems/healthz

Sí → 200 OK Continuar a F2. El broker es el bus central.

No → error Revisar deploy en Coolify. El broker es prerequisite para TODO.

Q2

¿Está el workspace container ejecutando gateway-server? necesario

Verificar con curl -s https://lab1-helsinki.api.mks2508.systems/health

Sí → 200 OK Continuar a UC1/UC2. El workspace está listo.

No → error o timeout Revisar supervisorctl status gateway dentro del container. Puede que GITHUB_TOKEN no esté seteado y el bundle no se descargó.

Q3

¿Está a2a-mcp funcional en el workspace? UC3+

Verificar con docker exec <container> which a2a-mcp

Sí → /usr/local/bin/a2a-mcp Listo para UC3/UC5 (channels y spawn).

No → not found Ejecutar update-a2a-mcp.sh dentro del container. Si GITHUB_TOKEN no está, el bundle no se descarga.

Siguiente paso

Con P0 verde, se puede proceder a:

UC1 — sesión básica con proxy (cl minimax --proxy)
UC2 — gateway-web → workspace session
UC3 — dos peers Mac con channels (requiere F4 verde)
UC4 — spawn desde sesión Mac (requiere runner daemon)
UC5 — E2E workspace completo (requiere todo lo anterior)