O que é o vphone-cli

O vphone-cli é um projeto de linha de comando que inicializa um iPhone virtual no macOS usando o Virtualization.framework da Apple e uma infraestrutura de máquina virtual de pesquisa chamada PCC. A proposta é colocar um ambiente virtual de iPhone no Mac para experimentos técnicos, sem tratar a ferramenta como um substituto universal para um aparelho físico.

O repositório é mantido por Lakr233, está escrito em Swift e usa a licença MIT. O registro público do projeto no GitHub foi criado em fevereiro de 2026, e a ferramenta ganhou atenção por automatizar várias etapas que normalmente ficariam espalhadas entre download de firmware, preparação, restauração e primeiro boot.

O interesse para desenvolvedores brasileiros está no fluxo reproduzível. Em vez de depender apenas de uma interface gráfica, você pode criar, listar, clonar, configurar, iniciar e exportar máquinas virtuais por comandos. Isso é útil para quem pesquisa sistemas Apple, ferramentas de teste e automação local em um Mac compatível.

Como funciona

O vphone-cli reúne em um único pipeline as etapas de preparação do firmware, aplicação de patches, inicialização em DFU, restauração e instalação de um ambiente CFW. O comando de criação automatiza esse caminho e deixa os comandos individuais disponíveis para quem precisa investigar ou repetir somente uma etapa.

A base é o Virtualization.framework, uma API da Apple para virtualização no macOS. O projeto também usa uma infraestrutura de máquina virtual de pesquisa e depende de componentes específicos do sistema para preparar o convidado. Por isso, a experiência não é igual à de abrir um simulador tradicional de iOS.

Há cinco variantes de firmware no projeto: less, regular, dev, jb e exp. Elas representam níveis crescentes de alterações no processo de inicialização. A diferença entre elas é técnica e relevante: quanto mais permissiva a variante, maior deve ser o cuidado com o equipamento e com os dados usados no teste.

⚠️
Atenção

O próprio projeto documenta relaxamentos de SIP e AMFI como parte dos pré-requisitos. Faça esse tipo de experimento apenas em um Mac de testes, com backup atualizado e sem dados de trabalho importantes.

Principais recursos

A ideia central é transformar várias tarefas de laboratório em comandos consistentes. O projeto oferece operações para administrar o ciclo de vida das máquinas e para repetir o preparo de firmware quando necessário.

  • Criação ponta a ponta: o comando vm create executa download, preparação, restauração e primeiro boot em sequência.
  • Gerenciamento de VMs: é possível listar, consultar, criar um pacote vazio, alterar CPU e memória, clonar, exportar, importar, renomear e excluir uma VM.
  • Controle por etapas: os comandos fw prepare, fw patch, restore e cfw install permitem conduzir o processo manualmente.
  • Formas de acesso: o projeto documenta conexão por SSH em uma porta dedicada e acesso por VNC.
  • Armazenamento local: os dados ficam sob ~/.vphone por padrão, com variáveis de ambiente para trocar a raiz da biblioteca e do ambiente Python.

O diferencial é a combinação entre automação e controle fino. Você pode começar com um comando curto e, quando uma etapa exigir investigação, repetir o fluxo de forma explícita em vez de depender de uma caixa-preta.

Como começar: instalação e acesso passo a passo

O primeiro filtro é o hardware. O README do projeto lista Apple Silicon, macOS 15 ou superior, Xcode e o SDK do iOS como pré-requisitos do host. A instalação também depende de ferramentas distribuídas pelo Homebrew.

Depois de confirmar os requisitos, instale as dependências listadas pelo projeto e o pacote do tap oficial do mantenedor:

brew install [email protected] aria2 wget gnu-tar openssl@3 ldid-procursus sshpass keystone cmake libusb ipsw zstd; brew install zqxwce/tap/vphone-cli

Para compilar a partir do código, clone o repositório com os submódulos, prepare as ferramentas e execute o script de build. O resultado fica no diretório de build descrito pelo próprio projeto:

git clone --recurse-submodules https://GitHub.com/Lakr233/vphone-cli.git; cd vphone-cli; ./scripts/setup_tools.sh; ./scripts/build.sh

Antes de criar uma VM, leia a seção de SIP e AMFI do README e avalie se o Mac de testes é adequado. O projeto oferece uma opção mais permissiva e outra de relaxamento direcionado, mas ambas alteram proteções do sistema e não devem ser aplicadas automaticamente em uma máquina usada no dia a dia.

Exemplo prático

Suponha que você tenha um Mac Apple Silicon com macOS compatível e queira criar uma VM chamada myphone usando a variante jb documentada no projeto. Depois de instalar as dependências e concluir a preparação do ambiente, a criação pode ser iniciada com:

vphone-cli vm create myphone -V jb; vphone-cli vm launch myphone

O primeiro comando concentra o pipeline de download, preparação, restauração e instalação do CFW. O segundo inicia a VM criada. Se o objetivo for apenas verificar o inventário, o projeto também documenta comandos para listar as VMs e consultar as informações de uma máquina específica.

vphone-cli vm list --json; vphone-cli vm info myphone

Quando você precisa separar o diagnóstico em etapas, crie um pacote vazio, prepare o firmware, aplique a variante, inicialize em DFU e execute a restauração conforme a ordem do README. Esse modo é mais demorado, mas ajuda a identificar em qual parte o ambiente deixou de funcionar.

Comparação com alternativas

O vphone-cli ocupa um espaço diferente do simulador de iOS incluído nas ferramentas da Apple. O simulador costuma ser a escolha direta para testar interfaces e fluxos de um aplicativo em desenvolvimento. O vphone-cli é mais experimental e orientado à criação de uma máquina virtual de iPhone com um pipeline próprio de firmware.

Um aparelho físico continua sendo importante quando o teste depende de sensores, desempenho real, acessórios, rede móvel ou diferenças entre modelos. A virtualização pode acelerar experimentos locais, mas não elimina a necessidade de validar o comportamento que depende do hardware.

Serviços de dispositivos na nuvem são outra alternativa para equipes que precisam de vários modelos ou integração com CI. Nesse caso, o ganho é a matriz de dispositivos pronta. O ponto forte do vphone-cli é manter o laboratório sob controle local, com código aberto, comandos reproduzíveis e sem depender de um serviço remoto para cada execução.

Pontos positivos e limitações

Entre os pontos positivos estão o controle por terminal, a possibilidade de automatizar operações repetitivas e a transparência de um repositório público. A licença MIT também facilita estudar o código e adaptar o projeto dentro dos termos da licença.

As limitações são importantes. O host precisa ser Apple Silicon com macOS 15 ou superior, além de Xcode e do SDK do iOS. O processo usa várias ferramentas externas, baixa componentes de firmware e pode exigir configurações sensíveis de segurança do sistema.

Também é uma ferramenta de pesquisa e experimentação, não uma garantia de compatibilidade com todos os aplicativos ou versões de iPhone. Um fluxo que funcione em uma combinação de Mac, firmware e variante pode exigir ajustes quando qualquer um desses elementos mudar.

🔴
Cuidado

Não use o vphone-cli como única validação antes de colocar um aplicativo em produção. Mantenha testes complementares no simulador oficial, em aparelhos físicos e nos serviços de CI que façam parte da sua matriz.

Casos de uso reais

Pesquisadores de sistemas Apple: podem usar a ferramenta para estudar o fluxo de uma máquina virtual de iPhone e observar como as etapas de firmware, patches e primeiro boot se relacionam.

Desenvolvedores Swift: podem manter um ambiente local de laboratório para investigar integrações e testar comandos auxiliares sem transformar cada experimento em uma operação manual longa.

Profissionais de segurança: podem analisar um ambiente de pesquisa isolado, desde que usem equipamento separado, dados descartáveis e uma compreensão clara dos relaxamentos de SIP e AMFI envolvidos.

Equipes de ferramentas internas: podem avaliar os comandos de listagem, informação, exportação e importação para montar rotinas reprodutíveis. Esse uso deve começar em uma máquina de testes e com validação manual de cada etapa.

Dicas e boas práticas

O maior ganho vem de tratar o vphone-cli como infraestrutura de laboratório. Registre a versão do macOS, a variante escolhida, o firmware usado e o resultado de cada execução. Assim, um problema pode ser reproduzido sem depender da memória de quem fez o primeiro teste.

💡
Dica

Use um Mac separado para os experimentos e faça backup antes de alterar proteções do sistema. O equipamento de trabalho não deve ser o primeiro lugar para testar um fluxo de pesquisa.

🚀
Pro tip

Prefira vm list --json em scripts e guarde a saída junto com os logs do laboratório. O formato estruturado reduz erros quando uma rotina precisa localizar uma VM pelo nome.

⚠️
Atenção

Leia o README na versão atual antes de repetir os comandos. Firmware, requisitos de macOS e ferramentas auxiliares podem mudar, e o histórico do repositório é a referência para o estado do projeto.

🔴
Cuidado

Não execute variantes mais permissivas em uma máquina com dados sensíveis. Comece com um cenário descartável e interrompa o teste se uma etapa pedir uma alteração que você não consegue explicar.

Vale a pena?

Vale a pena para quem trabalha com pesquisa, ferramentas de desenvolvimento Apple ou automação de laboratórios e já possui um Mac compatível. O projeto reúne um fluxo difícil de reproduzir manualmente e oferece comandos úteis para inspecionar e administrar as VMs.

Não é a escolha mais simples para quem só quer testar uma tela de aplicativo. Nesse cenário, o simulador oficial ou um aparelho físico costuma responder melhor ao objetivo, com menos mudanças no sistema operacional.

O próximo passo é ler o repositório oficial, separar uma máquina de testes e validar primeiro os pré-requisitos. Se o ambiente não atender Apple Silicon, macOS 15 ou superior, Xcode e SDK do iOS, pare nessa etapa e escolha uma alternativa adequada.