Documentação

Começando com o Qnex

Instalação, CLI, execução remota e limites atuais — somente comandos e fluxos disponíveis no produto.

InstalarApp macOS e CLI portátil assinada.Conectar hostLogin, serviço e presença remota.Escolher ambienteLocal, Terminal Linux ou Terminal Mac.

Instalação

O app Qnex está disponível para macOS 14 ou superior, Windows 10 ou superior e Linux. Há instaladores arm64 e x64 para cada sistema. A CLI é um executável separado e nenhuma instalação depende de acesso ao repositório privado.

bash

# Linux x86_64 ou aarch64
curl --proto '=https' --tlsv1.2 -fsSL \
  https://updates.qnex.dev/install.sh | sh

export PATH="$HOME/.local/bin:$PATH"
qnex --version

O instalador detecta sistema e arquitetura, baixa do R2 público do Qnex e valida tamanho, SHA-256 e assinatura Ed25519 antes da troca atômica. Ele precisa de curl, uma ferramenta SHA-256 e OpenSSL com Ed25519. No macOS, prefira o app; para instalar somente a CLI, use OpenSSL 3.

Por padrão a CLI vai para ~/.local/bin/qnex e não pede root. Para outro destino, defina QNEX_INSTALL_DIR. Instalar o executável como administrador não transforma o daemon em root: os comandos remotos devem ser executados pelo usuário que será dono dos projetos.

Conectar um terminal à conta

No Linux ou Mac que executará os projetos, faça login pelo device flow e instale o serviço. O navegador mostra um código para vincular o terminal à mesma conta usada no app.

bash

qnex auth login
qnex remote install --name "Servidor de desenvolvimento"
qnex remote status

No Linux, o padrão é um serviço systemd do usuário. No macOS, é um LaunchAgent. O daemon abre somente HTTPS/WSS de saída pela porta 443; não é necessário liberar SSH, criar DNS ou expor IP público.

Para containers ou sistemas sem systemd/launchd, use qnex remote serve em primeiro plano. O modo Linux --system instala uma unidade global, mas deve ser iniciado por um usuário normal; executar o daemon como root é recusado.

Local, Terminal Linux e Terminal Mac

No app, Adicionar projeto separa Local — Este Mac, Terminal (Linux) e Terminal (Mac). Cada host mostra presença e plataforma. Depois de escolher o ambiente, você pode abrir uma pasta, clonar um repositório ou iniciar um projeto novo.

Arquivos, busca, editor, Git, terminal, agentes, MCPs, skills, hooks e previews web são executados no host selecionado. O Git e as credenciais de provedores também são os daquele host; chaves do Mac controlador não são copiadas automaticamente.

O caminho faz parte da identidade do projeto junto com o ambiente. /srv/app no host A, /srv/app no host B e /srv/app no Mac local são três projetos diferentes.

Abrir, clonar e criar projetos remotos

Abrir pasta começa na home do usuário do serviço, mas permite escolher qualquer caminho que esse usuário possa acessar. As operações do projeto continuam enraizadas na pasta escolhida; uma nova seleção explícita ou o terminal pode acessar outros caminhos permitidos.

Clonar usa o Git e as credenciais já configuradas no host. Novo projeto oferece pasta vazia e presets para Next.js, Vite React, NestJS, Flutter, Expo e Swift Package, além de comando personalizado. Clone e criação usam diretório temporário e só promovem o destino após sucesso.

Se um processo remoto abrir uma porta web, o app pode encaminhar apenas o loopback do host para o Mac. Previews suportam HMR e WebSocket; isso não é desktop remoto e não expõe a porta publicamente.

Agente pela CLI

Sem prompt, qnex abre uma sessão interativa. Com um prompt posicional, executa um turno e encerra. Não existe subcomando qnex run: as opções vêm antes do texto da tarefa.

bash

qnex --provider openAI --effort high \
  "revise o diff e execute os testes relevantes"

qnex --continue
qnex --providers

Para automação, --json emite um evento por linha. --permission-mode aceita supervised, autoAcceptEdits, auto e fullAccess. Em saída não interativa, uma aprovação pendente é negada em vez de bloquear indefinidamente.

bash

qnex -C /srv/app --json --permission-mode auto \
  "execute os testes e resuma as falhas"

Sessões da CLI são retomadas pela própria CLI com --continue ou --resume. Elas não são a mesma transcrição persistida pelo app macOS.

Provedores, MCPs e credenciais

A CLI aceita OpenAI, Anthropic/Claude, DeepSeek, Kimi, GLM e Grok por API, além de Codex CLI, Claude Code e Grok Build quando os executáveis locais já estão autenticados. No remoto, tudo é resolvido no host que executa o projeto.

bash

export OPENAI_API_KEY=...
qnex --provider openAI --model gpt-5.2 \
  "mapeie a arquitetura deste projeto"

qnex --providers

Configurações persistentes ficam em ~/.qnex/config.json e configurações do projeto em .qnex/. Variáveis de ambiente sobrescrevem o arquivo apenas no processo atual. MCPs, skills e logins de CLIs existentes continuam pertencendo ao host; o relay nunca recebe esses segredos.

Retomada e segurança

App e daemon transportam SSHv2 ponta a ponta por WebSocket. O backend pareia sockets e encaminha bytes opacos. A chave do host é fixada e uma mudança nunca é aceita silenciosamente; autenticação remota usa chave Ed25519, sem senha SSH.

Turnos, clones, inicializações e PTYs continuam no host quando o Mac fecha ou a rede cai. Ao reconectar, cursores, ACKs e chaves de idempotência retomam eventos sem repetir operações mutáveis. Um reboot ou falha do próprio sistema operacional pode interromper processos e é informado como interrupção real.

A auditoria do backend guarda apenas identificadores técnicos, duração, volume e códigos de erro. Caminhos, comandos, arquivos, prompts e saída não são gravados no D1 nem na telemetria do relay.

Status, logs, atualização e remoção

bash

qnex auth status
qnex remote status --json
qnex remote logs
qnex remote update
qnex remote uninstall
qnex auth logout

remote update baixa o artefato correto, confere tamanho, SHA-256 e assinatura Ed25519 com uma chave pública embutida e substitui o executável atomicamente. O reinício do daemon é adiado enquanto houver operações ativas.

remote uninstall remove o serviço e revoga o host remoto. auth logout revoga o dispositivo e apaga a credencial e a identidade remota locais. O executável em ~/.local/bin/qnex só é removido manualmente depois desses passos.

Compatibilidade e limites atuais

O app exige macOS 14+, Windows 10+ ou uma distribuição Linux compatível e é publicado para arm64 e x64. A CLI tem builds próprios. Serviços persistentes usam LaunchAgent no macOS e systemd de usuário no Linux; outros ambientes podem usar o modo foreground.

Execução remota cobre arquivos, Git, terminal, agentes, MCPs, skills, hooks, clone, criação de projeto e preview web. Desktop remoto e Simulator iOS remoto não fazem parte desta versão; o Simulator continua sendo um recurso local do app no Mac.