← Volver al listado de tecnologías ← Índice de Goose

2. Instalación

Por: Artiko
gooseinstalacionclidesktopmacoslinuxwindows

2. Instalación

Goose viene en dos sabores: CLI (la que vas a usar para trabajo serio) y Desktop (UI gráfica con algunos extras). Podés instalar las dos: comparten la misma configuración subyacente.

Pre-requisitos

Instalación CLI

macOS / Linux

Script oficial:

curl -fsSL https://github.com/block/goose/releases/download/stable/download_cli.sh | bash

Lo que hace:

  1. Detecta tu OS y arquitectura.
  2. Descarga el binario de la última release estable.
  3. Lo coloca en ~/.local/bin/goose y agrega PATH si hace falta.

Homebrew (macOS)

brew install goose

Más limpio si ya usás Homebrew. Las actualizaciones las maneja brew upgrade.

Windows

Recomendado: WSL2 con Ubuntu y luego el script de macOS/Linux. El soporte nativo en Windows existe pero algunas extensiones MCP esperan utilidades Unix.

wsl --install -d Ubuntu
# después del reboot
wsl
curl -fsSL https://github.com/block/goose/releases/download/stable/download_cli.sh | bash

Desde fuente (Rust)

Goose está escrito en Rust. Si querés compilarlo:

git clone https://github.com/block/goose
cd goose
cargo build --release
sudo cp target/release/goose /usr/local/bin/

Solo recomendado si necesitás features pre-release o vas a contribuir.

Instalación Desktop

Descargás el instalador de la página de releases:

La app Desktop comparte la configuración con la CLI (~/.config/goose/), así que cualquier provider que configures por una se ve desde la otra.

Verificación

goose --version
# goose 1.x.y

goose --help
# muestra todos los subcomandos

Salida esperada de --help:

goose - Your open source AI agent

USAGE:
  goose [OPTIONS] [SUBCOMMAND]

SUBCOMMANDS:
  session       Start an interactive session
  run           Run a recipe or single task
  configure     Configure providers, extensions, settings
  recipe        Manage recipes
  project       Manage projects
  extension     Manage extensions
  bench         Benchmark provider performance
  update        Update goose to the latest version

Si goose no se encuentra, agregá ~/.local/bin al PATH:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Estructura de archivos creada

Después de la primera ejecución de cualquier subcomando que toque config:

~/.config/goose/
├── config.yaml           # configuración principal
├── recipes/              # recipes locales
├── projects/             # definiciones de proyectos
├── sessions/             # historial persistente de sesiones
├── extensions/           # cache de servidores MCP descargados
└── logs/                 # logs estructurados

~/.local/share/goose/
├── data/                 # state que no es config
└── cache/

En macOS reemplazá ~/.config/goose por ~/Library/Application Support/goose (Goose respeta XDG en Linux y la convención macOS por defecto).

Configuración inicial (goose configure)

El comando guiado para primera setup:

goose configure

Te va a preguntar:

  1. ¿Qué provider querés? (Claude Code, Codex, Cursor Agent, Gemini CLI, OpenAI-compat, ACP).
  2. ¿Configurar API key? (si aplica al provider).
  3. ¿Habilitar built-in extensions? (filesystem, shell, web fetch, etc.).
  4. ¿Modelo default?

El resultado es un ~/.config/goose/config.yaml similar a:

goose_provider: claude-code
goose_model: claude-sonnet-4-5

extensions:
  developer:
    enabled: true
    type: builtin
  computer-use:
    enabled: false
    type: builtin
  fetch:
    enabled: true
    type: builtin

Vamos a desentrañar este YAML en detalle en el capítulo 4.

Errores típicos en la instalación

”command not found: goose”

~/.local/bin no está en tu PATH. Reabrí la terminal o source ~/.zshrc.

”permission denied” al instalar con script

El script intenta escribir en ~/.local/bin, que debería existir y ser tuyo. Si está roto:

mkdir -p ~/.local/bin
chmod 755 ~/.local/bin

“no provider configured” al primer goose session

Faltó el goose configure. Corrélo y elegí provider.

Desktop no abre en macOS por notarización

xattr -cr /Applications/Goose.app

Quita el quarantine flag.

Errores de firewall / SSL

Algunas redes corporativas bloquean github.com o el endpoint de releases. Pedile al equipo de infra el proxy correspondiente:

export HTTPS_PROXY=http://proxy.empresa.com:8080
curl -fsSL ... | bash

Actualización

goose update

Si lo instalaste con Homebrew:

brew upgrade goose

Para Desktop: la app revisa actualizaciones automáticamente al arrancar.

Pro tip: cuando una update mete breaking changes de configuración, el changelog lo dice. Leé el changelog antes de updatear en producción / scripts críticos.

Desinstalación

# CLI
rm ~/.local/bin/goose
# o
brew uninstall goose

# Configuración (CUIDADO: pierde sessions y recipes)
rm -rf ~/.config/goose ~/.local/share/goose

# Desktop macOS
rm -rf /Applications/Goose.app

¿Qué viene?

Goose está instalado y respondiendo a --version. En el próximo capítulo lanzamos la primera sesión interactiva, generamos un cambio en código real y entendemos qué está haciendo el agente bajo el capó.

← Volver al listado de tecnologías ← Índice de Goose