The AI Engineer PathEjecutar el código localmente
Esta página te ayuda a poner en funcionamiento un proyecto extraído de Intro to AI Agents en tu computadora: un servidor Express que se comunica con tu proveedor de IA, y un frontend Vite que abres en el navegador. Nada más adelante en el curso depende de esto, y la versión de Scrimba sigue funcionando hagas o no esta configuración.
Lo que necesitas primero
Una versión LTS compatible de Node.js. Se recomienda Node 24, y Node 22 también funciona. Verifica qué tienes:
$ node --version
v24.18.0Si dice "command not found", instala la versión marcada LTS desde nodejs.org.
npm. Node incluye npm, y las descargas de Scrimba son proyectos npm. Verifica que esté disponible:
$ npm --version
11.18.0
Si alguno dice "command not found", ese es el único problema, e instalar Node lo soluciona todo.
Abre la carpeta del proyecto
Abre una terminal en la carpeta extraída que contiene package.json:
$ cd path-to-your-downloaded-projectEcha un vistazo a lo que hay ahí. Los archivos exactos varían según la lección. package.json siempre está ahí y lista los comandos que espera el proyecto; las lecciones de aplicación también incluyen archivos como server.js, environment.js, y vite.config.js.
cd para entrar en la carpeta extraída que contiene package.json. Todos los comandos en esta página se ejecutan desde ahí. Cuando un comando dice que falta un archivo, verifica en qué carpeta está tu terminal antes de cambiar cualquier otra cosa.
Instala y ejecuta
En Scrimba, AI_URL, AI_KEY, y AI_MODEL se almacenan en tu configuración de cuenta, y Scrimba los inyecta en el proyecto en ejecución. Por eso no hay archivo .env en la versión del navegador: no es necesario ahí, y sería un mal lugar para guardar una clave en un editor compartido de todas formas. En tu máquina nada los inyecta, así que un archivo .env hace ese trabajo.
Instala las dependencias del proyecto descargado, luego ejecútalo:
$ npm install
$ npm startEn la primera ejecución, environment.js nota que faltan los valores requeridos, crea .env junto a package.json, y detiene el servidor Express con un mensaje que incluye estas líneas:
Missing environment variables: AI_KEY, AI_MODEL, AI_URL.
Created .env with the required variable names. Complete it, then restart the app.Es posible que Vite siga ejecutándose, así que presiona Ctrl+C para detenerlo antes de editar el nuevo archivo. El archivo .env generado tiene una línea vacía por variable y una línea de puerto comentada al final:
AI_KEY=
AI_MODEL=
AI_URL=
# PORT=3001Rellena tus valores reales directamente después de cada =, sin espacios alrededor:
AI_KEY=tu-clave-api-aqui
AI_MODEL=gpt-5.4-nano
AI_URL=https://api.openai.com/v1
# PORT=3001Estos son los mismos valores que pusiste en las variables de entorno de Scrimba. Si los necesitas de nuevo, ve a provider setup. Deja la línea # PORT=3001 como está; el proyecto usa el puerto 3001 a menos que lo cambies.
Algunas lecciones posteriores añaden líneas opcionales como GITHUB_TOKEN= al archivo generado. El servidor puede iniciarse sin ellas e imprime ○ Optional environment not configured: GITHUB_TOKEN. Sin un token de GitHub, las solicitudes a GitHub usan el límite de tasa anónima más bajo.
Nunca hagas commit de tu archivo .env
Si pones este proyecto en Git, lista .env en un .gitignore en la carpeta del proyecto antes de tu primer commit. Una clave subida a un repositorio público es una clave que tienes que revocar, y los scrapers automatizados la encuentran en minutos. node_modules también pertenece ahí, porque es grande y npm install la reconstruye:
.env
node_modules.env.example es el archivo que es seguro hacer commit, porque contiene texto de marcador en lugar de tu clave. El manual de Git cubre el hábito más amplio en ignoring files and good habits.
Reinicia el proyecto después de guardar .env:
$ npm startNode carga el archivo a través del environment.js generado. El vite.config.js descargado llama a loadEnv de Vite, así que Vite lee el mismo archivo cuando configura el proxy navegador-a-servidor. No necesitas instalar dotenv ni editar server.js.
npm start ejecuta dos procesos a la vez: el servidor Express que mantiene tu clave de API y hace solicitudes de modelo, y el servidor de desarrollo Vite que sirve el frontend. Verás salida de ambos intercalada en la misma terminal. Una verificación de entorno marcada y ambas líneas de dirección significan que funcionó:
Environment check:
✓ AI_KEY: configured
✓ AI_MODEL: gpt-5.4-nano
✓ AI_URL: https://api.openai.com/v1
OpenSwap server running at http://localhost:3001
VITE v6.4.3 ready in 214 ms
➜ Local: http://localhost:5173/Abre la URL de Vite, no la de Express. El frontend es con lo que interactúas, y envía sus llamadas de API a Express detrás de escenas.
Detén ambos con Ctrl+C.
npm install una vez, luego npm start. El primer inicio crea .env y se detiene; presiona Ctrl+C, rellena los tres valores que usas en Scrimba, guarda, e inicia de nuevo. Cuando veas las marcas de verificación de la verificación de entorno y la dirección de Vite, abre esa dirección. Si usas Git, crea el .gitignore antes de tu primer commit, no después.
Cómo se encuentran los dos servidores
Tu código frontend llama a rutas como /api/swaps, sin hostname ni puerto. Esto funciona por el proxy en vite.config.js:
import { defineConfig, loadEnv } from "vite";
export default defineConfig(({ mode }) => {
const env = loadEnv(mode, process.cwd(), "");
const port = env.PORT || process.env.PORT || 3001;
return {
server: {
hmr: false,
watch: {
ignored: ["**/*"],
},
proxy: {
"/api": {
target: `http://localhost:${port}`,
},
},
},
};
});Cualquier cosa que comience con /api se reenvía a Express. Por eso el código frontend nunca necesita saber en qué puerto está el backend, y es también por qué no tienes errores de origen cruzado en desarrollo.
Los playgrounds del curso intencionalmente desactivan el comportamiento de recarga automática de Vite para que un guardado no pueda borrar la salida actual mientras trabaja en una lección. Actualiza el navegador manualmente cuando quieras cargar un cambio.
http://localhost:5173, en tu navegador. Las llamadas que comienzan con /api se pasan al servidor Express para ti, así que nunca abres el puerto 3001 directamente. Después de editar un archivo, actualiza el navegador tú mismo; la página no se recarga automáticamente.
Cuando el puerto 3001 está en uso
Si algo más en tu máquina ya usa el puerto 3001, Express falla al iniciar con EADDRINUSE. Abre .env, quita el # de la línea # PORT=3001 al final (o añade la línea si no está), y cambia el número:
PORT=3101Luego detén el proyecto con Ctrl+C y ejecuta npm start de nuevo. Ese es el único cambio que necesitas. server.js lee PORT para decidir dónde escuchar, y Vite lee el mismo valor antes de configurar su proxy.
El puerto del frontend se comporta diferente. Si 5173 está ocupado, Vite se mueve al siguiente puerto libre e imprime esa dirección en su lugar, así que lee la línea Local: en lugar de escribir localhost:5173 de memoria. Para elegir el puerto del frontend tú mismo, pásalo a Vite:
$ npm run client -- --port 5180El bare -- le dice a npm que pase el flag después de él a Vite en lugar de tratarlo como una opción de npm.
EADDRINUSE, abre .env, cambia # PORT=3001 a PORT=3101 (la # se quita), e reinicia. El frontend recoge el nuevo puerto del backend automáticamente. Para el frontend en sí, solo abre la dirección que imprime Vite.
Si algo no funciona
EADDRINUSE significa que el puerto ya está en uso. Ve la sección de arriba.
Missing environment variables: seguido de nombres significa que esas líneas en .env aún están vacías, o el archivo no se guardó. Rellérnalas e reinicia.
Un error de credenciales faltantes o autenticación significa que AI_KEY no llega al código, o el proveedor lo rechazó. Verifica que tu archivo se llama exactamente .env y no .env.txt, que está en la misma carpeta que package.json, que el valor está rellenado, y que reiniciaste el servidor después de editarlo.
"Local environment loading requires Node.js 20.12 or newer." Tu Node es demasiado antiguo para el cargador de .env integrado del proyecto. Instala el lanzamiento LTS actual, Node 24, desde nodejs.org, luego ejecuta npm start de nuevo. No necesitas dotenv.
Un error de modelo no encontrado usualmente significa que AI_MODEL y AI_URL no coinciden, por ejemplo un ID de modelo de OpenAI contra la URL de OpenRouter. Cambia las tres variables juntas cuando cambies proveedores.
Las llamadas de API devuelven 404 desde el frontend sugiere que Express no está ejecutándose o está en un puerto diferente del que espera el proxy. Mira tu terminal: deberías ver tanto la línea de Express como la de Vite. Si solo Vite se inició, Express se estrelló, y la razón estará justo encima.
La instalación se completa pero npm start no puede encontrar un paquete. Ejecuta npm install de nuevo e incluye la salida completa cuando pidas ayuda. La descarga incluye package-lock.json, así que pnpm y una configuración de workspace no están involucradas.
Todo se ve correcto y aún falla. Llévalo al Discord del curso, con lo que ejecutaste y lo que regresó. Los problemas de configuración casi siempre son específicos de una máquina, y alguien probablemente ya haya tropezado con la tuya.
.env, y un 404 del frontend usualmente significa que Express no está ejecutándose. Reinicia con npm start después de cada cambio a .env.