--- slug: 74-platform title: Plataforma Synsema (syn) description: La forma alojada de correr Synsema — la CLI syn (instalación, registro y login desde la terminal, deploy, logs, secretos, entorno), qué es un proyecto (web, worker, job), syn.toml, el techo que tu bloque require fija contra el plan, los gates humanos, las programaciones, el reposo y la API HTTP. example_ids: [] --- # Plataforma Synsema (`syn`) [synsema.com](https://synsema.com) corre programas Synsema por vos: subís una carpeta y recibís una URL. Es **una forma** de desplegar — el mismo programa corre en tu propio servidor con `synsema serve` ([Deploy](71-deploy)); nada del lenguaje depende de la plataforma. Lo que agrega la plataforma: contenedores, una URL con HTTPS, secretos fuera de tu repositorio, logs, la **auditoría** de cada chequeo de capacidades, programaciones para los jobs y los gates humanos de tu programa (`approve`, `confirm`, `ask`) contestados desde un panel o una API. ## Instalar `syn` `syn` es a su vez un programa Synsema, así que primero va el motor ([Inicio rápido](00-quickstart)): ```sh curl -fsSL https://synsema.com/cli/install.sh | sh # macOS, Linux → ~/.local/bin/syn ``` ```powershell irm https://synsema.com/cli/install.ps1 | iex # Windows → %LOCALAPPDATA%\Synsema\syn ``` ## Cuenta y login ```sh syn signup # si todavía no tenés cuenta syn login # si ya tenés ``` Los dos muestran una página y un código corto. Abrí la página, creá la cuenta ahí si hace falta y aprobá el código: la terminal queda logueada. Ninguna contraseña pasa por la terminal. El token queda en `.synsema/syn.json` en la carpeta actual — agregá `.synsema/` a tu `.gitignore`. En CI, sin login: definí `SYN_TOKEN` (un token de API de Settings en synsema.com) y, si usás otro sitio, `SYN_SITE`. ## Desplegar Desde la carpeta de tu proyecto: ```sh syn deploy ``` La primera vez crea el proyecto; después manda una versión nueva. Imprime el **techo** — cada línea `require` de tu programa, concedida o negada por tu plan — y los secretos que el programa todavía necesita. Un programa que pide más de lo que permite el plan **no se despliega**: la plataforma lo rechaza antes de que corra, en vez de dejarlo fallar después. Qué viaja: cada archivo de la carpeta salvo lo que nombra `.gitignore`, más `.git`, `.env`, `.synsema`, `node_modules` y `target`, que siempre quedan afuera. Un archivo de más de 1 MB se saltea con un aviso; el paquete entero tiene que quedar por debajo de 8 MB. `syn files` muestra la lista sin subir nada. El archivo de entrada es el que nombra `syn.toml`; sin él, el único `.syn` de la raíz con un bloque `serve on`, o `--entry`. ## Comandos | Comando | Qué hace | |---|---| | `syn signup` / `syn login` | Loguea esta carpeta desde el navegador (arriba) | | `syn deploy [--name N] [--entry E] [--kind web\|worker]` | Sube la carpeta y encola un deploy | | `syn status` | Estado, paquete, techo y deploys del proyecto de esta carpeta | | `syn logs [--follow]` | Lo que escribieron la plataforma y el runner | | `syn secrets [set NOMBRE=valor …]` | Lista los secretos definidos y los que faltan, o los define (sólo escritura) | | `syn env [set NOMBRE=valor … [--secret]] [rm NOMBRE …]` | El entorno: listarlo como `.env`, definir, borrar | | `syn projects` | Todos los proyectos de la cuenta | | `syn open` | La URL de este proyecto | | `syn files` | Lo que viajaría, sin subir | | `syn stop` | Baja el servicio; los archivos, secretos y volumen quedan | | `syn delete --yes` | Borra el proyecto y todo lo que el runner tiene de él | ## Qué es un proyecto Una carpeta de archivos Synsema con un archivo de entrada. Su bloque `require` es el manifiesto: la plataforma concede lo que el plan permite y rechaza lo que lo supere. Un deploy corre el programa en un contenedor bajo ese techo con la auditoría encendida, así que cada chequeo de capacidades queda en la auditoría del proyecto. | Tipo | Corre | URL | |---|---|---| | `web` | `synsema serve ` | `.synsema.app`, nombres extra `-.synsema.app`, tu propio dominio en Pro. El programa los recibe como `SYNSEMA_HOST`, `SYNSEMA_HOSTS`, `SYNSEMA_HOST_` | | `worker` | `synsema run `, siempre encendido | ninguna (un bloque `serve on` se sirve en un puerto local, así sus gates humanos funcionan) | | `job` | `synsema run ` en un contenedor nuevo por ejecución, según una programación o a pedido | ninguna | ## `syn.toml` Opcional, en la raíz de la carpeta. Dice lo que el código no puede decir de sí mismo; el bloque `require` sigue siendo el manifiesto. ```toml name = "Invoice agent" slug = "invoices" # el nombre de la URL; se puede cambiar después entry = "app.syn" kind = "web" # web | worker | job memory = "512m" # opcional; el plan tiene un valor por defecto y un techo [schedule] # sólo jobs, UTC: cinco campos cron o @hourly, @daily, … cron = "0 * * * *" [secrets] # lo que el programa necesita definido, y una línea para quien lo define LLM_API_KEY = "la clave" [env] # variables con valor por defecto, visibles, editables LLM_PROVIDER = "anthropic" [hosts] # sólo web: nombres extra; etiqueta = para qué es api = "la API JSON" [volumes] # carpetas donde escribe el programa, que se conservan entre deploys data = "./data" [provision] # una URL que la plataforma consulta una vez, al crear; su env siembra el entorno env_url = "https://example.com/token" ``` ## Gates humanos Un programa que llega a `approve "¿Pagar 800 USDC al proveedor?" within 2h` (o `confirm`, o `ask … with [...]`) se detiene en esa línea bajo `serve`. La pregunta aparece en Approvals en synsema.com y en `GET /api/v1/approvals`; contestala ahí o con `POST /api/v1/approvals/{id}` y el pedido que esperaba sigue. Pasado el `within` sin respuesta, cuenta como un no. Sólo espera el pedido que llegó al gate; el resto del servicio sigue respondiendo. En un `job`, o un `worker` sin `serve on`, nadie puede contestar, así que `approve` responde no de inmediato — un programa desatendido no puede concederse el umbral a sí mismo. ## Jobs, programaciones y reposo - Un **job** corre según su programación (`[schedule]` o `PUT /api/v1/projects/{id}/schedule`), con `POST /api/v1/projects/{id}/run`, o desde el panel. Una ejecución nunca se superpone con la anterior y se abandona a las dos horas; cada una guarda su código de salida y el final de su salida. - Un servicio **web** que nadie llama por un rato entra en reposo y despierta con el siguiente pedido en alrededor de un segundo (el pedido espera). En el plan Free se duerme a los 10 minutos sin uso; Pro y Enterprise eligen. Un **worker** nunca duerme. ## La API Todo lo que hacen `syn` y el panel es una API HTTPS con token bearer: [synsema.com/docs](https://synsema.com/docs) y el [openapi.json](https://synsema.com/openapi.json) legible por máquinas.