Instalar e rodar a partir de um binário pré-buildado#

Para quando você já tem — ou quer — só o binário opendray, sem que nenhum wizard de instalação mexa na sua máquina. Este é o caminho para:

• npm install -g opendray / npx opendray — o pacote npm traz o binário oficial do release Go (veja README → npm / npx).
• Downloads de release — pegue opendray_*_<os>_<arch>.tar.gz na página de Releases.
• Ambientes com scripts / efêmeros — runners de CI, imagens golden, gerenciamento de configuração (Ansible, Nix, Docker), ou qualquer host onde você já roda seu próprio Postgres e supervisor de processos.

O binário é o gateway completo — a SPA do painel web está embutida, então não há runtime Node, nenhum servidor de arquivos estáticos separado, e nada para buildar. O que ele não faz é configurar nada por você. Essa é a troca: você traz um banco PostgreSQL e uma forma de manter o processo rodando, e em troca nada é instalado, configurado ou registrado por baixo dos panos.

Prefere que tudo seja feito por você? Num Linux / macOS novo, o instalador de uma linha provisiona o Postgres, instala as AI CLIs, escreve o config e registra um serviço em ~5–10 minutos. Veja README → Instalador de uma linha ou o passo a passo manual em getting-started.md.

Este guia te leva de "binário no PATH" a "gateway rodando" em cinco etapas, e depois mostra como mantê-lo rodando como serviço.

Etapa 1 — Obter o binário#

Via npm (qualquer OS com Node ≥ 18)#

O binário correto para a plataforma (opendray-{linux,darwin}-{x64,arm64}) é selecionado automaticamente via optionalDependencies — não há hook de postinstall nem chamada de rede no momento da instalação. Não passe --no-optional: isso pula o pacote de plataforma e deixa o launcher sem binário para executar.

Via arquivo de release#

Verificar#

Plataformas suportadas: Linux (x64, arm64) e macOS (x64, arm64). Windows nativo não tem pacote — use WSL2 e siga o caminho do Linux.

Etapa 2 — Prover o PostgreSQL 15+ com pgvector#

O opendray armazena tudo (sessões, memória, audit log) no PostgreSQL, e seu subsistema de memória precisa da extensão pgvector. Versões de servidor suportadas: 15, 16, 17.

Se você já roda o Postgres, crie um banco e uma role somente CRUD, depois habilite a extensão uma vez com um superusuário:

Após a extensão existir, a role CRUD do opendray executa as migrations sem nenhum acesso de superusuário adicional. Nunca aponte o opendray para uma role de superusuário em produção — forneça uma conta com escopo de projeto e altere a senha fora do fluxo.

Etapa 3 — Configurar#

O opendray lê sua configuração de um arquivo TOML ou puramente de variáveis de ambiente (12-factor) — a env sempre vence sobre o arquivo. O único requisito obrigatório é a URL do banco; todo o resto tem um padrão.

Opção A — variáveis de ambiente (bom para containers / hosts efêmeros)#

Execute opendray serve sem a flag -config e ele carrega inteiramente do ambiente.

Opção B — config.toml#

O mínimo a editar:

Veja config.example.toml para o arquivo completamente anotado (logging, detecção de sessão ociosa, backups, vault, MCP). Passe com -config config.toml nos comandos abaixo. Mantenha segredos fora do TOML em hosts compartilhados — defina OPENDRAY_DATABASE_URL / OPENDRAY_ADMIN_PASSWORD via env e deixe o arquivo sem segredos.

Etapa 4 — Aplicar o schema#

Idempotente — rodar novamente é um no-op quando o schema já está atualizado. Isso precisa ter sucesso antes do primeiro serve.

Etapa 5 — Rodar#

Isso roda em foreground (Ctrl-C para). Você deve ter agora:

Isso é um gateway completo e rodando. Para qualquer coisa além de um teste rápido, rode-o sob um supervisor para que sobreviva a reinicializações e reinicie em caso de crash — veja a seguir.

Rodar como serviço#

opendray serve é exatamente o que o comando de start de uma unit de serviço deve chamar. O opendray traz units prontas e endurecidas; os passos abaixo são os mesmos do README → Deploy de produção, que é a referência autoritativa (bootstrap completo, notas de sandboxing, reverse-proxy/TLS).

Linux — systemd#

O repositório traz uma unit endurecida em deploy/systemd/opendray.service (roda migrate como ExecStartPre, segredos via EnvironmentFile, restart on-failure, sandboxing de syscall/filesystem).

Sem systemd? (LXC sem ele, OpenRC, runit, s6, supervisord…) Aponte seu supervisor para opendray serve -config /etc/opendray/config.toml e rode opendray migrate uma vez como etapa de pré-start. Veja README → Deploy de produção §B.

macOS — launchd#

O repositório traz um LaunchDaemon em deploy/launchd/com.opendray.opendray.plist (sobe no boot, reinicia em caso de crash, loga em /usr/local/var/log/opendray/).

Reinicie: sudo launchctl kickstart -k system/com.opendray.opendray. Desmonte: sudo launchctl bootout system/com.opendray.opendray.

Ambas as units são documentadas por completo — incluindo o layout de segredos e por que MemoryDenyWriteExecute fica desabilitado — em deploy/README.md.

Mantendo atualizado#

Como você atualiza depende de como instalou:

• Instalado via npm — atualize com seu gerenciador de pacotes. opendray update substituiria o binário dentro de node_modules sem o conhecimento do npm e seria sobrescrito na próxima instalação, então não use aqui.

  [object Promise]

• Download de release / instalação via wizard — o binário se auto-atualiza no lugar (baixa o release mais recente, verifica o SHA-256, troca atomicamente por si mesmo):

  [object Promise]

Solução de problemas#

the matching platform package "opendray-…" was not installed O npm foi rodado com --no-optional, ou a instalação foi interrompida. Rode novamente npm install -g opendray (sem --no-optional).

unsupported platform O pacote npm cobre somente Linux/macOS em x64/arm64. Em outros alvos, faça o build a partir do código-fonte — veja quickstart.md.

config: database.url is empty Nem OPENDRAY_DATABASE_URL nem [database].url está definido. Defina um (Etapa 3).

connection refused no migrate/serve O Postgres não está rodando ou o DSN está errado. Confirme que o servidor está ativo e que o host/porta/credenciais no seu DSN estão corretos.

pgvector / extension "vector" is not available A extensão não está instalada no servidor, ou não foi habilitada no banco do opendray. Refaça a Etapa 2 (instale o pacote do SO, depois CREATE EXTENSION vector como superusuário).

Porta já em uso Altere OPENDRAY_LISTEN (ou listen em config.toml) para uma porta livre.

Próximos passos#

• README → Deploy de produção — referência completa de deploy (systemd / launchd / supervisor próprio, hardening, reverse proxy)
• docs/operator-guide.md — ops: topologia de reverse-proxy/TLS, backups criptografados do DB, exportação/importação de dados
• docs/integration-guide.md — escreva uma integração externa contra a API REST + WebSocket
• docs/getting-started.md — o setup guiado e tudo-em-um se você preferir não montar as peças por conta própria