Conecta una instalación

Hay una sola forma de conectar una instalación autoalojada: obtener un código en la cuenta de Opfield y pegarlo en Opfield. El mismo código añade la instalación a tu cuenta y la conecta. Las instalaciones gestionadas se conectan por sí solas; consulta Instalaciones gestionadas.

Antes de empezar

• Necesitas una cuenta de Opfield en https://account.opfield.dev y, en Opfield, un usuario con el ámbito license:manage.
• Opfield debe llegar a https://account.opfield.dev por HTTPS saliente. No se abre nada en tu lado: la conexión es un WebSocket que el propio Opfield abre hacia la cuenta.

Conecta

1. En la cuenta de Opfield, abre Installations, elige Connect an installation y después Get a code. Para una instalación que ya está en tu cuenta (por ejemplo, tras una reinstalación o una desconexión), abre su página y elige Connect en su lugar.
2. Copia el código. Tiene un aspecto como CLD-7K3M-Q9TX, funciona una sola vez y caduca a los 10 minutos. Obtener un código nuevo sustituye al anterior sin usar.
3. En Opfield, abre Settings > General, pega el código en el bloque Cloud y pulsa Connect. Opfield también acepta el código sin CLD-, sin guiones o en minúsculas.

El bloque Cloud pasa a mostrar Connected to con el correo de la cuenta, junto con Account y Connected since. La instalación aparece en tu cuenta unos segundos después.

Si Opfield rechaza el código:

Mensaje	Qué hacer
This code is not valid or has expired	Obtén un código nuevo en la cuenta.
This code was created for another installation	Has tomado el código de la página de otra instalación. Abre esta instalación en la cuenta y obtén allí su código.
Too many attempts	Espera unos minutos antes de volver a intentarlo.
Your cloud account could not be reached	Comprueba que Opfield puede llegar a https://account.opfield.dev por HTTPS y vuelve a intentarlo.

Permite la gestión remota

Una vez conectado, el bloque Cloud muestra Allow remote management. Está desactivado por defecto. Mientras está desactivado, la cuenta solo lee el estado de la instalación, los logs de los contenedores propios de Opfield y su estado de actualización.

Actívalo, y confirma, para que la cuenta también pueda:

• crear tokens de registro de nodos de un solo uso con sus comandos de instalación, como hace Nodes > Add Node;
• iniciar la actualización de Opfield que ofrece Settings > General;
• emitir un código de configuración del primer administrador, solo antes de la configuración inicial, mientras la instalación no tiene usuarios.

Desactivarlo surte efecto de inmediato y no requiere confirmación. El interruptor pertenece a la conexión actual: al volver a conectar, o al conectar con otra cuenta, empieza desactivado. Una petición que el interruptor prohíbe se rechaza, y la cuenta muestra que la gestión remota está desactivada. Cada petición, permitida o rechazada, queda en el registro de auditoría.

Inicia sesión con la cuenta de Opfield

Una instalación conectada puede permitir que las personas inicien sesión con su cuenta de Opfield. En Settings > Authentication > OIDC provider, elige Use Opfield account: Opfield pide a la cuenta un cliente de inicio de sesión, muestra “Waiting for your Opfield account…” con Cancel request y, cuando la cuenta responde, añade el proveedor “Opfield account” y activa el inicio de sesión con OIDC. Esto funciona con Allow remote management desactivado. Consulta Inicia sesión con la cuenta de Opfield.

Cambia a otra cuenta

Mientras estás conectado, elige Switch account, pega un código de la otra cuenta de Opfield, pulsa Connect y confirma. La conexión con la primera cuenta termina de inmediato y la instalación se conecta a la cuenta de la que procede el código. Allow remote management vuelve a empezar desactivado.

Desconecta

Desde Opfield, elige Disconnect en el bloque Cloud y confirma. Opfield pide a la cuenta que revoque la conexión y después la olvida. Si no se puede llegar a la cuenta, Opfield olvida la conexión de todos modos y te avisa de que la cuenta puede seguir mostrando la instalación: desconéctala también en la cuenta.

Desde la cuenta, elige Disconnect en la página de la instalación. El bloque Cloud muestra entonces Disconnected by the account, con la cuenta y la hora, y Opfield deja de conectarse. Eliminar la instalación de la cuenta también revoca su conexión.

En ambos casos, la instalación sigue funcionando. Su inicio de sesión solo cambia si usaba la cuenta de Opfield: Opfield olvida el cliente de inicio de sesión de la cuenta, elimina el proveedor “Opfield account” y desactiva el inicio de sesión con OIDC. Si ningún administrador pudiera iniciar sesión sin ese proveedor, se mantiene, y Settings > Authentication > OIDC provider avisa de ello; da a un administrador otro método de inicio de sesión y elimina después el proveedor. Para volver a conectar, obtén un código nuevo en la cuenta y pégalo en el bloque Cloud: el botón dice Connect, o Connect again tras una desconexión desde la cuenta.

Una instalación gestionada no se puede desconectar ni cambiar a otra cuenta desde ninguno de los dos lados.

Desde la API o MCP

La REST API y MCP hacen lo mismo que el bloque Cloud:

Acción	REST API	Herramienta MCP	Ámbito
Leer el estado de la conexión	GET /api/system/cloud/status	get_cloud_status	license:view
Conectar con un código	POST /api/system/cloud/connect con { "code": "CLD-XXXX-XXXX" }	manage_cloud con operation: "connect"	license:manage
Permitir o prohibir la gestión remota	POST /api/system/cloud/remote-management con { "enabled": true }	manage_cloud con operation: "set_remote_management"	license:manage
Desconectar	POST /api/system/cloud/disconnect	manage_cloud con operation: "disconnect"	license:manage

El estado es not_connected, connected o disconnected_by_account. Cuando está conectada, también indica el correo de la cuenta, la URL de la cuenta, la hora de conexión, el estado de la propia conexión (online, connecting o reconnecting con el último error), la gestión remota y las cinco últimas peticiones que envió la cuenta. Tras una desconexión desde Opfield mientras no se puede llegar a la cuenta, la respuesta incluye un warning. En una instalación gestionada, conectar, desconectar y cambiar la gestión remota se rechazan con 409 CLOUD_MANAGED.

Un código de conexión es un secreto: el asistente de IA te pide que lo copies de la cuenta y no lo repite en el chat. Consulta REST API y MCP.