Guía de Configuración de Espacios

Aprende cómo crear y configurar espacios de trabajo donde tus agentes de IA pueden leer archivos, escribir código y gestionar proyectos.

Tabla de Contenidos

Lo Que Aprenderás
Requisitos Previos
Entendiendo Espacios
Creando un Espacio
Trabajando con Archivos
Variables de Entorno
Configuración del Área de Trabajo
Mejores Prácticas
Solución de Problemas

Lo Que Aprenderás

Al final de esta guía, sabrás cómo:

✅ Crear espacios de trabajo aislados para agentes
✅ Cargar y gestionar archivos
✅ Configurar variables de entorno de forma segura
✅ Establecer estructura del proyecto
✅ Controlar acceso y permisos
✅ Trabajar con almacenamiento persistente

Tiempo para completar: 15-20 minutos

Requisitos Previos

Antes de comenzar, asegúrate de tener:

✅ Una cuenta de TeamDay (Guía de registro)
✅ Una organización (Configuración de Org)
✅ Al menos un agente creado (Guía de Agentes)
✅ Token de Acceso Personal (Guía de PAT)

Entendiendo Espacios

¿Qué Son los Espacios?

Los espacios son entornos aislados del sistema de archivos donde agentes de IA pueden:

Leer y escribir archivos
Ejecutar código y comandos
Almacenar datos persistentes
Trabajar con repositorios Git
Acceder a variables de entorno

Piensa en un espacio como un área de trabajo virtual para tus agentes, como una carpeta de proyecto en esteroides.

Screenshot

Características Clave

Aislamiento

Cada espacio tiene su propio sistema de archivos
Los agentes no pueden acceder a archivos de otros espacios
Multitenancy seguro

Persistencia

Los archivos sobreviven entre ejecuciones de agentes
Copia de seguridad automática a almacenamiento S3
Control de versiones con Git

Flexibilidad

Comienza desde cero (espacio vacío)
Clona repositorio Git existente
Usa plantillas de iniciación

Colaboración

Comparte espacios con miembros del equipo
Múltiples agentes pueden trabajar en el mismo espacio
Sincronización de archivos en tiempo real

Casos de Uso de Espacios

Desarrollo de Software

Espacio: "Proyecto de API de Backend"
- Clona repositorio Git
- Los agentes revisan y escriben código
- Confirman cambios de vuelta al repo
- Ejecutan pruebas y compilación

Análisis de Datos

Espacio: "Análisis de Ventas Q1"
- Carga conjuntos de datos CSV
- Ejecuta scripts de análisis Python
- Genera visualizaciones
- Almacena resultados e informes

Creación de Contenido

Espacio: "Tubería de Contenido de Blog"
- Borradores de artículos en Markdown
- Itera con comentarios del agente
- Almacena imágenes y activos
- Publica contenido final

Scripts de Automatización

Espacio: "Utilidades de DevOps"
- Almacena scripts de automatización
- Archivos de configuración
- Manifiestos de implementación
- El agente ejecuta tareas

Creando un Espacio

Método 1: Vía UI (Recomendado)

Paso 1: Navega a Espacios

Inicia sesión en TeamDay
Haz clic en “Espacios” en la barra lateral
Haz clic en el botón ”+ Nuevo Espacio”

Screenshot

Paso 2: Configura Opciones Básicas

Nombre del Espacio:

Descriptivo y específico
1-100 caracteres
Ejemplos:
- ✅ “API de Backend de Cliente”
- ✅ “Contenido del Sitio Web de Marketing”
- ❌ “Espacio 1”, “Prueba”, “Área de trabajo”

Descripción (Opcional):

Descripción general del propósito del espacio
Ayuda a los miembros del equipo a entender el contexto
Ejemplo: “API de backend para sistema de gestión de clientes construida con Node.js y PostgreSQL”

Screenshot

Paso 3: Elige Tipo de Inicialización

Opción A: Área de Trabajo Vacía

Mejor para: Comenzar un nuevo proyecto desde cero

Lo que obtienes:

Directorio vacío
Repositorio Git inicializado
Archivo de instrucciones CLAUDE.md predeterminado
Listo para trabajo del agente

Haz clic en “Crear Espacio Vacío”

Screenshot

Opción B: Clonar Repositorio Git

Mejor para: Trabajar con bases de código existentes

Requisitos:

URL de repositorio Git (HTTPS o SSH)
Credenciales de acceso (para repos privados)

Pasos:

Selecciona “Clonar desde Git”

Ingresa URL del repositorio

https://github.com/username/repository.git

(Opcional) Especifica rama
- Predeterminado: main o master
- Ejemplo: develop, staging
Haz clic en “Clonar Repositorio”

Screenshot

Opción C: Usar Plantilla de Iniciación

Mejor para: Configuración rápida de proyectos con mejores prácticas

Plantillas disponibles:

Nuxt - Framework Vue de stack completo
Next.js - Framework React
Vue - Framework frontend
React - Librería frontend
Express - Backend Node.js
FastAPI - Backend Python

Cada plantilla incluye:

Boilerplate del proyecto
Dependencias configuradas
CLAUDE.md con instrucciones del proyecto
Estructura de archivo de mejores prácticas

Selecciona plantilla y haz clic en “Crear desde Plantilla”

Screenshot

Paso 4: Establece Visibilidad

Controla quién puede acceder a tu espacio:

Privado (Predeterminado)

Solo tú puedes acceder
Mejor para: Proyectos personales, experimentos
Acceso de agente: Solo agentes que asignes

Organización

Todos los miembros de la organización pueden acceder
Mejor para: Colaboración de equipo
Acceso de agente: Todos los agentes de org disponibles

Público

Cualquiera con enlace puede ver (solo lectura)
La ejecución requiere membresía de org
Mejor para: Demostraciones, código abierto, vitrinas

Screenshot

Paso 5: Crear Espacio

Haz clic en “Crear Espacio”

Proceso de inicialización:

Crear sistema de archivos
Inicializar Git (si es aplicable)
Clonar repositorio / configurar plantilla (si es aplicable)
Configurar sincronización S3
¡Listo! ✅

Progreso mostrado en UI. Generalmente toma 10-30 segundos.

Screenshot

Paso 6: Accede a Tu Espacio

Una vez listo, verás:

Pestaña Archivos - Examina y gestiona archivos
Pestaña Chat - Interactúa con agentes en este espacio
Pestaña Configuración - Configura opciones de espacio
Pestaña Historial - Historial de confirmaciones Git

Screenshot

Método 2: Vía API

Crear Espacio Vacío:

curl -X POST "https://us.teamday.ai/api/v1/spaces" \
  -H "Authorization: Bearer $TEAMDAY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customer API Backend",
    "description": "Backend API for customer management",
    "visibility": "organization",
    "type": "empty"
  }'

Clonar Repositorio Git:

curl -X POST "https://us.teamday.ai/api/v1/spaces" \
  -H "Authorization: Bearer $TEAMDAY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Existing Project",
    "type": "git",
    "gitUrl": "https://github.com/username/repo.git",
    "gitBranch": "main"
  }'

Usar Plantilla de Iniciación:

curl -X POST "https://us.teamday.ai/api/v1/spaces" \
  -H "Authorization: Bearer $TEAMDAY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "New Nuxt App",
    "type": "starterKit",
    "starterKit": "nuxt"
  }'

Respuesta:

{
  "id": "s-abc123xyz",
  "name": "Customer API Backend",
  "description": "Backend API for customer management",
  "visibility": "organization",
  "status": "initializing",
  "organizationId": "org_xyz789",
  "createdAt": "2025-01-15T10:00:00Z",
  "s3Bucket": "teamday-workspaces",
  "s3Prefix": "org_xyz789/spaces/s-abc123xyz/"
}

Monitorea estado de inicialización:

curl -X GET "https://us.teamday.ai/api/v1/spaces/s-abc123xyz" \
  -H "Authorization: Bearer $TEAMDAY_API_TOKEN"

Espera a que status: "ready" antes de usar el espacio.

Trabajando con Archivos

Estructura del Sistema de Archivos

Cada espacio incluye:

/data/sandbox/{orgId}/spaces/s-{spaceId}/
├── CLAUDE.md           # Instrucciones de agentes (auto-generado)
├── .git/               # Repositorio Git
├── .gitignore          # Ignorados estándar
└── ...tus archivos...

El Archivo CLAUDE.md

Instrucciones auto-generadas para agentes que trabajan en este espacio:

# Proyecto: API de Backend de Cliente

API de backend para sistema de gestión de clientes

## Contexto

Este es un área de trabajo de TeamDay para: Desarrollo backend
Organización: Acme Corp
ID de Espacio: s-abc123xyz
Creado: 2025-01-15

## Directrices

Al trabajar en este espacio:
- Sigue patrones de código existentes
- Escribe mensajes de confirmación claros
- Prueba antes de confirmar
- Documenta cambios significativos

## Archivos

[Agente: Usa la herramienta de sistema de archivos para explorar archivos]

Personaliza CLAUDE.md para añadir instrucciones específicas del proyecto:

# Proyecto de API de Cliente

## Stack de Tecnología
- Node.js 20+ con TypeScript
- Framework Express.js para API
- Base de datos PostgreSQL
- Autenticación JWT

## Estándares de Código
- Usa modo estricto de TypeScript
- Sigue guía de estilo Airbnb
- Longitud máxima de función: 50 líneas
- Escribe comentarios JSDoc para funciones públicas

## Pruebas
Ejecuta pruebas antes de confirmar:
```bash
bun test

Comandos Comunes

Desarrollo

bun run dev     # Iniciar servidor de desarrollo (puerto 3000)
bun run build   # Compilar para producción

Base de Datos

bun run migrate    # Ejecutar migraciones
bun run seed       # Datos de prueba de semilla


![Screenshot](./images/space-setup/claude-md.png)

### Cargar Archivos

**Vía UI:**

1. Abre espacio → Pestaña **Archivos**
2. Haz clic en el botón **"Cargar Archivos"**
3. Selecciona archivos de tu computadora
   - Máx 20 archivos a la vez
   - Máx 100MB por archivo
4. Elige directorio de destino (predeterminado: raíz)
5. Haz clic en **"Cargar"**

Los archivos aparecen inmediatamente en el navegador de archivos.

![Screenshot](./images/space-setup/upload-files.png)

**Vía CLI:**

```bash
# Cargar archivo único
teamday spaces upload s-abc123xyz \
  --file data.csv \
  --dest /data/

# Cargar múltiples archivos
teamday spaces upload s-abc123xyz \
  --files config.json,schema.sql,README.md \
  --dest /

# Cargar directorio
teamday spaces upload s-abc123xyz \
  --directory ./src \
  --dest /src

Vía API:

curl -X POST "https://us.teamday.ai/api/v1/spaces/s-abc123xyz/files" \
  -H "Authorization: Bearer $TEAMDAY_API_TOKEN" \
  -F "[email protected]" \
  -F "path=/data/data.csv"

Leer Archivos

Vía Agente:

Pide a tu agente que lea archivos:

Usuario: "Muéstrame el contenido de package.json"

Agente: [Usa herramienta de sistema de archivos para leer archivo]

Usuario: "¿Qué archivos hay en el directorio src/?"

Agente: [Lista contenidos del directorio]

Screenshot

Vía UI:

Navega a la pestaña Archivos
Haz clic en cualquier archivo
Ve el contenido en el editor integrado

Vía API:

curl -X GET "https://us.teamday.ai/api/v1/spaces/s-abc123xyz/files?path=/package.json" \
  -H "Authorization: Bearer $TEAMDAY_API_TOKEN"

Escribir Archivos

Vía Agente:

Los agentes pueden crear y modificar archivos:

Usuario: "Crea un nuevo archivo src/utils/helpers.ts con funciones de utilidad común"

Agente: [Crea archivo con contenido]

Usuario: "Actualiza src/api/users.ts para añadir validación de entrada"

Agente: [Lee archivo, hace cambios, escribe de vuelta]

Screenshot

Vía UI:

Haz clic en el botón “Nuevo Archivo”
Ingresa nombre de archivo y ruta
Escribe contenido en el editor
Haz clic en “Guardar” (o Cmd/Ctrl+S)

Vía API:

curl -X POST "https://us.teamday.ai/api/v1/spaces/s-abc123xyz/files" \
  -H "Authorization: Bearer $TEAMDAY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "path": "/src/utils/helpers.ts",
    "content": "export function formatDate(date: Date): string {\n  return date.toISOString();\n}"
  }'

Descargar Archivos

Vía UI:

Navega a la pestaña Archivos
Click derecho en archivo → Descargar
O selecciona múltiples → Descargar como ZIP

Vía CLI:

# Descargar archivo único
teamday spaces download s-abc123xyz \
  --file src/app.ts \
  --output ./app.ts

# Descargar espacio completo
teamday spaces download s-abc123xyz \
  --all \
  --output backup.zip

Vía API:

curl -X GET "https://us.teamday.ai/api/v1/spaces/s-abc123xyz/files/download?path=/src/app.ts" \
  -H "Authorization: Bearer $TEAMDAY_API_TOKEN" \
  -o app.ts

Eliminar Archivos

Vía Agente:

Usuario: "Elimina los archivos de prueba antiguo en /tests/deprecated/"

Agente: [Elimina archivos]

Vía UI:

Selecciona archivo(s) en el navegador de archivos
Haz clic en el botón Eliminar (o presiona tecla Eliminar)
Confirma eliminación

Vía API:

curl -X DELETE "https://us.teamday.ai/api/v1/spaces/s-abc123xyz/files?path=/old-file.txt" \
  -H "Authorization: Bearer $TEAMDAY_API_TOKEN"

Variables de Entorno

Almacena configuración sensible de forma segura.

¿Por Qué Usar Variables de Entorno?

Seguridad:

Las claves de API y secretos no en código
Cifrado en reposo
No expuesto en historial de Git

Flexibilidad:

Diferentes valores por entorno
Fácil de actualizar sin cambios de código
Comparte espacios sin compartir secretos

Mejores Prácticas:

Nunca confirmes credenciales en Git
Usa variables de entorno para todos los secretos
Rota claves regularmente

Estableciendo Variables de Entorno

Vía UI:

Abre espacio → Pestaña Configuración
Haz clic en “Variables de Entorno”
Haz clic en ”+ Añadir Variable”

Ingresa clave y valor:

Clave: DATABASE_URL
Valor: postgresql://user:pass@host:5432/db

Haz clic en “Guardar”

Las variables se cifran antes del almacenamiento.

Screenshot

Variables Comunes:

# Base de Datos
DATABASE_URL=postgresql://user:pass@localhost:5432/mydb
REDIS_URL=redis://localhost:6379

# Claves de API
ANTHROPIC_API_KEY=sk-ant-xxx
OPENAI_API_KEY=sk-xxx
STRIPE_SECRET_KEY=sk_test_xxx

# Aplicación
NODE_ENV=development
PORT=3000
LOG_LEVEL=debug

# Autenticación
JWT_SECRET=your-secret-key
SESSION_SECRET=another-secret

Vía API:

curl -X POST "https://us.teamday.ai/api/v1/secrets/set" \
  -H "Authorization: Bearer $TEAMDAY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "spaceId": "s-abc123xyz",
    "key": "DATABASE_URL",
    "value": "postgresql://user:pass@host:5432/db"
  }'

Usando Variables de Entorno

En Código del Agente:

Los agentes pueden acceder a variables al ejecutar código:

# Ejemplo Python
import os

database_url = os.environ.get('DATABASE_URL')
api_key = os.environ.get('ANTHROPIC_API_KEY')

// Ejemplo JavaScript
const databaseUrl = process.env.DATABASE_URL;
const apiKey = process.env.ANTHROPIC_API_KEY;

En Archivos de Configuración:

Usa sintaxis de marcador de posición:

{
  "database": "${DATABASE_URL}",
  "apiKey": "${ANTHROPIC_API_KEY}"
}

Ver Variables

Vía UI:

Configuración → Variables de Entorno
Ve lista de claves (valores ocultos)
Haz clic en “Revelar” para mostrar valor temporalmente

Vía API:

curl -X GET "https://us.teamday.ai/api/v1/spaces/s-abc123xyz/environment" \
  -H "Authorization: Bearer $TEAMDAY_API_TOKEN"

Respuesta (valores cifrados):

{
  "variables": {
    "DATABASE_URL": "***encrypted***",
    "ANTHROPIC_API_KEY": "***encrypted***"
  }
}

Eliminar Variables

Vía UI:

Configuración → Variables de Entorno
Encuentra variable
Haz clic en el icono Eliminar
Confirma

Vía API:

curl -X DELETE "https://us.teamday.ai/api/v1/secrets/DATABASE_URL?spaceId=s-abc123xyz" \
  -H "Authorization: Bearer $TEAMDAY_API_TOKEN"

Configuración del Área de Trabajo

Límites del Sistema de Archivos

Tamaño total: 10 GB por espacio
Recuento de archivos: Ilimitado (uso razonable)
Archivo individual: Máx 100 MB de carga
Frecuencia de sincronización: Cada 5 minutos + en cambios

Sincronización S3

Todos los espacios se sincronizan automáticamente con S3 para durabilidad:

Cómo funciona:

El agente modifica archivos localmente
Los cambios se detectan por observador de archivos
Los archivos modificados se cargan a S3
Sincronización cada 5 minutos + inmediatamente al guardar

Beneficios:

Copia de seguridad automática
Recuperación ante desastres
Compartir entre sesiones
Acceder desde múltiples ubicaciones

Sincronización manual:

# Fuerza carga a S3
teamday spaces sync s-abc123xyz --direction up

# Fuerza descarga desde S3
teamday spaces sync s-abc123xyz --direction down

Verifica estado de sincronización:

teamday spaces sync-status s-abc123xyz

Salida:

{
  "spaceId": "s-abc123xyz",
  "lastSync": "2025-01-15T10:30:00Z",
  "pendingChanges": 0,
  "syncEnabled": true
}

Asignando Agentes

Otorga acceso específico de agentes a un espacio:

Vía UI:

Abre espacio → Configuración → Agentes
Haz clic en “Asignar Agente”
Selecciona agente del dropdown
Haz clic en “Añadir”

Los agentes asignados:

Pueden leer/escribir archivos
Ven contexto del espacio
Reciben instrucciones del archivo CLAUDE.md

Screenshot

Vía API:

curl -X POST "https://us.teamday.ai/api/v1/spaces/s-abc123xyz/agents" \
  -H "Authorization: Bearer $TEAMDAY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "char_def456"
  }'

Mejores Prácticas

1. Organiza Tus Archivos

Usa estructura de proyecto estándar:

project-space/
├── CLAUDE.md          # Instrucciones
├── README.md          # Docs del proyecto
├── package.json       # Dependencias
├── src/               # Código fuente
│   ├── api/          # Rutas de API
│   ├── services/     # Lógica de negocio
│   ├── utils/        # Utilidades
│   └── types/        # Tipos de TypeScript
├── tests/            # Archivos de prueba
├── docs/             # Documentación
└── .github/          # CI/CD

2. Usa .gitignore

Siempre ignora:

# Dependencias
node_modules/
vendor/

# Salida de compilación
dist/
build/
.next/

# Entorno
.env
.env.local

# Logs
*.log
logs/

# OS
.DS_Store

3. Documenta en CLAUDE.md

Facilita a los agentes:

# Referencia Rápida

## Iniciar Desarrollo
```bash
bun install
bun run dev

Ejecutar Pruebas

bun test

Tareas Comunes

Agregar endpoint API: Crea archivo en src/api/
Migración de base de datos: Ejecuta bun run migrate
Implementar: Empuja a rama main (se implementa automáticamente)


### 4. Asegura Tus Secretos

**Haz:**
- ✅ Usa variables de entorno para todos los secretos
- ✅ Añade `.env` a `.gitignore`
- ✅ Rota claves regularmente
- ✅ Usa diferentes claves por entorno

**No Hagas:**
- ❌ Confirmes secretos en Git
- ❌ Compartas secretos en mensajes de chat
- ❌ Uses claves de producción en desarrollo

### 5. Mantén Espacios Enfocados

Crea espacios separados para:

- **Desarrollo** - Trabajo activo
- **Staging** - Pruebas pre-producción
- **Producción** - Referencia solo lectura
- **Experimentos** - Prueba ideas nuevas

### 6. Copias de Seguridad Regulares

Aunque la sincronización S3 proporciona copia de seguridad, también mantén copias:

```bash
# Script de copia de seguridad semanal
#!/bin/bash
DATE=$(date +%Y%m%d)
teamday spaces download s-abc123xyz \
  --all \
  --output "backups/project-$DATE.zip"

7. Monitorea el Tamaño del Espacio

Mantén espacios bajo 1GB para mejor rendimiento:

# Verifica tamaño del espacio
teamday spaces info s-abc123xyz | grep size

Archivos grandes a evitar:

node_modules/ (usa .gitignore)
Artefactos de compilación (.next/, dist/)
Conjuntos de datos grandes (usa almacenamiento externo)
Archivos binarios (imágenes, videos)

8. Limpia Regularmente

Elimina archivos no utilizados:

Usuario: "Elimina archivos no utilizados en /tmp y ramas antiguas"

Agente: [Limpia el área de trabajo]

Solución de Problemas

Espacio Atrapado en “Inicializando”

Problema: El estado nunca alcanza “listo”

Soluciones:

# Verifica registros de inicialización
teamday spaces logs s-abc123xyz --tail 50

# Cancela y reintenta
teamday spaces delete s-abc123xyz
teamday spaces create --name "Mi Espacio" --type empty

Archivos No Se Sincronizan

Problema: Los cambios no aparecen en S3

Soluciones:

# Verifica que la sincronización esté habilitada
teamday spaces config s-abc123xyz --get SYNC_ENABLED

# Fuerza sincronización
teamday spaces sync s-abc123xyz --direction up

# Verifica registros
teamday spaces logs s-abc123xyz --grep sync

Errores de “Permiso Denegado”

Problema: El agente no puede acceder a archivos

Verifica:

El agente está asignado al espacio
La visibilidad del espacio es correcta
La membresía de org es válida

teamday spaces info s-abc123xyz

La Carga Grande Falla

Problema: La carga de archivo agota el tiempo

Soluciones:

Divide en archivos más pequeños (bajo 100MB cada uno)
Usa CLI en lugar de UI (más confiable)
Comprime antes de cargar (archivos zip)

# Carga vía CLI
teamday spaces upload s-abc123xyz \
  --file large-dataset.csv.gz \
  --dest /data/

Próximos Pasos

Ahora que tienes un espacio configurado:

1. Habilita Integración con Git

Conecta a repositorios de GitHub
Guía: Integración con Git

2. Trabaja con Agentes en Espacios

Ejecuta agentes con contexto del espacio
Guía: Crear Tu Primer Agente

3. Instala Complementos MCP

Añade herramientas para tus agentes
Guía: Complementos MCP

4. Configura Automatización

Programa tareas recurrentes en espacios
Guía: Automatización

Recursos de Aprendizaje

[Referencia de API de Espacios - Documentación completa de API
[Operaciones de Archivos - Gestión avanzada de archivos
[Mejores Prácticas de Seguridad - Asegura tus espacios

¡Feliz construcción de área de trabajo! 🚀