O agente roda sem permissão de administrador: ele não consegue instalar
pacote do sistema nem subir banco de dados. A tarefa que precisa disso
declara no bloco task:, e o Kadu instala antes de a execução
começar.
task:
dependencies:
apt: [ffmpeg, poppler-utils]
services: [postgres]
O repositório só escolhe nomes de uma lista mantida pela Kobana. Para
um serviço, a versão, a porta, o usuário e a senha vêm da lista, nunca do
repositório.
O que acontece na execução
- A execução começa e o Kadu confere cada nome na lista. Nome fora da lista,
ou desativado nela, faz a execução falhar antes de instalar qualquer coisa.
- Os pacotes são instalados e os serviços sobem na própria máquina da
execução, acessíveis só por ela (
127.0.0.1).
- Cada serviço chega à skill numa variável de ambiente (
DEPENDENCY_POSTGRES_URL
etc.), com a URL de conexão pronta.
- A linha do tempo mostra o passo "dependências" com o tempo gasto, ou o
motivo da falha. Só depois disso a skill começa.
A instalação conta para os 60 minutos da execução: declare só o que a tarefa
usa.
Regras
| Regra | Detalhe |
|---|
| Só nomes da lista | Nome fora da lista aparece nos avisos da sincronização e faz a execução falhar |
| Limites | No máximo 30 pacotes e 5 serviços por tarefa |
| Formato | Listas de texto; outra chave (como npm:) ou outro tipo descarta o bloco inteiro, com aviso |
| Ausente | dependencies fora do frontmatter mantém o que estava gravado; dependencies: {} limpa |
| Pares que não convivem | mysql e mariadb (mesma porta), redis e valkey (mesma porta), mysql-client e mariadb-client. Declarar os dois de um par faz a execução falhar |
| SQLite | É arquivo, não serviço: basta o pacote sqlite3 |
:::info Por que uma lista
Pacote e serviço são instalados com permissão de administrador, antes de a
skill rodar. A lista garante que só entra software conhecido, do repositório
oficial do Ubuntu ou de imagens oficiais fixadas por versão exata. Mesmo com a
lista, o Kadu recusa uma instalação que daria à skill um jeito de virar
administrador da máquina, e a execução falha com o motivo.
:::
Pacotes disponíveis
PDF
| Pacote | Para quê |
|---|
poppler-utils | Extrair texto e imagens, converter páginas (pdftotext, pdftoppm, pdfinfo) |
qpdf | Juntar, dividir, girar, descriptografar e reparar |
pdftk-java | Juntar, dividir e preencher formulários (pdftk) |
mupdf-tools | mutool: extrair, renderizar e limpar |
ghostscript | Renderizar, comprimir e converter PDF/PostScript |
img2pdf | Imagens → PDF sem perda |
ocrmypdf | PDF escaneado → PDF pesquisável (OCR) |
OCR
| Pacote | Para quê |
|---|
tesseract-ocr | OCR de imagens |
tesseract-ocr-por | Idioma português |
tesseract-ocr-eng | Idioma inglês |
tesseract-ocr-spa | Idioma espanhol |
Documentos (DOC, DOCX, ODT, RTF, PPT)
| Pacote | Para quê |
|---|
libreoffice-writer-nogui | DOC/DOCX/ODT: converter e gerar PDF sem interface (soffice --headless) |
libreoffice-impress-nogui | PPT/PPTX/ODP: converter e gerar PDF sem interface |
pandoc | Converter entre Markdown, DOCX, HTML e outros |
antiword | DOC (Word 97-2003) → texto |
catdoc | DOC, XLS e PPT antigos → texto (catdoc, xls2csv, catppt) |
docx2txt | DOCX → texto |
odt2txt | ODT/ODS → texto |
unrtf | RTF → texto ou HTML |
Planilhas e CSV
| Pacote | Para quê |
|---|
libreoffice-calc-nogui | XLS/XLSX/ODS: converter e recalcular sem interface |
gnumeric | ssconvert: XLS/XLSX/ODS/CSV sem LibreOffice |
csvkit | csvlook, csvsql, csvjoin, in2csv (XLSX → CSV) |
miller | mlr: filtrar, agregar e converter CSV/TSV/JSON |
xlsx2csv | XLSX → CSV |
sqlite3 | SQLite: consultar CSV e bancos em arquivo |
Imagens
| Pacote | Para quê |
|---|
imagemagick | Converter, redimensionar e compor imagens |
graphicsmagick | gm convert/mogrify (alternativa ao ImageMagick) |
libvips-tools | vips: imagens grandes com pouca memória |
webp | WebP (cwebp, dwebp) |
optipng | Otimizar PNG sem perda |
jpegoptim | Otimizar JPEG |
pngquant | Compressão de PNG com perda |
librsvg2-bin | SVG → PNG/PDF (rsvg-convert) |
libimage-exiftool-perl | exiftool: metadados de imagem, PDF e áudio |
Áudio e vídeo
| Pacote | Para quê |
|---|
ffmpeg | Cortar, converter e montar áudio e vídeo |
sox | Converter, cortar, normalizar e aplicar efeitos em áudio |
libsox-fmt-mp3 | MP3 no sox |
lame | Codificar MP3 |
flac | FLAC |
opus-tools | Opus (opusenc, opusdec) |
vorbis-tools | OGG Vorbis (oggenc, oggdec) |
mediainfo | Metadados de áudio e vídeo |
Arquivos e dados
| Pacote | Para quê |
|---|
zip | Compactar ZIP |
unzip | Descompactar ZIP |
p7zip-full | 7z, e leitura de RAR e outros formatos |
xmlstarlet | Consultar e editar XML (NF-e, CNAB em XML) |
html2text | HTML → texto |
yq | Consultar e converter YAML e XML |
Serviços e armazenamento
| Pacote | Para quê |
|---|
gh | GitHub CLI |
git-lfs | Git LFS |
rclone | Copiar e sincronizar arquivos com Google Drive, Dropbox, OneDrive, S3 e outros |
s3cmd | S3 e compatíveis |
Clientes de banco
| Pacote | Para quê |
|---|
postgresql-client | psql, pg_dump |
mysql-client | mysql, mysqldump (não convive com mariadb-client) |
mariadb-client | mariadb, mariadb-dump (não convive com mysql-client) |
redis-tools | redis-cli |
valkey-tools | valkey-cli |
Fontes e tela
| Pacote | Para quê |
|---|
fonts-noto-core | Fontes Noto (latim, acentos) |
fonts-noto-color-emoji | Emoji colorido |
fonts-liberation2 | Compatíveis com Arial, Times e Courier |
fonts-dejavu-core | Fontes DejaVu |
xvfb | Tela virtual para navegador com interface |
Serviços disponíveis
| Serviço | Versão | Variável | Valor | Usuário / senha / banco |
|---|
postgres | PostgreSQL 18 | DEPENDENCY_POSTGRES_URL | postgresql://postgres:postgres@127.0.0.1:5432/postgres | postgres / postgres / postgres |
mysql | MySQL 8.4 (LTS) | DEPENDENCY_MYSQL_URL | mysql://root:mysql@127.0.0.1:3306/app | root / mysql / app |
mariadb | MariaDB 11.4 (LTS) | DEPENDENCY_MARIADB_URL | mysql://root:mariadb@127.0.0.1:3306/app | root / mariadb / app |
redis | Redis 7 | DEPENDENCY_REDIS_URL | redis://127.0.0.1:6379 | sem senha |
valkey | Valkey 8 (protocolo Redis) | DEPENDENCY_VALKEY_URL | redis://127.0.0.1:6379 | sem senha |
O banco nasce vazio a cada execução e some com ela: é para trabalho
temporário (montar dados, rodar um app em modo de desenvolvimento), não para
guardar nada entre execuções.
O que não está na lista
| Precisa de | Faça assim |
|---|
| Pacotes de npm, pip ou navegadores | A skill instala na própria pasta, sem permissão de administrador (npm install -g --prefix "$HOME/.local", npx, pip install --user) |
Slack CLI, Google Cloud CLI (gcloud), Linear | Não estão no repositório do Ubuntu. Instale na pasta da skill, ou chame a API HTTP com curl |
| AWS CLI | Não está no Ubuntu 24.04. Para S3, use s3cmd ou rclone |
| Google Drive, Dropbox, OneDrive | rclone |
| Outro pacote ou banco | Peça ao suporte da Kobana (abaixo) |
Pedir um pacote ou serviço
Fale com o suporte da Kobana dizendo o nome e para que a tarefa precisa. O
pacote precisa estar no repositório oficial do Ubuntu 24.04 e não pode trazer
programa com permissão especial; o serviço precisa de imagem oficial. Depois de
incluído, ele vale para as próximas execuções, sem mudar nada no repositório.
Erros comuns
| Sintoma | Causa | Solução |
|---|
| Aviso "fora da lista permitida" na sincronização | Nome não está na lista, ou foi desativado | Corrija o nome ou peça a inclusão |
| Execução falha antes de começar, no passo "dependências" | Nome fora da lista, par que não convive, ou pacote recusado | Leia o motivo na linha do tempo |
dependencies ignorado, com aviso | Chave desconhecida ou tipo errado no bloco | Só apt e services, como listas de texto |
| Conexão recusada ao banco | Serviço não declarado, ou a skill lê outra variável | Declare em services e use a variável DEPENDENCY_* |
| Execução estoura o tempo | Pacotes demais | Declare só o que a tarefa usa |