Setup local

Requisitos

Node.js 14+ (sin dependencias externas)
Cuenta activa en app.puente.xyz
Una Platform API Key (puente_studio_xxx) generada desde Configuración

1. Generar tu STUDIO_KEY

Entra a app.puente.xyz

Inicia sesión con tu cuenta del workspace.

Configuración → Puente Studio Key

En el menú lateral o desde tu avatar → Configuración → Puente Studio Key → Nueva API Key.El formato es puente_studio_xxxxxxxxxxxxxxxxxxxx.

Cópiala y guárdala segura

Esta es tu credencial maestra. No la commitees en ningún repo. La key solo se muestra una vez.

La STUDIO_KEY da acceso completo a todos los artefactos y tablas de tu equipo. Trata esta key como tratarías una password de admin.

2. Clonar el repo

git clone https://github.com/octaviofv/puente_studio_repo.git
cd puente_studio_repo

Estructura

puente_studio_repo/
├── .env.example              Plantilla de variables de entorno
├── .env                      Tu config local (NO commitear)
├── README.md
├── skill_puente_studio.md    Documentacion del agente
└── APP/
    ├── files/                Archivos fuente de la app (editar aqui)
    ├── json_result/          JSONs de salida (generados)
    ├── output.json           JSON listo para subir a la API
    ├── pull_artefacto.js     ⬇  API → archivos locales
    └── files_to_json.js      ⬆  Archivos locales → JSON de la API

3. Configurar tu .env

cp .env.example .env

Edita .env con tu key:

.env

BASE_URL=https://puente-backend-721178029791.southamerica-west1.run.app/
STUDIO_KEY=puente_studio_xxxxxxxxxxxxxxxxxxxx

El BASE_URL del ejemplo es el correcto. No lo cambies salvo que estés en un environment privado.

4. Verificar que funciona

Lista tus artefactos:

curl -H "X-API-Key: $(grep STUDIO_KEY .env | cut -d= -f2)" \
  "$(grep BASE_URL .env | cut -d= -f2)studio/artefactos"

Si recibes un JSON con un array de artefactos (puede estar vacío si todavía no creaste ninguno), todo está correcto.

Si recibes 401, la STUDIO_KEY es inválida o está revocada — genera una nueva.

Editar una app existente

Bajar el artefacto a tu disco

node APP/pull_artefacto.js <id>

Esto descarga el app_content a APP/files/.

Editar los archivos

Modifica los archivos en APP/files/ con tu editor (VSCode, vim, Cursor, etc.).

Empaquetar el resultado

node APP/files_to_json.js

Genera APP/output.json listo para subir.

Subir los cambios

curl -X PUT "$BASE_URL/studio/artefactos/<id>" \
  -H "X-API-Key: $STUDIO_KEY" \
  -H "Content-Type: application/json" \
  -d @APP/output.json

El PUT reemplaza todo el app_content. Siempre usa el flujo completo: GET → editar → PUT con todo. Nunca subas solo los archivos modificados — los que falten se eliminan.

Crear una app nueva

curl -X POST "$BASE_URL/studio/artefactos" \
  -H "X-API-Key: $STUDIO_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "titulo": "Mi nueva app",
    "descripcion": "Demo",
    "app_content": {
      "index.tsx": {
        "content": "import React from \"react\";\nimport { createRoot } from \"react-dom/client\";\nimport App from \"./App\";\n\ncreateRoot(document.getElementById(\"root\")!).render(<App />);",
        "type": "tsx"
      },
      "App.tsx": {
        "content": "export default function App() { return <h1>Hola</h1>; }",
        "type": "tsx"
      }
    }
  }'

La respuesta incluye id, public_id y api_key. Guárdalas inmediatamente — la api_key no se vuelve a mostrar.

Configurar git para no commitear el .env

El .env está en .gitignore del repo. Igual verifica:

grep .env .gitignore

Si no aparece, agrégalo:

echo ".env" >> .gitignore

Errores comunes

`STUDIO_KEY` placeholder en `.env`

Si el archivo todavía tiene {STUDIO_KEY} literal en vez de tu key real, ningún script va a funcionar. Pega tu key real sin las llaves.

`401 Unauthorized` al listar artefactos

Tres causas comunes:

La key está revocada → regenera una nueva en Configuración
Estás usando una api_key de artefacto (puente_artifact_xxx) en endpoints privados → usa la STUDIO_KEY
La key pertenece a otro environment → verifica el BASE_URL

`404 Not Found` al actualizar un artefacto

El ID no existe en tu equipo, o pertenece a otro equipo. Verifica con GET /studio/artefactos (lista solo los del equipo asociado a tu key).

Mi app perdió archivos después de un PUT

Hiciste un PUT con app_content parcial. El endpoint reemplaza el objeto completo. Si tienes copia local, vuelve a empaquetar todos los archivos y haz otro PUT. Si no, baja el artefacto a tu disco antes de futuros cambios.

Empezar

Plataforma

Componentes

Puente Studio

Recursos

Enterprise

Preguntas frecuentes

Requisitos

1. Generar tu STUDIO_KEY

2. Clonar el repo

Estructura

3. Configurar tu .env

4. Verificar que funciona

Editar una app existente

Crear una app nueva

Configurar git para no commitear el .env

Errores comunes

Siguiente paso

Usar con coding agents

Referencia de API

​Requisitos

​1. Generar tu STUDIO_KEY

​2. Clonar el repo

​Estructura

​3. Configurar tu .env

​4. Verificar que funciona

​Editar una app existente

​Crear una app nueva

​Configurar git para no commitear el .env

​Errores comunes

​Siguiente paso

Usar con coding agents

Referencia de API

Requisitos

1. Generar tu STUDIO_KEY

2. Clonar el repo

Estructura

3. Configurar tu .env

4. Verificar que funciona

Editar una app existente

Crear una app nueva

Configurar git para no commitear el .env

Errores comunes

Siguiente paso