Guia de Contenedores Docker¶

Otros idiomas¶

Imagen Disponible¶

Contenedor Unificado de Symbi¶

• Imagen: ghcr.io/thirdkeyai/symbi:latest
• Proposito: Contenedor todo en uno con analisis de DSL, runtime de agentes y servidor MCP
• Tamano: ~80MB (incluye base de datos vectorial y soporte de API HTTP)
• CLI: Comando unificado symbi con subcomandos para diferentes operaciones

Inicio Rapido¶

Crear y ejecutar un proyecto (recomendado)¶

symbi init funciona dentro del contenedor y escribe un proyecto en su directorio del host, incluyendo un docker-compose.yml listo para ejecutar y un .env con un SYMBIONT_MASTER_KEY recien generado:

# 1. Create the project files on the host
docker run --rm -v $(pwd):/workspace ghcr.io/thirdkeyai/symbi:latest \
  init --profile assistant --no-interact --dir /workspace

# 2. Start the runtime (reads .env automatically)
docker compose up

El flag --dir /workspace le indica a symbi init que escriba en el volumen montado en lugar del WORKDIR de la imagen. Despues de esto tendra symbiont.toml, agents/, policies/, .symbiont/audit/, AGENTS.md, docker-compose.yml, .env y .env.example en el directorio actual.

Para omitir la generacion del archivo compose:

docker run --rm -v $(pwd):/workspace ghcr.io/thirdkeyai/symbi:latest \
  init --profile minimal --no-interact --no-docker-compose --dir /workspace

Usando la Imagen Pre-construida (ad-hoc)¶

# Pull latest image
docker pull ghcr.io/thirdkeyai/symbi:latest

# Parse an agent definition (`.symbi`; legacy `.dsl` is also accepted)
docker run --rm -v $(pwd):/workspace \
  ghcr.io/thirdkeyai/symbi:latest \
  dsl --file /workspace/agent.symbi

# Run MCP server (stdio-based, no port needed)
docker run --rm -i \
  ghcr.io/thirdkeyai/symbi:latest \
  mcp

# Run the runtime without a project (ephemeral, no master key)
docker run --rm -p 8080:8080 -p 8081:8081 \
  ghcr.io/thirdkeyai/symbi:latest \
  up --http-bind 0.0.0.0

Flujo de Trabajo de Desarrollo¶

# Interactive development
docker run --rm -it -v $(pwd):/workspace \
  ghcr.io/thirdkeyai/symbi:latest bash

# Development with volume mounts and ports
docker run --rm -it \
  -v $(pwd):/workspace \
  -p 8080:8080 \
  -p 8081:8081 \
  ghcr.io/thirdkeyai/symbi:latest bash

Etiquetas Disponibles¶

• latest - Ultima version estable
• main - Ultima compilacion de desarrollo
• v1.0.0 - Versiones especificas
• sha-<commit> - Compilaciones de commits especificos

Compilacion Local¶

Contenedor Unificado de Symbi¶

# From project root
docker build -t symbi:latest .

# Test the build
docker run --rm symbi:latest --version

# Test DSL parsing
docker run --rm -v $(pwd):/workspace symbi:latest dsl --help

# Test MCP server
docker run --rm symbi:latest mcp

Soporte Multi-Arquitectura¶

Las imagenes se compilan para: - linux/amd64 (x86_64) - linux/arm64 (ARM64/Apple Silicon)

Docker descarga automaticamente la arquitectura correcta para su plataforma.

Caracteristicas de Seguridad¶

Ejecucion Sin Root¶

• Los contenedores se ejecutan como el usuario no root symbi (UID 1000)
• Superficie de ataque minima con imagenes base reforzadas en seguridad

Escaneo de Vulnerabilidades¶

• Todas las imagenes se escanean automaticamente con Trivy
• Los avisos de seguridad se publican en la pestana de Seguridad de GitHub
• Informes SARIF para analisis detallado de vulnerabilidades

Configuracion¶

Variables de Entorno¶

Contenedor Symbi: - SYMBIONT_MASTER_KEY - Requerido para estado persistente. Clave hexadecimal de 32 bytes usada para cifrar el almacen local. Genere con openssl rand -hex 32. symbi init escribe una en .env automaticamente. - RUST_LOG - Establecer nivel de registro (debug, info, warn, error) - SYMBIONT_VECTOR_BACKEND - Backend vectorial: lancedb (predeterminado) o qdrant - QDRANT_URL - URL de la base de datos vectorial Qdrant (solo si se usa el backend opcional de Qdrant) - OPENROUTER_API_KEY / OPENAI_API_KEY / ANTHROPIC_API_KEY - Credenciales LLM opcionales; cualquiera habilita el endpoint Coordinator Chat.

Montajes de Volumenes¶

La imagen se ejecuta como usuario symbi (UID 1000) con WORKDIR=/var/lib/symbi. Los archivos del proyecto se montan en modo solo lectura en ese directorio; el estado persistente (el almacen SQLite local y los registros de auditoria) vive en volumenes con nombre para que sobreviva a reinicios del contenedor.

# Project files (read-only)
-v $(pwd)/symbiont.toml:/var/lib/symbi/symbiont.toml:ro
-v $(pwd)/agents:/var/lib/symbi/agents:ro
-v $(pwd)/policies:/var/lib/symbi/policies:ro
-v $(pwd)/tools:/var/lib/symbi/tools:ro

# Persistent state
-v symbi-data:/var/lib/symbi/.symbi
-v symbi-audit:/var/lib/symbi/.symbiont

Ejemplo de Docker Compose¶

symbi init genera un docker-compose.yml listo para ejecutar que coincide con el resto de esta seccion — preferirlo a escribir un archivo compose a mano. Como referencia, o al empezar sin init:

Por defecto, Symbiont usa LanceDB como base de datos vectorial integrada -- no se requieren servicios externos. Si necesita un backend vectorial distribuido para despliegues a escala, puede agregar opcionalmente Qdrant.

Valores predeterminados de seguridad (auditoria posterior a v1.13.0). El docker-compose.test.yml incluido ahora exige que SYMBIONT_API_TOKEN este definido en el entorno (sin valor por defecto — testtoken123 fue eliminado) y vincula los puertos publicados a 127.0.0.1 en lugar de 0.0.0.0. El runtime ademas rechaza cualquier token que sea exactamente testtoken123 o que comience con test y tenga menos de 20 caracteres; esto evita el redespliegue accidental del valor predeterminado historico. Consulta .env.example para las variables requeridas y SECURITY_AUDIT.md C5 para la justificacion.

Minimo (LanceDB predeterminado -- no se necesita Qdrant)¶

Combinelo con un archivo .env que defina SYMBIONT_MASTER_KEY:

services:
  symbi:
    image: ghcr.io/thirdkeyai/symbi:latest
    command: ["up", "--http-bind", "0.0.0.0"]
    ports:
      - "8080:8080"
      - "8081:8081"
    volumes:
      - ./symbiont.toml:/var/lib/symbi/symbiont.toml:ro
      - ./agents:/var/lib/symbi/agents:ro
      - ./policies:/var/lib/symbi/policies:ro
      - ./tools:/var/lib/symbi/tools:ro
      - symbi-data:/var/lib/symbi/.symbi
      - symbi-audit:/var/lib/symbi/.symbiont
    environment:
      SYMBIONT_MASTER_KEY: ${SYMBIONT_MASTER_KEY:?set SYMBIONT_MASTER_KEY in .env}
      RUST_LOG: ${RUST_LOG:-info}
    restart: unless-stopped

volumes:
  symbi-data:
  symbi-audit:

Con Backend Opcional de Qdrant¶

services:
  symbi:
    image: ghcr.io/thirdkeyai/symbi:latest
    command: ["up", "--http-bind", "0.0.0.0"]
    ports:
      - "8080:8080"
      - "8081:8081"
    volumes:
      - ./symbiont.toml:/var/lib/symbi/symbiont.toml:ro
      - ./agents:/var/lib/symbi/agents:ro
      - ./policies:/var/lib/symbi/policies:ro
      - symbi-data:/var/lib/symbi/.symbi
      - symbi-audit:/var/lib/symbi/.symbiont
    environment:
      SYMBIONT_MASTER_KEY: ${SYMBIONT_MASTER_KEY:?set SYMBIONT_MASTER_KEY in .env}
      RUST_LOG: ${RUST_LOG:-info}
      SYMBIONT_VECTOR_BACKEND: qdrant
      QDRANT_URL: http://qdrant:6334
    depends_on:
      - qdrant
    restart: unless-stopped

  qdrant:
    image: qdrant/qdrant:latest
    ports:
      - "6333:6333"
      - "6334:6334"
    volumes:
      - qdrant-data:/qdrant/storage

volumes:
  symbi-data:
  symbi-audit:
  qdrant-data:

Solucion de Problemas¶

Problemas Comunes¶

Permiso Denegado:

# Ensure correct ownership
sudo chown -R 1000:1000 ./data

# Or use different user
docker run --user $(id -u):$(id -g) ...

Conflictos de Puertos:

# Use different ports
docker run -p 8081:8080 ghcr.io/thirdkeyai/symbi:latest

Fallos de Compilacion:

# Clear Docker cache
docker builder prune -a

# Rebuild without cache
docker build --no-cache .

Verificaciones de Salud¶

# Check container health
docker run --name symbi-test -d ghcr.io/thirdkeyai/symbi:latest up --http-bind 0.0.0.0:8080
docker exec symbi-test /usr/local/bin/symbi --version
docker rm -f symbi-test

Optimizacion de Rendimiento¶

Limites de Recursos¶

# Set memory and CPU limits
docker run --memory=512m --cpus=1.0 \
  ghcr.io/thirdkeyai/symbi:latest mcp

Optimizacion de Compilacion¶

# Use BuildKit for faster builds
DOCKER_BUILDKIT=1 docker build .

# Multi-stage caching
docker build --target builder -t symbi-builder .
docker build --cache-from symbi-builder .

Integracion CI/CD¶

GitHub Actions compila y publica automaticamente los contenedores cuando: - Se hace push a la rama main - Se crean nuevas etiquetas de version (v*) - Se abren pull requests (solo compilacion)

Las imagenes incluyen metadatos: - SHA del commit de Git - Marca de tiempo de compilacion - Resultados del escaneo de vulnerabilidades - SBOM (Software Bill of Materials)