> ## Documentation Index
> Fetch the complete documentation index at: https://docs.squarecloud.app/llms.txt
> Use this file to discover all available pages before exploring further.
# Variables de entorno y secretos
> Guarda tokens, claves de API y cadenas de conexión como variables de entorno en Square Cloud desde el dashboard, la CLI o la API, y léelas en tu código.
Mantén los tokens de bots, las claves de API y las contraseñas de bases de datos fuera de tu código fuente. Defínelos como variables de entorno en la aplicación, y tu código los lee en tiempo de ejecución como cualquier otra variable.
## Configurar las variables
Las variables de entorno pertenecen a una sola aplicación. Se mantienen tras reinicios y commits, pero una subida nueva crea una aplicación nueva sin ellas, así que vuelve a definirlas allí.
1. Abre tu aplicación en el [dashboard](https://squarecloud.app/es/dashboard) y ve a **Ajustes** → **Variables de entorno**.
2. Agrega cada clave y valor, o importa un archivo `.env` existente.
3. Haz clic en **Guardar**. El dashboard pregunta si quieres reiniciar la aplicación: reiníciala para que tome los nuevos valores.
Cuando subes una aplicación nueva en el dashboard, también puedes agregar variables en la pantalla de subida, antes del primer inicio.
Ejecuta los comandos desde la carpeta de tu proyecto. La CLI actúa sobre la aplicación cuyo `ID` está en tu `squarecloud.app`. Para actuar sobre otra, pasa `--app ` (para `list`, pasa el ID como argumento).
```bash theme={"system"}
# Agrega o actualiza variables (las demás quedan como están)
squarecloud app env set DISCORD_TOKEN=your-token LOG_LEVEL=info
# Envía cada línea de un archivo .env local
squarecloud app env set --from-file .env
# Lista las variables actuales
squarecloud app env list
# Elimina una variable
squarecloud app env remove LOG_LEVEL
# Reinicia para aplicar los cambios
squarecloud app restart
```
`squarecloud app env replace` sustituye todo el conjunto por el que pasas, tras una confirmación. Todos los comandos y flags se explican en [variables de entorno desde la CLI](/es/cli-reference/environment-variables); para instalar la CLI e iniciar sesión, consulta la [guía rápida de la CLI](/es/cli-reference/quickstart).
En la [extensión de Square Cloud](/es/vscode-extension/features), haz clic derecho en tu aplicación en la barra lateral y elige **Variables de entorno** para listarlas, agregarlas, editarlas o eliminarlas. Reinicia la aplicación después para aplicar los cambios.
Envía las variables a [`POST /v2/apps/{app_id}/envs`](/es/api-reference/endpoint/apps/envs/add_n_edit) con una clave de API que tenga el scope `envs:write`:
```bash theme={"system"}
curl -X POST "https://api.squarecloud.app/v2/apps/YOUR_APP_ID/envs" \
-H "Authorization: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"envs": {"DISCORD_TOKEN": "your-token"}}'
```
La misma ruta también [lista](/es/api-reference/endpoint/apps/envs/get) (`GET`), [reemplaza](/es/api-reference/endpoint/apps/envs/overwrite) (`PUT`) y [elimina](/es/api-reference/endpoint/apps/envs/remove) (`DELETE`) variables. La API no reinicia la aplicación: llama después al [endpoint de reinicio](/es/api-reference/endpoint/apps/restart).
Las variables se cargan cuando la aplicación inicia. Después de cualquier cambio, reinicia la aplicación, o seguirá ejecutándose con los valores anteriores.
## Léelas en tu código
```javascript Node.js theme={"system"}
const token = process.env.DISCORD_TOKEN;
if (!token) {
throw new Error("DISCORD_TOKEN is not set");
}
```
```python Python theme={"system"}
import os
token = os.environ.get("DISCORD_TOKEN")
if not token:
raise RuntimeError("DISCORD_TOKEN is not set")
```
Fallar de inmediato cuando falta una variable te da un mensaje claro en los logs, en lugar de un error confuso más adelante, como un token inválido.
## Variables que Square Cloud define por ti
Tu aplicación inicia con estas variables ya definidas:
| Variable | Valor | Úsala para |
| - | - | - |
| `PORT` | `80` | Elegir el puerto en el que escucha tu servidor web. |
| `HOST` | `0.0.0.0` | Elegir la dirección a la que se enlaza tu servidor web. |
| `SQUARECLOUD_APP_ID` | El ID de tu aplicación | Identificar la aplicación en tiempo de ejecución. |
| `NODE_ENV` | `production` | Indicar a las librerías de Node.js que se ejecutan en producción (runtimes de Node.js y TypeScript). |
No sobrescribas `PORT` ni `HOST` en un sitio web: la plataforma solo llega a un servidor en el puerto 80 y el host `0.0.0.0`.
Como `NODE_ENV` es `production`, `npm install` omite las `devDependencies`. Si tu comando `START` hace el build del proyecto (por ejemplo con `typescript` o `vite`), lista esas herramientas de build en `dependencies` dentro de `package.json`.
## Cómo llegan las variables a tu aplicación
Square Cloud guarda las variables en un archivo `.squarecloud/.env` dentro de la aplicación y las carga con un shell cada vez que la aplicación inicia, antes de instalar las dependencias y de ejecutar tu comando `START` o tu archivo `MAIN`. Dos consecuencias:
* **Los nombres** deben usar letras, dígitos y guiones bajos, y no empezar por un dígito.
* **Los valores** con espacios o caracteres del shell como `$`, `&`, `;` o `|` deben ir entre comillas, o el shell los corta o los expande. El dashboard y `squarecloud app env set` los ponen entre comillas por ti. En la extensión de VS Code o en la API, envuelve tú mismo ese valor en comillas simples: escribe `'p@ss word$1'`, o envía `"PASSWORD": "'p@ss word$1'"` en el cuerpo de la API.
Los límites son 256 variables por aplicación, 1024 caracteres por nombre y 4096 caracteres por valor. Los sitios web estáticos (HTML/CSS) no admiten variables de entorno y devuelven `STATIC_APP_ENV_NOT_SUPPORTED`.
## Mantén los secretos fuera de tu subida
Si tu código carga un archivo `.env` por su cuenta (por ejemplo con `dotenv`), ese archivo tiene que estar en la subida. Si listas `.env` en [`squarecloud.ignore`](/es/getting-started/squarecloud-ignore), la aplicación inicia sin sus secretos, y un bot falla con un token inválido.
La configuración más segura: pasa cada valor de tu `.env` a las variables de entorno de la aplicación, como se muestra arriba. Una vez definidas, puedes dejar `.env` fuera de la subida y fuera de tu repositorio de Git. `dotenv` no sobrescribe las variables que ya existen, así que el mismo código sigue funcionando en tu máquina y en Square Cloud.
Nunca subas tokens ni contraseñas a un repositorio público. Si uno se filtra, revócalo en el proveedor (por ejemplo, restablece el token del bot en el Discord Developer Portal) y define aquí el nuevo valor.
## Próximos pasos
Define `MAIN`, `MEMORY`, `START` y los demás campos de `squarecloud.app`.
Haz deploy de un bot que lee su token de una variable de entorno.
Corrige un token inválido, intents que faltan y bots que se desconectan.
Conéctate con un `DATABASE_URL` y la configuración SSL correcta.