docs/quick-start.pt-BR.md

Rama main · réplica de lectura del repositorio original.

# Portico MCP: início rápido (PT-BR)

O Portico MCP é instalado pelo terminal, com Docker Compose e scripts transparentes deste repositório.

## Pré-requisitos

Antes de executar a instalação guiada:

- VPS ou computador Linux; Ubuntu 24.04 LTS é o alvo homologado do candidato de lançamento;
- Docker Engine 24 ou superior e plugin Docker Compose v2/v5;
- pelo menos 2 GB de RAM para a instalação do ZITADEL incluída;
- Git, OpenSSL, Python 3 e curl;
- DNS público para o domínio MCP, portas TCP 80/443 acessíveis e HTTPS com certificado válido;
- conta/workspace ChatGPT Web em que Modo Desenvolvedor e cadastro de aplicativo MCP personalizado estejam efetivamente disponíveis.

A OpenAI controla a disponibilidade por plano, conta, workspace e distribuição gradual. Verifique a interface realmente oferecida à sua conta. A documentação oficial descreve acesso integral de escrita/modificação por MCP em Business, Enterprise e Edu. Separadamente, em 06/10/2026, uma conta Plus do operador do Portico demonstrou escrita, leitura e exclusão com escopo delimitado. Isso comprova aquele ambiente específico e não garante a mesma capacidade para todas as contas Plus. Consulte a documentação oficial e teste a sua conta antes de começar.

## Instale pelo terminal

~~~bash
git clone https://github.com/josemirmoura/mcp-vps-agent-gateway.git
cd mcp-vps-agent-gateway
bash scripts/install.sh
~~~

O instalador identifica o idioma do terminal. Inicialmente há suporte a português do Brasil e inglês. Você pode escolher explicitamente:

~~~bash
bash scripts/install.sh --lang pt-BR
# ou
bash scripts/install.sh --lang en
~~~

O banner identifica o produto e a versão, incluindo a autoria:

~~~text
Feito por Josemir Moura | github.com/josemirmoura
~~~

## Etapas da instalação guiada

~~~text
Pré-requisitos
 -> Escopo físico da máquina
 -> Resumo da autoridade efetiva
 -> Contêineres
 -> Verificação local
 -> Acesso público seguro
 -> Conexão com ChatGPT
 -> Chamada MCP real registrada na auditoria
 -> INSTALAÇÃO CONCLUÍDA / INSTALLATION COMPLETE
~~~

Antes de criar o estado do Portico, o instalador verifica Linux, Docker Engine/Compose, ferramentas do host, systemd, memória e, para acesso público, as condições de proxy de borda. Se faltar um requisito obrigatório, ele interrompe o processo e apresenta a documentação oficial para instalação.

Quando encontra um Traefik compatível existente, o Portico o reutiliza. Se não encontrar Traefik e as portas 80/443 estiverem livres, instala o Traefik incluído. Ele nunca substitui silenciosamente outro serviço que esteja ocupando essas portas.

Se uma etapa for interrompida, o instalador pode ser executado novamente. Os scripts preservam o estado local, exceto quando o operador solicita explicitamente a remoção completa.

## Modelo recomendado de autoridade: Standard

A opção interativa padrão é **Standard**.

~~~text
teto físico do filesystem: /opt
raízes estáticas autorizadas: nenhuma
acesso aos projetos: aprovação explícita posterior
~~~

O teto físico limita onde o Portico poderá receber permissão no futuro. Ele **não autoriza automaticamente** a leitura ou a escrita em /opt durante a instalação.

Depois de conectar o ChatGPT, o operador poderá aprovar uma subpasta ou o teto físico exato. A autorização para todo o teto apresenta um aviso reforçado: o perfil escolhido alcançará os caminhos atuais e futuros dentro desse teto até a revogação.

Comando não interativo equivalente:

~~~bash
bash scripts/install.sh --profile custom --scope /opt
~~~

O argumento da CLI continua sendo custom por compatibilidade; o nome mostrado ao operador na interface é Standard.

Após conectar o ChatGPT, a autorização de projeto ocorre assim:

~~~text
permissions.request_root_access
        |
        v
confirmação nativa do cliente MCP (elicitation)
        |
        v
Broker ativa read / work / compose apenas para a raiz aprovada
~~~

O modelo de IA não pode aprovar a própria ampliação de permissões. Em clientes com suporte a elicitação MCP, a confirmação ocorre na interface nativa, sem uma ferramenta de autoaprovação nem um token utilizável pelo modelo. O Broker vincula a decisão à identidade autenticada e à solicitação pendente.

## Autorização Scoped quando o chat não mostra elicitation

Se o resultado indicar `approval_method=operator_fallback` e `request_id=apr_...`, existe um pedido **pendente**, não uma aprovação. Em uma sessão SSH confiável, separada do chat, já dentro do checkout do Pórtico na sua máquina Linux, use o CLI Community de operador:

~~~bash
python3 scripts/operator-approvals.py --list
python3 scripts/operator-approvals.py
~~~

O primeiro comando lista pedidos pendentes não expirados. O segundo permite revisão interativa. Compare o ID exibido na conversa com a identidade, pasta, perfil e duração. Somente o operador com acesso autorizado à máquina deve digitar a frase exata `APROVAR apr_...` ou `NEGAR apr_...`. Divergência, prazo expirado ou cancelamento não concedem nada. Também é possível usar `python3 scripts/operator-approvals.py --request apr_ID_REAL` com o **ID real** da solicitação.

O CLI exige conta confiável com acesso Docker, que corresponde a um privilégio administrativo poderoso no Linux. Esse acesso, o login SSH e tokens do operador não devem ficar disponíveis para a IA. Um link/ID, isoladamente, não autoriza nada; estar conectado ao ChatGPT não comprova a identidade do aprovador. Depois, consulte `permissions.list_root_access` para verificar a delegação. Esse fallback **não** comprova que os botões de autorização nativos do ChatGPT funcionam. Veja também o [guia completo de fallback do operador](operator-approval-fallback.md), já disponível em português.

## Perfil restrito a um projeto

Escolha este perfil quando o Portico não deve operar fora de uma pasta específica.

~~~bash
bash scripts/install.sh \
  --profile project \
  --scope /opt/my-app
~~~

Se a pasta não existir, a interface guiada poderá oferecer sua criação explícita. Em modo de comando:

~~~bash
bash scripts/install.sh \
  --profile project \
  --scope /opt/my-app \
  --create-scope
~~~

## Whole Host

O perfil Whole Host altera o **teto físico do filesystem** do Broker para /.

Ele não habilita automaticamente o modo Full, a rede irrestrita, a administração de pacotes, usuários ou firewall.

~~~bash
bash scripts/install.sh --profile whole-host
~~~

O instalador exige confirmação explícita antes de iniciar esse perfil.

## Usuário de execução do shell

Os trabalhos de shell confinados usam uma conta real não-root do host. O instalador detecta automaticamente o usuário não-root que iniciou a instalação.

Para escolher outra conta não-root já existente:

~~~bash
bash scripts/install.sh --run-as deploy
~~~

As tarefas normais de shell com escopo não são configuradas para rodar como root.

## Autorizações dinâmicas de pastas

No modo Standard, nenhuma raiz de projeto é autorizada durante a instalação.

Após conectar o ChatGPT, estão disponíveis:

~~~text
permissions.request_root_access
permissions.list_root_access
permissions.revoke_root_access
~~~

Perfis de acesso:

- **read:** leitura de arquivos;
- **work:** leitura e escrita, além de shell confinado à raiz autorizada;
- **compose:** tudo de work, mais operações Compose já permitidas pela política estática de ações.

As autorizações podem ser permanentes ou temporárias e entram em vigor sem reiniciar o Broker.

Para usos avançados, raízes estáticas também podem ser gerenciadas pelo terminal com scripts/delegate-root.sh, mas isso não faz parte do fluxo guiado normal.

## Domínio público e operador OAuth

Para conectar o ChatGPT pela internet, o instalador explica como criar um nome DNS como mcp.example.com, apontar o registro A/AAAA para a VPS e informar apenas o domínio, sem https:// nem /mcp. O DNS é verificado antes de avançar.

A integração OAuth cria uma conta exclusiva de operador Portico. O instalador informa:

~~~text
Nome de usuário: vps-operator
E-mail:         operator@example.com
~~~

A tela OAuth utiliza o **nome de usuário**. Essa identidade é separada das credenciais Linux/SSH/root da VPS.

## Concluir a conexão com ChatGPT

Após verificar o OAuth público, scripts/connect-chatgpt.sh apresenta um tutorial de conexão, o endpoint MCP correto e o usuário de login.

Na instalação interativa, não há contagem regressiva oculta. Cadastre o aplicativo MCP no ChatGPT, conclua o login OAuth, execute a chamada inofensiva system.info e volte ao terminal. Pressione Enter para confirmar. Se a auditoria ainda não tiver detectado a chamada, o Portico indica o que verificar e permite tentar novamente.

A instalação só termina quando a chamada autenticada passa por Gateway, Broker, política e auditoria. Contêineres saudáveis, isoladamente, não concluem o processo.

## Validação apenas local

Para validar o pacote sem OAuth público nem ChatGPT:

~~~bash
bash scripts/install.sh \
  --profile custom \
  --scope /opt \
  --local-only \
  --yes
~~~

Nesse modo, nenhuma raiz estática de projeto é autorizada e a instalação para intencionalmente antes do acesso público. **Não considere esse teste uma instalação completa.**

## Remoção segura e limpeza completa

Remoção segura: preserva a configuração local do operador e o histórico de auditoria.

~~~bash
bash scripts/remove.sh safe
~~~

Limpeza completa: remove runtime, volumes e estado/configuração pertencentes ao Portico MCP, além das imagens Gateway/Broker compiladas localmente por padrão.

~~~bash
VPS_AGENT_PURGE_CONFIRM=PURGE \
bash scripts/remove.sh --purge
~~~

Para excluir também o diretório de código clonado, há uma segunda confirmação explícita:

~~~bash
VPS_AGENT_PURGE_CONFIRM=PURGE \
VPS_AGENT_REMOVE_SOURCE_CONFIRM=REMOVE_SOURCE \
bash scripts/remove.sh --purge --remove-source
~~~

A limpeza não elimina pastas de projetos delegados, imagens de terceiros, aplicações, bancos de dados ou serviços não pertencentes ao Portico. A pasta antiga /opt/vps-agent-sandbox só é removida caso esteja vazia.

## Recuperação quando uma etapa falha

**Falha local/do runtime:** confira os serviços e execute novamente as verificações locais. Não faça purge apenas porque uma checagem falhou.

~~~bash
bash scripts/diagnose.sh status
bash scripts/diagnose.sh health
bash scripts/verify.sh
~~~

**Falha de DNS/HTTPS/OAuth:** verifique se o DNS aponta para o host Linux correto e se as portas TCP 80/443 alcançam o Traefik configurado. Após corrigir a configuração com segurança, reavalie a autenticação pública.

~~~bash
bash scripts/verify-public.sh
~~~

**A opção de aplicativo MCP não aparece no ChatGPT:** confira a conta/workspace e a disponibilidade efetiva de Developer Mode / Plugins. Uma VPS saudável não habilita recursos inexistentes na conta.

**MCP conectado, mas nenhuma chamada auditada:** confirme o endpoint exato `https://<domain>/mcp`, entre com o **usuário de operador OAuth** (normalmente `vps-operator`, não o login Linux), chame `system.info`, volte ao terminal e pressione Enter para repetir a checagem da auditoria com baseline fixo. Sem novo evento, a instalação não está concluída.

**Janela de aprovação ausente ou ilegível:** não presuma consentimento nem permita autoaprovação pela IA. Use somente alternativa de operador autenticada, realmente incluída na versão instalada; caso contrário, mantenha o pedido pendente. Registre evidência sanitizada de cliente/dispositivo para o gate #65.

**Atualização, backup ou migração interrompidos:** não use purge como tentativa de recuperação. Preserve o estado e consulte as evidências do lifecycle/rollback da versão instalada; a recuperação de todos os modos de falha ainda exige aceite separado.


## Seleção da versão e segurança da instalação

A release estável `v0.1.0` **ainda não foi publicada**. Não tente clonar uma tag estável inexistente nem trate a branch `main` mutável como release assinada.

Para inspeção e validação de pré-lançamento, use o clone indicado no começo deste guia. Depois da publicação e verificação de uma release imutável, selecione a tag efetivamente publicada e verifique os checksums, digests e assinaturas correspondentes. O checkout Git permite atualização controlada com checagem de fast-forward, backup e rollback, sujeitos ao aceite real do lifecycle.

Até lá, este é um candidato pré-estável. A conclusão exige instalação limpa em Linux, chamada MCP autenticada de cliente compatível e auditoria do Broker, sem prometer aprovação visual mobile já aceita.

[English Quick Start](quick-start.md).