Impreza Host

O conector oficial da Impreza Host para gerenciamento de servidores offshore

Documentação

impreza-mcp

Servidor Model Context Protocol para Impreza Host. Permite que ferramentas de codificação com IA (Claude Code, Cursor, Codex CLI, Continue, Zed, ...) implantem aplicativos criados por clientes em VPSes Impreza gerenciados sem sair do chat.

Quando você diz "implante isso para mim" ao Claude com este servidor MCP carregado, o Claude chama impreza_deploy_custom diretamente — empacota seu projeto, envia-o, compila e executa no seu VPS Impreza, e reporta de volta a URL.

Vincule a CLI local

Gere um código de uso único no clientarea em Impreza API → Conecte um assistente de IA, escolhendo as permissões que o assistente precisa. Execute npx -y impreza-mcp login --code <code-from-clientarea> na máquina que executa o servidor MCP local. Os códigos expiram após 10 minutos e podem ser usados uma única vez.

A CLI troca o código em POST /v1/mcp/pair sem enviar nenhuma credencial de API existente. Ela salva a chave retornada, o segredo, os escopos e a expiração em ~/.impreza/credentials.json; o código e o segredo nunca são impressos. O diretório usa o modo 0700 e o arquivo 0600 em POSIX. O Windows usa uma ACL protegida concedendo acesso apenas à sua conta. O servidor lê este arquivo automaticamente quando nenhuma das variáveis de ambiente de credencial está definida. IMPREZA_API_KEY e IMPREZA_API_SECRET explícitos têm precedência juntos; credenciais de ambiente parciais nunca usam uma contraparte salva.

Defina IMPREZA_BASE_URL antes de vincular para um endpoint de API diferente. HTTPS é obrigatório; um endpoint onion v3 requer IMPREZA_PROXY com um proxy SOCKS5 explícito e nunca recorre a uma conexão direta. O endpoint e o proxy são salvos com a credencial. Uma URL de API diferente recusa a credencial salva. A vinculação nunca segue redirecionamentos nem tenta novamente um código automaticamente.

Um arquivo de credencial existente nunca é sobrescrito. Revogue uma chave antiga vinculada no clientarea antes de remover seu arquivo e vincular novamente. Se uma troca ou gravação em disco falhar, o código pode já ter sido consumido: verifique e revogue a nova chave no clientarea antes de gerar outro código. Reinicie o cliente de IA após a vinculação.

Acesso de entrada para portas não-HTTP (0.52.0)

impreza_get_ingress lê quais faixas de endereço podem alcançar cada porta não-HTTP que um aplicativo publica (bancos de dados, servidores de jogos, RustDesk...). Cada implantação começa aberta. A resposta traz a revisão, o status (open, pending, enforced, not_enforced com um motivo, ou agent_update_required com a versão mínima do agente) e, por porta, aberta ou restrita com suas origens. Requer escopo de leitura.
impreza_set_ingress substitui a lista de permissões pelo estado desejado completo: rules lista apenas as portas restritas, cada uma com suas origens CIDR IPv4 ou IPv6, e rules=[] abre todas as portas novamente. Restringir pode bloquear seu próprio acesso, então requer confirm: true; abrir não requer. Passe o base_revision que você leu; um desatualizado é recusado com REVISION_CONFLICT. O agente aplica dentro de cerca de um minuto. Se uma restrição não puder ser aplicada, as portas permanecem abertas, o status diz not_enforced com o motivo, e um alerta é disparado no aplicativo. Requer escopo de gerenciamento.
HTTP e HTTPS não são cobertos: eles passam pelo proxy e pelo Shield. A aplicação exige agente 0.6.26 ou posterior.

Valores exatos de recarga e IDs verificados em caminhos de API (0.51.0)

Valores exatos de recarga. impreza_topup aceita o valor como uma string decimal exata (por exemplo "25.50") e o envia à API inalterado, sem convertê-lo em um número de ponto flutuante binário. Um número JSON ainda é aceito. Strings com expoente, sinal, espaços ou mais de duas casas decimais são recusadas.
Cada ID colocado em um caminho de API é verificado. A proteção 0.50.0 para deployment_id agora cobre todo identificador que o pacote coloca em um caminho de URL de API: IDs de tarefa, backup, VPS, imagem, fatura, comando, leitura e execução, IDs de agente, nomes de clientes onion, o domínio em ferramentas que roteiam por domínio, e o IP dedicado para DNS reverso. Um valor que adicionaria ou alteraria segmentos de caminho (., .., /, \, %, espaços em branco ou caracteres de controle) é recusado antes que qualquer requisição saia do processo. IDs válidos são enviados exatamente como antes.

Proteja um aplicativo, IDs de implantação mais seguros e pedidos de VPS sem agente (0.50.0)

Proteja um aplicativo, como um prompt guiado. prompts/list adiciona impreza_protect_app. Começando de um dos seus aplicativos em execução, ele conduz o assistente por um standby frio em um servidor que você possui em outro país: escolha o alvo com o humano, crie o standby (impreza_deploy_catalog_app com standby: true), vincule-o e execute o primeiro exercício de restauração, cada etapa atrás de sua própria confirmação humana explícita. Após um exercício verificado, ele reporta a idade de cópia medida e a duração do exercício; estas são medições, não um RPO ou RTO garantido. Ele nunca compra um servidor, promove o standby, alterna tráfego ou altera DNS, e cobre os aplicativos de failover revisados (Memos 0.31.0 e Uptime Kuma 2.5.5). Como todo prompt, ele não concede autoridade.
Localizações de servidor: impreza_list_servers retorna o failover_location de cada servidor em sua saída estruturada: country_code, country_basis (verified, operator_verified ou declared; um país que você declarou para um servidor externo não é verificado pela Impreza) e country_notice.
IDs de implantação não podem adicionar segmentos de caminho. Um deployment_id que adicionaria ou alteraria segmentos de caminho em uma URL de API (., .., /, \, %, espaços em branco ou caracteres de controle) é recusado antes que qualquer requisição saia do processo. IDs válidos são enviados exatamente como antes.
Um VPS pedido pela API vem sem agente por padrão. impreza_order_vps e impreza_vps_offer agora descrevem o que a API faz: sem app, o VPS nasce com app: "none" (SO puro, sem agente). Passe app: "@agent" explicitamente quando o cliente quiser que ele seja implantável, ou ofereça impreza_install_agent depois com a confirmação do cliente. Após o pedido, consulte impreza_list_services; impreza_list_servers lista apenas servidores com agente instalado.
Dependências diretas exatas. O pacote fixa suas dependências diretas de runtime nas versões exatas com as quais foi testado (veja Versões de dependências).

Instale o agente, insira segredos fora do chat e proteja aplicativos personalizados (0.49.0)

impreza_install_agent oferece o agente Impreza em um VPS gerenciado que ainda não o possui, somente com o acordo explícito do cliente: a primeira chamada não instala nada e retorna um confirm_token de curta duração; a segunda chamada, com os mesmos argumentos mais esse token, inicia a instalação. impreza_get_agent_install informa se um VPS pode recebê-lo e acompanha a instalação até o agente ficar online.
Segredos nunca passam pelo chat. impreza_prepare_secret_entry retorna um link de portal de uso único com validade de dez minutos para uma variável secreta de um aplicativo existente ou grupo de variáveis; o proprietário da conta o abre, faz login e digita o valor lá. impreza_get_secret_entry reporta apenas pending, stored, expired ou cancelled — nunca o valor ou um hash dele. As ferramentas agora recusam valores secretos (senhas, tokens Git, chaves privadas onion, segredos de build) em seus argumentos e apontam para o portal; a API REST permanece inalterada.
Failover de jurisdição para projetos personalizados: impreza_deploy_custom aceita standby: true para criar um standby frio em outro servidor, a partir da mesma fonte fixada (digest de imagem, commit git exato ou o upload Compose congelado). O projeto deve declarar cada volume persistente, e um par personalizado faz a troca somente após um exercício verificado.

Progresso de implantação e reinicializações do agente

A revisão e implantação de Compose aceitam context_id para um upload retido contendo contextos de build locais e arquivos de runtime env_file, configs ou segredos. O mesmo contexto deve ser fornecido na revisão e na implantação. Arquivos de runtime exigem agente 0.6.11+ com compose-source-files-v1.

Implantações personalizadas de servidor Node/estático aceitam node_package_manager, como pnpm@10.26.1 ou yarn@4.9.2, correspondendo ao packageManager exato do projeto e ao lockfile commitado. Omita para npm. Versões suportadas são pnpm 10–12 autônomo e projetos Yarn 4, sem combinar este campo com npm_workspace. A inspeção infere a fixação e os planos salvos a retêm. Veja a documentação de implantação para entradas e limites suportados.

Leia last_operation.progress de impreza_list_deployments para a última etapa reportada e o timestamp. O agente 0.6.6+ salva os resultados finais antes de enviá-los; após reiniciar, ele reenvia o mesmo recibo sem repetir a implantação. O agente 0.6.7+ pode verificar um checkpoint de preparação concluído e restaurar a configuração anterior sem repetir a implantação (recovery=reconciling). Aguarde a falha terminal ou o cancelamento confirmado antes de tentar novamente. recovery=required significa que a reconciliação automática não pôde ser verificada; entre em contato com o suporte. Builds ocupados, checkpoints ausentes e incerteza de substituição permanecem bloqueados. Um build de longa duração pode continuar após o agente sair. O progresso não é uma porcentagem ao vivo nem prova de saúde atual do runtime. Agentes existentes atualizam explicitamente antes da próxima implantação. Veja progresso de implantação.

Cancele uma implantação

Use impreza_cancel_deployment com o ID da implantação e o last_operation.command_id exato. Requer permissão de gerenciamento. O cancelamento de fila é imediato; a preparação em execução exige agente 0.6.5+. O agente 0.6.12+ pode interromper um build próprio após o administrador do servidor habilitar builds controlados em hosts Ubuntu 24.04 amd64 suportados. Outra preparação aguarda sua etapa atual. A confirmação ainda exige limpeza verificada e configuração restaurada. requested não é cancelled. Substituição/recuperação não pode ser cancelada. Cancelar uma Task de rastreamento permanece separado. Leia o guia de cancelamento.

Saúde de runtime e operações de implantação

impreza_list_deployments retorna runtime e last_operation separadamente. Um build com falha pode deixar o aplicativo anterior saudável. Leia o estado de runtime, o tempo de observação e o motivo; leituras antigas ou ausentes permanecem desconhecidas. Executar sem um healthcheck confirmado não é saudável. Isso exige agente 0.6.4+ para observações e não verifica HTTP/DNS/TLS externo. Servidores existentes atualizam explicitamente. Veja saúde de runtime.

Planos de projeto salvos e novas tentativas seguras

impreza_plan_project também aceita git_url e um git_commit exato de 40 caracteres em vez de context_id. git_username e git_token opcionais são usados apenas para a busca. O servidor captura um arquivo retido imutável, contabiliza sua cota de upload e retorna source.origin junto com o SHA256 do arquivo. Revise esses valores antes de preparar/aplicar a configuração salva. Apenas HTTPS de rede pública na porta 443 é suportado; redirecionamentos e submódulos são recusados. O código do projeto não é executado pela inspeção. Essas opções exigem as capacidades correspondentes do plano de controle; atualize o pacote MCP local antes de usá-las.

Use impreza_plan_project com um context_id retido para inspecionar o inventário do arquivo e os arquivos de configuração selecionados. Escolha project_dir, dockerfile_path, um start_command Python ou php_document_root conforme necessário. Revise as descobertas e analysis.deployment_options.

Com MCP 0.32.0+, chame impreza_prepare_project_deployment com plan_id, option_index baseado em zero, nome do aplicativo, servidor e configurações de runtime. Ele valida e salva a configuração efetiva sem criar um aplicativo, job ou registro DNS. Revise a configuração retornada e então chame impreza_apply_project_deployment com apenas execution_id e configuration_digest. Alterações posteriores de formulário/requisição não podem sobrescrever esse registro. Uma repetição do mesmo deployment salvo retorna seu recibo de aceitação original, inclusive após expiração ou remoção do aplicativo. O recibo, o aplicativo e o job da fila são confirmados juntos. Após uma resposta incerta, repita o mesmo ID e digest em vez de preparar outro deployment. Aceitação significa enfileirado; inspecione o status do aplicativo, logs e saúde. Isso não reinicia um job com falha nem atualiza um aplicativo existente.

impreza_list_prepared_deployments lista as 20 configurações salvas mais recentes ou recupera uma execution_id. Os valores de ambiente são criptografados no registro preparado, omitidos das respostas de revisão e limpos desse registro na aceitação; o aplicativo então usa seu armazenamento de ambiente normal. As revisões mostram nomes de variáveis. Use no máximo 100 valores de string, sem substituições de variáveis de sistema/roteamento.

No máximo 20 registros pendentes por conta, válidos por não mais que o plano de origem e por no máximo 24 horas. Origem, regras, disponibilidade/IP de destino e configurações efetivas são reverificados antes da primeira aplicação. Não há reserva de domínio, porta ou capacidade, fixação de dependências ou garantia de build. O DNS é externo à transação do aplicativo e pode permanecer após uma tentativa interrompida. Registros pendentes expirados são removidos na próxima preparação da conta; recibos aceitos são retidos.

A inspeção de origem permanece disponível no MCP 0.31.0+. O mais antigo impreza_deploy_project_plan cria diretamente a partir de uma opção e não é idempotente. A criação de plano requer escopo de deploy; a listagem requer escopo de leitura; preparação/aplicação requerem escopo de deploy. Essas ferramentas de nível de conta exigem credenciais sem restrições de recursos. Nenhuma atualização de agente é necessária apenas para este fluxo; os requisitos de receita ainda se aplicam. Consulte o guia de plano e revisão.

Uploads de origem retidos

Use impreza_upload_context com dir e um label opcional para enviar uma versão de origem imutável sem fazer deploy. A resposta inclui seu context_id, SHA256, tamanho e expiração. Liste ou inspecione versões com impreza_list_contexts.

Crie um aplicativo com impreza_deploy_custom, mode: "dockerfile" e context_id (ou faça deploy de um dir local diretamente). Reconstrua-o com impreza_redeploy_deployment e opcionalmente outro context_id retido. A identidade do aplicativo, domínio, porta do host, volumes e receita de build permanecem fixos. A origem selecionada pode diferir da versão em execução após falha ou rollback; inspecione o histórico de deployments.

Origens em uso permanecem disponíveis. Versões não referenciadas expiram sete dias após o upload ou sua última solicitação de deployment, não sete dias após o desligamento. Cotas padrão são 10 arquivos não expirados/referenciados, 300 MiB por conta e 100 MiB por arquivo; origens referenciadas contam. Exclua uma versão não utilizada com impreza_delete_context, context_id e confirm: true após confirmação do cliente. Metadados exigem escopo de leitura, upload exige deploy e exclusão exige gerenciamento. Credenciais com restrição de recursos não podem gerenciar uploads de conta.

O empacotador exclui pastas comuns de dependências/VCS, .env e .env.* (exceto arquivos example/sample/template), .npmrc e .pypirc. Ele não verifica segredos arbitrários nem interpreta .gitignore/.dockerignore; revise o que você envia. Arquivos do portal são enviados inalterados. Uploads REST legados permanecem temporários, a menos que optem pelo retain=true. Aplicativos mais antigos com origem enviada podem migrar selecionando um contexto retido novo no redeploy. Essas ferramentas MCP exigem 0.22.0+; nenhuma atualização de agente é necessária apenas para retenção de origem. Consulte o guia de upload de origem.

Builds npm Node.js

Faça deploy de um aplicativo HTTP npm independente sem um Dockerfile de repositório usando impreza_deploy_custom com mode: "dockerfile", build_strategy: "node_npm", git_url (ou dir local) e target_port (geralmente 3000). A API gera uma receita Node 24: npm ci, script de build opcional, poda de produção e npm start como usuário não root. A pasta de projeto selecionada deve conter package.json, package-lock.json e um script de início de produção. Docker Compose 2.17+ e BuildKit devem estar disponíveis no servidor. Selecione workspaces npm explicitamente com npm_workspace. Use build_secrets para credenciais nomeadas e o segredo npmrc para instalação npm privada; agente 0.6.11+ é necessário. O aplicativo deve escutar em 0.0.0.0 e na porta configurada. Mantenha o PORT de runtime consistente com essa porta.

Redeploys e previews do Git reutilizam o snapshot da receita. Uploads de origem retidos suportam reutilização e seleção de versão de origem; uploads temporários mais antigos permanecem de uso único. A receita exclui .git, node_modules, .env, .env.* e .npmrc da cópia de origem; isso não verifica segredos arbitrários. Mantenha credenciais fora do código-fonte. A sonda de início HTTP aceita respostas abaixo de 500 em / e não é um teste funcional do aplicativo.

Variáveis de build públicas

Início saudável necessário: opte por require_healthy_start=true, um healthcheck_path explícito e build_strategy=node_npm. No portal, habilite Exigir início saudável. O agente 0.6.3 ou mais novo deve ser relatado em Servidores; atualize-o explicitamente e aguarde o próximo heartbeat. startup_timeout_seconds aceita um inteiro de 30 a 600, padrão 60. O orçamento começa após a criação dos contêineres e inclui a observação de saúde estável; fetch do Git, builds de dependências/imagens e recuperação têm limites de tempo separados. Cada serviço em execução deve relatar Docker saudável e pelo menos um contêiner de serviço deve existir. Redirecionamentos HTTP, erros de autenticação e timeouts não passam na sonda 2xx configurada. Quando a primeira instalação falha, seus contêineres são removidos e volumes persistentes são preservados; a falha inclui logs de diagnóstico. Uma substituição com falha recupera uma versão anterior verificada como saudável quando disponível. Recuperação e rollback manual usam a política de início da versão salva, então uma versão saudável lenta retém seu prazo original. A recuperação de falha não desfaz gravações de banco de dados ou dados mutáveis. O plano de controle recusa agentes incompatíveis na criação, nunca despacha a política sem suporte a startup-health-v1 na sondagem atual e aceita sucesso apenas com uma confirmação de saúde correspondente. Previews herdam a política; redeploy mantém o snapshot. Leituras de deployment expõem startup_health. Escolha um novo deployment para alterar a política salva. Omissão ou falso preserva o comportamento legado; um timeout de início requer a opção habilitada. A opção pública é para builds Node gerados. Isso não fornece troca sem downtime ou rollback automático contínuo após o início. Suporte a entrada MCP local requer 0.20.0+. Agentes existentes atualizam apenas quando o cliente executa o atualizador. Consulte https://docs.imprezahost.com/tutorials/agent-apps-panels.html#required-startup

Verificações de saúde do Node: com build_strategy=node_npm, defina opcionalmente healthcheck_path (por exemplo, /health ou /api/ready), ou preencha Caminho de verificação de saúde no portal. A verificação de saúde Docker gerada envia HTTP GET para 127.0.0.1 na target_port dentro do contêiner e exige status 200-299; ela não segue redirecionamentos nem envia credenciais. A rota deve funcionar sem login e deve relatar as dependências que seu aplicativo precisa para atender solicitações. Use / ou um caminho de no máximo 200 caracteres ASCII; segmentos começam com letra, dígito, sublinhado ou hífen e podem incluir pontos ou tils. Uma barra final é permitida. URLs, strings de consulta, fragmentos, escapes de porcentagem, espaços, segmentos pai e barras repetidas são recusados. Omita o campo (deixe em branco no portal) para manter a sonda / legada aceitando status abaixo de 500; definir explicitamente / exige 2xx. Snapshots de deployment existentes permanecem inalterados. O healthcheck_path salvo é retornado por leituras de deployment, herdado por novos previews e retido no redeploy; alterá-lo exige um novo deployment. Sites estáticos mantêm sua sonda index.html; Dockerfiles personalizados definem seu próprio HEALTHCHECK. A sonda é executada a cada 5 segundos com timeout de solicitação de 2 segundos. Com início saudável desabilitado, agentes 0.6.2 e posteriores observam o início por até 60 segundos: uma substituição com falha recupera uma versão anterior verificada como saudável quando uma existe. Sem esse alvo de recuperação, uma primeira instalação ainda pode concluir com um aviso de início, então inspecione saúde e logs antes de tratá-la como pronta. Essa política padrão não fornece rollback contínuo, roteamento sem downtime ou verificações de uptime externas. Para impor um prazo de início, habilite início saudável necessário com agente 0.6.3+. Entradas MCP locais exigem 0.19.0+; healthcheck_path sozinho não precisa de atualização de agente além de 0.6.2.

Configurações de build públicas: receitas geradas node_npm e node_npm_static aceitam public_build_vars, um objeto de valores de string disponíveis apenas para npm run build (incluindo seus scripts prebuild/postbuild). Por exemplo, {"VITE_API_URL":"https://api.example.com"} permite que o Vite compile uma URL de API pública no site. Nomes devem começar com VITE_, NEXT_PUBLIC_ ou PUBLIC_, conter apenas letras maiúsculas, dígitos e sublinhados, e ter no máximo 128 caracteres. Limites: 20 entradas, 4096 bytes UTF-8 por valor e 16384 bytes para nomes mais valores. Strings vazias são preservadas; NUL é recusado. Valores são dados literais, sem expansão de shell ou variável. O portal expõe Variáveis de build públicas como linhas KEY=value; não adicione aspas ao redor, que se tornariam parte do valor. Esses valores são públicos e podem aparecer em bundles, metadados de imagem e logs: nunca envie senhas, tokens ou segredos. Eles não são fornecidos ao npm ci nem adicionados automaticamente a variáveis de runtime. Variáveis de runtime ainda configuram o contêiner em execução e não reescrevem arquivos de navegador compilados. Configurações são salvas na criação, expostas em leituras de deployment, herdadas por novos previews e reutilizadas no redeploy. Herança/substituições de runtime de preview não alteram este snapshot de build; crie um deployment separado para diferentes valores de build públicos. Snapshots existentes não têm valores de build públicos por padrão. Use build_secrets para credenciais de build suportadas com agente 0.6.11+; configurações de build não suportadas exigem um Dockerfile personalizado. MCP local requer 0.18.0+; nenhuma atualização de agente é necessária além do executor de build existente.

Consulte o guia de configuração de build.

Aplicativos em subpastas de projeto

Faça deploy de um aplicativo npm independente de uma subpasta: defina project_dir (padrão .) com node_npm ou node_npm_static, ou escolha Pasta de projeto no portal. Por exemplo, apps/site deve conter seu próprio package.json e package-lock.json correspondente; static_output_dir é relativo a essa pasta. Apenas a pasta selecionada é copiada para /app para instalação npm e builds. O repositório/upload permanece o contexto de build Docker, então seu .dockerignore raiz ainda se aplica. Caminhos permitem até 120 caracteres e cinco segmentos não ocultos; componentes pai, node_modules e symlink são recusados. Pastas ausentes ou builds com falha retêm o runtime saudável anterior. O valor project_dir é retornado por leituras de deployment, salvo na criação e herdado por novos previews; redeploy reutiliza a receita salva. Snapshots existentes usam . por padrão; alterar a pasta exige um novo deployment. Isso suporta aplicativos independentes em um repositório, não workspaces compartilhados ou dependências fora da pasta; use um Dockerfile personalizado para esses casos. O analisador não descobre subpastas: forneça os metadados do aplicativo selecionado e revise a Pasta de projeto você mesmo. MCP local requer 0.17.0+; nenhuma atualização de agente é necessária além do executor de build existente.

Consulte o guia de pasta de projeto.

Importar uma pilha Compose

Use impreza_prepare_compose com compose_yaml, então selecione explicitamente web_service e o inteiro target_port. Revise serviços, volumes persistentes, variáveis necessárias, alterações e bloqueadores antes de fazer deploy com impreza_deploy_custom, mode: "compose", o mesmo YAML/serviço/porta e compose_review_id definido como o analysis_id retornado. Supports self-contained public-image stacks with up to 12 services, private bridge networks, local named volumes and service dependencies. Original host port bindings are removed; only the selected HTTP service joins the proxy and receives a managed loopback port. Container and volume names become specific to the deployment. Declare CPU/memory limits per service in YAML.

The review does not fetch images, execute code or reserve resources. Local build contexts and auxiliary files require the same retained context_id at review and deploy. Runtime env_file accepts literal assignments only, without interpolation or inherited bare keys. Aliases, profiles, host privileges and external resources are outside this import subset. Reference uppercase variables instead of embedding secrets. Runtime values must be single-line strings up to 4 KiB, without surrounding whitespace, quotes, backslashes, dollar signs or space followed by #. Variables supply explicit references, not every service's environment. Required values are checked at creation, editing and redeploy.

The imported source is saved as a manifest. Redeploy reuses it and the named data; changing the source/topology requires a new deployment. Failure recovery uses the existing agent policy and does not undo database writes. Local MCP support for public-image stacks requires 0.21.0+. Retained build/runtime sources require MCP 0.34.0+ and agent 0.6.11+. See the Compose import guide.

Prepare project configuration

Use impreza_prepare_project with package_json, dockerfile, and optional dockerfile_path before deploying. It returns framework hints, available build and start commands, explicit ports from the final Dockerfile stage, and findings to review. Each file is limited to 32 KiB. Review files for credentials before sending; never submit .env files or secrets.

This is advisory analysis of supplied text. It does not fetch a repository, execute code, generate a Dockerfile or deploy resources. Git deploys use a Dockerfile by default; supported npm projects can opt into the Node recipe. The analysis ID identifies metadata, not an executable plan. Requires an API exposing /v1/platform/deployments/custom/prepare.

Why this host and not a mainstream one

Any provider can run your app. This one is built so an agent can obtain and operate infrastructure that is not tied to your identity, end to end, without you opening a browser:

No KYC, and no email address, to open an account. An account is a generated client ID plus a recovery token. No documents, no selfie, no phone number.
Funded in cryptocurrency. impreza_topup accepts BTC, XMR, USDT and TRX, and impreza_order_vps buys the server from that balance. The agent can go from "I need a server" to a running deployment without a card.
Offshore and onshore jurisdictions side by side, chosen per project rather than per account.
Tor is a deployment target, not an add-on. impreza_add_onion gives a deployment a .onion address in one call, so an agent can publish a hidden service the same way it publishes a normal site. impreza_onion_auth_* manage Tor v3 restricted discovery (client authorization): private keys never leave the customer's Tor client unless they ask the server to generate a keypair — and then the private key is shown once, never stored.
No API key in your config. The hosted connector authenticates over OAuth.

If none of that matters for your project, a mainstream provider is a perfectly good choice and usually cheaper to start with. This exists for the projects where it does matter: research and journalism under pressure, censorship circumvention, security work, and anything that should not be one support ticket away from being linked to a legal name.

Retained-release rollback

The source tree adds impreza_rollback_deployment. Read a deployment's release_history through impreza_api_call at /platform/deployments/{id}, then choose a rel_... entry with rollback_supported: true.

Explain the selected release and possible interruption to the customer before calling the tool with deployment_id, target_version and confirm: true. The hosted connector uses its two-call confirm_token flow instead. The operation requires manage scope and a compatible API and agent.

A historical release may no longer be retained. The agent checks local images and unchanged ports, storage and routing before replacing containers. It saves the current healthy runtime and attempts recovery if the selected release fails startup. Database contents and mutable data are not reverted. A queued response does not confirm restoration; check deployment history for the result.

Available in impreza-mcp 0.12.0. Requires a compatible API and agent.

Static npm sites

Static npm sites: choose build_strategy=node_npm_static with a Git/context source (mode=dockerfile), or Static site + npm in the portal. Requires an independent npm package in the selected project folder, matching package-lock.json and a build script producing index.html in the selected output folder. Node 24 installs dependencies and runs the build; unprivileged Nginx serves only the selected output folder with configurable SPA fallback. No start script is required. Default target_port is 8080. Compose 2.17+ and BuildKit required. No SSR or server functions. Explicit npm_workspace and build_secrets are supported with their documented source and agent requirements. Runtime variables (including VITE_* and PORT) do not rewrite static bundles or change the configured Nginx port. Use static_output_dir (default dist) to choose a relative output folder containing index.html, and static_spa (boolean, default true) to choose SPA fallback or 404 for unknown routes. The portal exposes both fields. Paths are limited to 120 characters and five segments, without hidden, parent or node_modules segments; symlinks in the output or its parent path are refused. These settings are chosen at creation, stored in the recipe snapshot, exposed as static_options and carried to new previews. Redeploy reuses the saved recipe; changing these settings on existing deployments requires creating a new deployment. Existing snapshots keep their original recipe. Local MCP option inputs require 0.16.0+. Use public_build_vars for supported public settings; other build-time configuration requires a custom Dockerfile. Source .env/.env.*/.npmrc/.git/node_modules are excluded; review all generated files because the output folder is public. Missing index.html and symlink output fail the build. Existing preview/redeploy snapshots preserve the strategy. Local MCP requires 0.15.0+; no agent upgrade is needed beyond the existing build executor. The analyzer returns static_npm_recipe and conditional deployment_options; metadata is not proof of a static, working build.

Status

Package version: 0.52.0. The tool catalog covers app deployment plus account + crypto balance, catalog + ordering, domains/DNS + registration, invoices, VPS lifecycle with snapshots and backups, dedicated / bare-metal servers, plan upgrades, and Titan / Google Workspace mailboxes — with a setup wizard that generates ready-to-paste config snippets for 5 AI tools.

On top of that, everything an app needs after it is running: backup and restore into the customer's own S3 bucket, a timer on an app with its output kept, outbound webhooks so you stop polling, reading the app's own files, and running the app's own command line.

The local (npx) server and the hosted OAuth connector expose the same tool catalog — 218 tools in the local package. Declared, one-direction gaps remain: impreza_get_log_request stays hosted-only (only the control plane resolves a bare request_id; locally, call impreza_tail_logs again on the application — requests dedupe); impreza_list_approvals, impreza_get_approval and impreza_get_credential_policy are hosted-first (locally, the same reads are REST calls through impreza_api_call); and impreza_upload_context stays local-only (binary tarball streaming does not fit the hosted transport).

New in 0.11.0

Run the app's own command line. WP-CLI for WordPress, occ for Nextcloud, gitea admin for Gitea, and the database client for a dump — impreza_app_cli to run, impreza_get_cli_run to collect the output. Call impreza_get_cli_run with no run_id first: it names the command lines the app has, says what each is for, and gives one example that works.

No docker socket, and that is measured rather than claimed. The command runs in a separate container built from the app's own image, joined to the app's own network, with its data mounted — the shape the official CLI images are designed for. cap_drop: ALL, and no new privilege on the machine.
Arguments are a list, never a string. Each element becomes one argv entry through execve, so nothing is split, globbed or substituted: quoting is not your problem, and a $ or a ; inside a value is just that. Verified against a live site — option update blogname 'dollars $HOME and a ; semicolon' reads back exactly as sent.
Destructive, and treated as such. A command line can do anything the app itself can, so it needs the manage scope and is confirmation-gated. Arguments are free rather than allowlisted: that is the same ceiling uninstall with purge_data already sits at, and a list of wp subcommands would age badly while protecting nothing the confirmation gate does not.
The CLI version follows the app. Where the command line is the app's own image it is taken from that deployment, so a catalog bump carries it — running occ from an older Nextcloud against a newer database is how a maintenance command corrupts an install.

Custom deployments have no command line here: it is your own image and the platform cannot know what it ships. Use a scheduled task of kind command for those.

New in 0.10.0

Look inside the app's own files. impreza_get_logs reads stdout, which cannot answer the question a deploy that came up wrong actually raises: did that variable reach the config file? Two tools now do — impreza_inspect_app to ask and impreza_get_app_read to collect the answer.

Four actions, and no fifth: list a directory, read a file (capped at 256 KB), tail its last lines, grep under a path with an extended regular expression. There is no command string in the interface, and therefore no shell.
Read-only by construction. A one-shot container mounts the app's storage read-only — the same mechanism the backup already uses — with no docker socket and no write capability. So it also works on an app that is failed and will not start, which is when it is wanted most.
Only the app's own storage: data, or one of the named volumes the app's manifest declares (a WordPress exposes data and wp_db, so its database files are readable too). Call impreza_get_app_read with no read_id to see the list for a given app.
What comes back is untrusted and often secret — an app's config file is where its database password lives. It reaches you and nothing else: the field is on our request log's deny list, and the record is deleted within a day.

Since 0.6.1

Three releases the npm page never described, each one a whole capability:

0.7.0 — backup e restauração dos dados de uma implantação no bucket Impreza S3 da própria conta, com um manifesto SHA-256 por bloco que fica ao lado dos dados para que a cópia permaneça verificável com as próprias credenciais do cliente e sem precisar nos contatar. Além disso, um agendamento (diário por padrão, mantendo 3), e uma restauração que pode parar em um aplicativo diferente, que é como um aplicativo se move entre servidores.
0.8.0 — tarefas agendadas: um temporizador em um aplicativo com a saída mantida, para os aplicativos que precisam de um para se comportar corretamente (cron do Nextcloud, wp-cron do WordPress em um site sem visitantes).
0.9.0 — webhooks de saída: assine eventos de implantação, backup e VPS e pare de fazer polling, com entrega assinada por HMAC e um registro de entrega.

Novo na 0.6.1

tools/list agora reflete o que sua conta realmente possui. Cerca de um terço das ferramentas só fazem sentido se você tiver a máquina por trás delas — controles de energia de VPS sem VPS só podem responder "não encontrado" — então essas são omitidas da listagem até que você possua uma. Contas típicas veem cerca de 70 ferramentas em vez de 97, o que representa aproximadamente seis mil tokens a menos de contexto gastos antes de você perguntar qualquer coisa.

Três coisas que vale a pena saber sobre como isso se comporta:

O caminho de compra nunca é filtrado. Uma conta que não possui nada é a que precisa comprar algo, então pedidos, recargas, faturas e o catálogo estão sempre listados.
Comprar algo aumenta a lista no meio da sessão. O servidor envia notifications/tools/list_changed na mesma resposta do pedido, então um cliente que o respeita adota as novas ferramentas sem reconectar.
Falha aberta. Se este servidor não conseguir alcançar a API para perguntar, ele lista tudo em vez de adivinhar.

Ocultar uma ferramenta não é um limite de autorização — a API ainda recusa qualquer coisa que sua conta não possua. Isso apenas impede que a listagem carregue ferramentas que nunca poderiam funcionar para você.

Novo na 0.6.0

Quatro coisas que só fazem sentido em um host construído para anonimato:

Pré-visualizações escuras — envie uma branch, obtenha uma pré-visualização em seu próprio .onion Tor efêmero. A URL de pré-visualização de todas as outras plataformas coloca o nome da sua branch no DNS público e em um registro permanente de Transparência de Certificados; nomes de branch carregam IDs de tickets, nomes de clientes e recursos não lançados. Este não cria nenhum dos dois registros e destrói suas chaves quando a branch é excluída ou o TTL expira. impreza_configure_previews, impreza_list_previews, impreza_retire_preview.
Sub-credenciais de agente — cunhe uma credencial mais restrita a partir da que você possui e entregue-a a uma subtarefa: uma implantação, uma hora, sem gastos. Um filho nunca pode exceder seu pai em nenhum eixo, e revogar uma credencial revoga tudo o que ela cunhou, por mais profundo que seja. impreza_mint_subcredential, impreza_list_credentials, impreza_revoke_credential, impreza_agent_activity.
Um relatório de privacidade que você pode verificar — impreza_privacy_report retorna todos os campos que armazenamos sobre sua conta, para que servem, por quanto tempo sobrevivem e quem mais os vê, e então mede nossa própria retenção contra o registro mais antigo que realmente sobreviveu. Contagens e intervalos de datas, nunca conteúdos.
Pergunte antes de adivinhar — pesquise em nossos documentos, valide um manifesto de implantação antes de implantá-lo (incluindo uma verificação de privacidade para CDNs de terceiros, resolvedores DNS públicos e segredos vazados), ou execute um diagnóstico quando algo estiver errado. impreza_search_docs, impreza_validate_manifest, impreza_doctor.

Além da extensão Tasks, para que operações longas relatem conclusão em vez de deixar você fazendo polling, e três painéis de MCP Apps — um cartão de pagamento, um cartão de servidor e um assistente de implantação — que são renderizados em clientes que os suportam.

A tabela abaixo é uma seleção, não a lista completa — ela cobre as ferramentas que a maioria das pessoas procura primeiro. A listagem de ferramentas do seu próprio cliente é a autoritativa, e impreza_api_search encontra qualquer coisa não nomeada aqui.

Ferramenta	Encapsula
Apps e implantações
`impreza_list_servers`	`GET /v1/platform/servers`
`impreza_list_apps`	`GET /v1/platform/apps`
`impreza_list_deployments`	`GET /v1/platform/deployments` + `/custom` (mesclado)
`impreza_upload_context`	`POST /v1/platform/deployments/custom/contexts?retain=true`
`impreza_list_contexts`	`GET /v1/platform/deployments/custom/contexts[/{context_id}]`
`impreza_delete_context`	`DELETE /v1/platform/deployments/custom/contexts/{context_id}`
`impreza_deploy_custom`	`POST /v1/platform/deployments/custom` (3 modos)
`impreza_deploy_catalog_app`	`POST /v1/platform/deployments`
`impreza_uninstall_deployment`	`POST .../uninstall`
`impreza_get_logs`	`POST .../logs` (cauda síncrona, últimas N linhas)
`impreza_restart_deployment`	`POST .../restart`
`impreza_redeploy_deployment`	`POST .../custom/{id}/redeploy` (reconstrução no local, mesmo domínio)
`impreza_add_onion`	`POST .../onion/add`
`impreza_set_onion_profile`	`POST .../onion/profile` (níveis de endurecimento `standard` / `hardened` / `max`)
`impreza_export_onion_key`	`POST .../onion/export` (selado com sua chave X25519; texto simples nunca transita)
`impreza_fetch_onion_key_export`	`GET .../onion/export/{command_id}` (leitura única — o blob é queimado)
`impreza_rotate_onion_key`	`POST .../onion/rotate` (novo .onion; o endereço antigo morre)
`impreza_onion_auth_list`	`GET .../onion/clients`
`impreza_onion_auth_add`	`POST .../onion/clients` (`pubkey`, ou `generate:true` → `private_key` mostrado uma vez)
`impreza_onion_auth_revoke`	`DELETE .../onion/clients/{name}`
`impreza_change_domain`	`POST .../domain`
`impreza_git_webhook_status`	`GET .../custom/{id}/git-webhook`
`impreza_git_webhook_connect`	`POST .../custom/{id}/git-webhook/connect`
`impreza_git_webhook_disconnect`	`POST .../custom/{id}/git-webhook/disconnect`
Conta e saldo
`impreza_account_info`	`GET /v1/account`
`impreza_list_services`	`GET /v1/account/services`
`impreza_topup`	`POST /v1/account/topup` — recarregue em BTC / XMR / USDT / TRX
`impreza_topup_status`	`GET /v1/account/topup/{invoice_id}`
`impreza_topup_payment`	`GET /v1/account/topup/{invoice_id}/payment` — endereço de criptomoeda + valor a pagar
Catálogo e pedidos
`impreza_list_products`	`GET /v1/products` — produtos + preços; o VPS é listado em seu menor tamanho (`configurable: true`)
`impreza_vps_offer`	`GET /v1/products/vps` — locais de VPS, sistemas operacionais, faixas de CPU / memória / disco e preços; com uma configuração completa, `GET /v1/products/vps/quote` — seu preço exato
`impreza_order_vps`	`POST /v1/orders` — um VPS por local, SO e tamanho (ou um plano fixo por `product_id`); pago do saldo; SO puro por padrão (`app: "none"`); solicite explicitamente `app: "@agent"` para implantação, ou use `impreza_install_agent` depois com confirmação do cliente; 202 + polling `impreza_list_services`
Domínios e DNS
`impreza_domain_check`	`GET /v1/domains/check`
`impreza_domain_details`	`GET /v1/domains/{domain}`
`impreza_list_dns`	`GET /v1/domains/{domain}/dns`
`impreza_add_dns_record`	`POST /v1/domains/{domain}/dns`
`impreza_update_dns_record`	`PUT /v1/domains/{domain}/dns`
`impreza_delete_dns_record`	`DELETE /v1/domains/{domain}/dns`
`impreza_set_nameservers`	`PUT /v1/domains/{domain}/nameservers`
Ciclo de vida do VPS (Proxmox)
`impreza_vps_status`	`GET /v1/vps/proxmox/{id}/status`
`impreza_vps_power`	`POST /v1/vps/proxmox/{id}/{start\|shutdown\|reboot\|stop}`
`impreza_vps_list_backups`	`GET /v1/vps/proxmox/{id}/backups`
`impreza_vps_create_backup`	`POST /v1/vps/proxmox/{id}/backups`
`impreza_vps_list_templates`	`GET /v1/vps/proxmox/{id}/templates`
`impreza_vps_reinstall`	`POST /v1/vps/proxmox/{id}/reinstall` — destrutivo (apaga)
`impreza_vps_resize`	`POST /v1/services/{id}/resize` — mais vCPU, memória ou disco pelo preço proporcional (cotação primeiro com `GET /v1/services/{id}/resize/quote`); `max_amount` fixa

Instalação + configuração

Pré-requisitos

Node ≥ 20
Uma conta Impreza Host com chave de API + segredo (área do cliente → Chaves de API; o IP da máquina que executa este servidor MCP deve estar na lista de permissões da chave)

Uso único via `npx`

Nenhuma instalação global necessária — npx impreza-mcp funciona.

Ou instale globalmente

npm install -g impreza-mcp

Obtenha um trecho de configuração pronto para colar

O caminho mais rápido: pergunte ao próprio binário.

npx impreza-mcp setup --tool claude-code
# also: cursor | continue | zed | codex-cli

O assistente imprime o bloco JSON para colocar na configuração MCP da sua ferramenta de IA + o caminho exato do arquivo + o passo pós-configuração (geralmente "saia completamente + reabra a ferramenta de IA"). Ele NÃO grava em disco — cole você mesmo para não sobrescrever acidentalmente uma configuração existente com outros servidores MCP.

Ou configure manualmente

Claude Code — adicione a ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) ou %APPDATA%/Claude/claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "impreza": {
      "command": "npx",
      "args": ["-y", "impreza-mcp"],
      "env": {
        "IMPREZA_API_KEY": "imp_...",
        "IMPREZA_API_SECRET": "..."
      }
    }
  }
}

Reinicie o Claude Code. As ferramentas aparecem sob o ícone MCP.

Cursor — adicione a ~/.cursor/mcp.json (mesma forma que acima).

Continue — adicione a ~/.continue/config.json:

{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "transport": {
          "type": "stdio",
          "command": "npx",
          "args": ["-y", "impreza-mcp"],
          "env": {
            "IMPREZA_API_KEY": "imp_...",
            "IMPREZA_API_SECRET": "..."
          }
        }
      }
    ]
  }
}

Zed — adicione às suas configurações:

{
  "context_servers": {
    "impreza": {
      "command": {
        "path": "npx",
        "args": ["-y", "impreza-mcp"],
        "env": {
          "IMPREZA_API_KEY": "imp_...",
          "IMPREZA_API_SECRET": "..."
        }
      }
    }
  }
}

Uso no chat

Após a configuração, fale com sua IA naturalmente:

"Liste meus servidores Impreza." → chama impreza_list_servers

"Implante este diretório no meu VPS Impreza, exponha via .onion." → empacota o diretório atual como uma implantação personalizada em modo Dockerfile, envia, implanta com onion=true, relata o endereço .onion.

"Quais aplicativos estão rodando no meu agente?" → chama impreza_list_deployments filtrado para o servidor correto.

Autenticação + segurança

IMPREZA_API_KEY + IMPREZA_API_SECRET vivem no env da configuração MCP da ferramenta de IA — não em nenhum arquivo em disco pertencente ao próprio impreza-mcp. O servidor MCP mantém o segredo apenas em memória e o anexa somente como cabeçalhos de solicitação HTTP.

O IP da máquina que executa este servidor MCP (quase sempre seu laptop) deve estar na lista de permissões da chave de API. Gerencie a lista de permissões na sua área do cliente Impreza.

Usando via Tor

O servidor MCP pode rotear cada chamada de API através de um daemon Tor local, para que as solicitações de API usem o proxy configurado. Seu provedor de rede ainda pode observar sua conexão com o Tor; esta opção não esconde que você está usando Tor.

Instale e inicie o Tor (o daemon tor, ou o Tor Browser — ambos comumente expõem um listener SOCKS5 em 127.0.0.1:9050 para o daemon ou 127.0.0.1:9150 para o Tor Browser; verifique sua configuração local).

Adicione IMPREZA_PROXY ao env da configuração MCP:

"env": {
  "IMPREZA_API_KEY": "imp_...",
  "IMPREZA_API_SECRET": "...",
  "IMPREZA_PROXY": "socks5://127.0.0.1:9050"
}

Cada solicitação de API então sai através do Tor, e o hostname da API é resolvido pelo próprio Tor (DNS remoto) — nada é resolvido localmente, então não há vazamento de DNS. O transporte falha fechado: se o proxy estiver inalcançável ou recusar a conexão, a solicitação falha — nunca cai silenciosamente em uma conexão clearnet direta.

Opcionalmente, aponte IMPREZA_BASE_URL para o espelho .onion da API — http:// é aceito apenas para hosts .onion v3, pois o Tor autentica e criptografa conexões onion. Hosts clearnet exigem https://. Uma URL onion também exige um IMPREZA_PROXY explícito; o cliente recusa DNS direto e conexões mesmo quando a URL onion usa HTTPS. Solicitações de proxy recusam redirecionamentos, usam um prazo de solicitação limitado e aceitam corpos de resposta de até 16 MiB.

Um ajuste do lado da conta: os IPs de saída do Tor giram constantemente, então uma lista de permissões de IP fixo na chave de API não pode funcionar. Defina o fator de IP da chave para tofu ou keyonly na área do cliente.

Implantações PHP

Use impreza_prepare_project com composer_json e opcionalmente php_document_root para revisar um aplicativo PHP. Implante com impreza_deploy_custom, mode: "dockerfile" e build_strategy: "php_composer", usando Git, um diretório local ou um upload retido. A receita PHP 8.4/Apache instala dependências de produção de composer.json e um composer.lock correspondente, sem scripts ou plugins do Composer, e verifica os requisitos reais da plataforma. Escolha project_dir para o aplicativo e php_document_root para sua subpasta pública contendo index.php (padrão public). O Apache roda como um usuário não-root em target_port (padrão 8080, mínimo 1024); ele serve arquivos públicos e envia caminhos ausentes para index.php.

Verificações de saúde exigem HTTP 2xx sem redirecionamentos, em / ou seu healthcheck_path. require_healthy_start opcional precisa de um caminho explícito e agente 0.6.3+, com um orçamento de inicialização de 30–600 segundos. Pré-visualizações e reimplantações mantêm a receita salva. Repositórios personalizados, credenciais privadas de dependências, plugins de instalação, extensões extras, regras .htaccess, builds de frontend e configuração/ migrações de aplicativo exigem um Dockerfile personalizado. start_command e variáveis de build públicas não são opções PHP. A análise é consultiva e não inspeciona o lockfile ou o repositório. Veja o guia de implantação PHP.

Implantações Python

Use impreza_prepare_project com requirements_txt e um start_command explícito para revisar um aplicativo Python. Faça o deploy com impreza_deploy_custom, mode: "dockerfile" e build_strategy: "python_pip", usando Git, um diretório local ou um contexto enviado. A receita Python 3.13 instala um requirements.txt simples do PyPI e executa como um usuário não root; escolha project_dir para uma pasta de aplicativo independente. Inicie um servidor de produção em 0.0.0.0 em target_port (padrão 8000), por exemplo exec gunicorn --bind 0.0.0.0:$PORT app:app, com Flask e gunicorn declarados em requirements. PORT e HOST são variáveis de tempo de execução. Mantenha as credenciais fora do comando salvo.

A sonda de saúde Python padrão exige HTTP 2xx em /; escolha healthcheck_path para outra rota. O require_healthy_start opcional exige um caminho explícito e agente 0.6.3+, com um orçamento de inicialização de 30 a 600 segundos. Pré-visualizações e reimplantações mantêm a receita salva. Opções de dependência, includes, URLs, projetos locais, credenciais privadas de build, pacotes de sistema e outros gerenciadores de pacotes exigem um Dockerfile personalizado. Variáveis de build públicas permanecem apenas para npm. A análise é consultiva; os builds resolvem dependências reais no servidor. Consulte o guia de deploy Python.

Build

npm install
npm run build
# dist/server.js is the entry point

Preparação supervisionada

Estas regras legadas de worker permanecem em vigor, a menos que o administrador habilite o agente 0.6.12+ builds controlados, que adicionam parada e recuperação verificadas do executor para novos builds.

Agente 0.6.8+: deploys suportados em Linux/systemd executam pull de imagem e build em um processo supervisionado separado. Se o agente reiniciar, ele aguarda o recibo exato do worker sem repetir esse trabalho. Apenas um recibo durável e bem-sucedido permite a reconciliação de preparação existente: revalidar operação/fase e contêineres inalterados, restaurar a configuração anterior e fechar como falha ou confirmar um cancelamento solicitado anteriormente. recovery=reconciling pode incluir aguardar o worker original. Recibos ausentes/inválidos, falha ou timeout do worker, reinicialização do host antes de um recibo, trabalho legado não supervisionado, incerteza de substituição, propriedade de dados e preparação de onion ainda exigem revisão. Um processo ou serviço que desaparece nunca é prova de conclusão. O cliente deve aguardar o resultado final antes de tentar novamente; nenhuma nova tentativa automática de deploy, término imediato do build, rollback de dados ou garantia de saúde em tempo de execução é adicionada.

Licença

MIT — consulte LICENSE.

Substituição supervisionada

Agente 0.6.9+: novos deploys suportados em Linux/systemd mantêm a substituição autorizada de contêineres, verificações de inicialização, hooks de ciclo de vida, rotas e recuperação normal de inicialização em um único worker supervisionado. Se o agente reiniciar, recovery=reconciling com step=reconciling_replacement aguarda esse worker original. Seu recibo final durável e verificado é entregue sem repetir contêineres ou hooks, incluindo um deploy com falha cuja versão anterior foi restaurada. Recibos ausentes ou inválidos, perda ou timeout do worker, reinicialização do host antes da conclusão, operações legadas não supervisionadas, mudanças de propriedade de dados e provisionamento de onion ainda exigem suporte; mantenha o diário privado e não tente novamente para desbloquear a fila. Isso não adiciona novas tentativas automáticas de deploy, rollback de banco de dados ou troca de tráfego sem tempo de inatividade. Atualize o agente explicitamente antes do próximo deploy.

Deploys Python podem selecionar python_package_manager=uv@0.12.15 com python_pip, pyproject.toml e uv.lock. A instalação é bloqueada, apenas para produção e não editável no Python 3.13; apenas fontes públicas do PyPI. Workspaces/índices uv personalizados exigem um Dockerfile. Use MCP 0.34.0+ e um plano de controle que suporte esta receita.

Conexões de aplicativos PostgreSQL

impreza_prepare_service_binding revisa uma conexão PostgreSQL dedicada para um aplicativo de imagem no mesmo ambiente de projeto e servidor. impreza_prepare_service_binding_removal revisa a remoção ou uma nova tentativa de limpeza pendente com o deployment_id e binding_id exatos. Leia o plano salvo com impreza_get_service_binding_plan; aplique somente após confirmação explícita usando impreza_apply_service_binding_plan, o digest exato e confirm: true. A remoção retém os dados do banco e desabilita o login dedicado somente após uma substituição saudável sem a conexão. Aceitação significa enfileirado, não conclusão verificada. Requer agente 0.6.13+ e um plano de controle compatível.

impreza_prepare_service_binding_rotation revisa uma rotação de credenciais para uma conexão existente com deployment_id, binding_id e mode (rotate ou abandon). A rotação substitui o login dedicado por um novo distinto e desabilita o login anterior somente após uma substituição saudável com o DATABASE_URL rotacionado; o banco de dados e seus dados são sempre retidos. Uma falha na inicialização mantém o aplicativo anterior em serviço com a credencial atual e exige uma nova tentativa revisada; se o login anterior não pôde ser confirmado como desabilitado, a rotação permanece em limpeza pendente e uma nova revisão de rotate tenta novamente. abandon descarta a credencial candidata não utilizada e mantém a atual; é recusado quando apenas a limpeza permanece. Aplique a revisão retornada com impreza_apply_service_binding_plan como acima; a preparação não enfileira nada e não retorna credencial. A rotação exige um agente anunciando postgres-service-binding-rotation-v1: agentes mais antigos recusam o despacho e o trabalho com falha direciona o cliente a atualizar o agente explicitamente, preservando sua identidade, configuração e aplicativos. A rotação exige uma conexão de protocolo v2; conexões legadas de primeiro protocolo não são adotadas.

Diagnósticos HTTPS públicos

impreza_probe_deployment recebe deployment_id e verifica o hostname público salvo através do plano de controle. Ele relata resolução DNS pública, verificação TLS e o status HEAD HTTPS, sem seguir redirecionamentos ou enviar credenciais de aplicativo. Não lê corpos de resposta nem verifica dependências. Uma tentativa por conta a cada 30 segundos; nenhuma atualização de agente é necessária.

Promoção de imagens e ambientes

impreza_prepare_image_promotion, impreza_get_image_promotion e impreza_apply_image_promotion revisam um digest exato de registro para uma configuração de destino existente. Aplicar exige o digest de revisão retornado e confirmação explícita. Variáveis e dados de destino permanecem locais para esse aplicativo.

As ferramentas de projeto/ambiente organizam aplicativos existentes com associações explícitas de componentes. Elas não copiam variáveis, criam conexões de rede ou implantam workloads. Consulte o guia de ambientes de projeto.

Fluxos de trabalho de deploy revisados

A versão 0.38.0 adiciona comparação de configuração de ambiente, trocas de tráfego prepare/read/apply e pré-visualizações de branch explícitas com proteção opcional por senha. A comparação retorna nomes de variáveis, nunca valores. As trocas de tráfego exigem um digest revisado e confirmação, mantêm a fonte em execução e exigem reconciliação do operador se a recuperação não puder ser verificada. As credenciais de pré-visualização protegidas são mostradas uma vez. As trocas de tráfego e pré-visualizações protegidas exigem agente 0.6.16 ou mais recente. Servidores existentes atualizam somente a pedido do cliente. A restauração assistida de banco de dados é um fluxo de trabalho REST. Consulte ambientes de projeto e segurança de deploy.

Gerenciamento básico de Cloud VPS

O Cloud VPS básico suporta status e recursos alocados através de impreza_api_call, e inicialização, desligamento gracioso e reinicialização através de impreza_cloud_power. Use o ID de serviço WHMCS de impreza_list_services. As ferramentas avançadas de infraestrutura em nuvem não são mais anunciadas; chamadas aposentadas retornam FEATURE_NOT_AVAILABLE. Entre em contato com o suporte da Impreza para outras mudanças de infraestrutura. Pedidos e cancelamentos mantêm seus fluxos de trabalho normais de conta. O gerenciamento de aplicativos através de um agente inscrito é separado.

Configuração, métricas e recuperação (0.39.0)

Revise a configuração do aplicativo com ferramentas export/prepare/get/apply; inspecione métricas por aplicativo e regras de alerta; baixe partes de backup e revise/aplique uma restauração PostgreSQL em um novo banco de dados. Aplicar uma revisão exige seu digest e confirmação explícita; aceitação é trabalho enfileirado, não conclusão verificada. As ferramentas personalizadas de deploy e preparação também suportam static_files e go_build. Métricas e bindings MariaDB exigem agente 0.6.17 ou mais recente. Consulte configuração, métricas e recuperação para permissões, exemplos e limites. Nenhuma atualização automática de servidor ocorre.

Runtime isolado através de Tor (0.42.0)

Deploys de imagem personalizada e fonte podem optar por participar com tor_egress: true através de impreza_deploy_custom e preparação de deploy salva. Esta opção exige um agente anunciando tor-egress-v1, Docker Engine 28+ e um aplicativo compatível com SOCKS5h. O runtime não tem fallback direto de saída. Downloads de fonte, pulls de imagem e builds mantêm a conexão de rede normal do servidor. Instalações de catálogo, manifestos importados e bindings de serviço externos não são suportados. Consulte o guia de runtime Tor para disponibilidade e verificação. Esta opção é separada de usar Tor para conectar o cliente MCP em si e de publicar um endereço onion de entrada.

Failover de jurisdição e leituras mais seguras (0.48.0)

Failover frio revisado. Quatorze ferramentas movem um aplicativo para um standby frio em outro servidor que você possui, em um país diferente, através de uma revisão que você confirma. Os aplicativos revisados são Memos 0.31.0 e, desde 0.48.1, Uptime Kuma 2.5.5 do catálogo. Crie o standby com impreza_deploy_catalog_app e standby: true, sem domínio ou onion; ele inicia sem rota pública. Em seguida, emparelhe e leia-o (impreza_pair_failover_standby, impreza_get_failover_standby). Para um servidor externo, primeiro declare seu país com impreza_declare_external_failover_country (declarado por você, não verificado pela Impreza; servidores gerenciados relatam o deles). Confirme a cadeia exata de backup/restauração/redeploy (impreza_confirm_failover_sync), depois prepare, leia e aplique uma revisão (impreza_prepare_failover, impreza_get_failover, impreza_apply_failover e impreza_retry_failover_activation quando a ativação do destino precisar de outra tentativa).

Após um failover verificado, impreza_prepare_failback, impreza_get_failback e impreza_apply_failback liberam o host antigo e invertem o par: o primário antigo se torna o standby frio, e nenhum tráfego se move. O retorno de tráfego é um backup, restauração, confirmação de sincronização e failover revisado comuns. impreza_set_failover_drill_policy, impreza_run_failover_drill e impreza_get_failover_drill atualizam o standby com uma cópia fria executada pela plataforma, sob demanda ou a cada 60 a 10080 minutos, e registram quanto tempo cada etapa levou.

O que se move: um hostname na zona gerenciada, ou um endereço onion público através de sua exportação selada. Domínios personalizados, serviços onion privados, bindings de banco de dados e servidores dedicados não são suportados. Aplicar interrompe a fonte e pode interromper o tráfego ou perder escritas feitas desde o backup restaurado: revise a fonte, o destino e a idade do backup com o usuário, depois passe o cutover_id exato (ou failback_id), review_digest e confirm: true. A aceitação é assíncrona: leia a revisão até que seja verificada ou relate uma falha acionável. Onde o failover não está habilitado na API, essas ferramentas retornam o 404 da API. O conector hospedado exige uma credencial de conta sem restrições. Guia: failover de jurisdição.

Também em 0.48.0:

impreza_vps_resize_recommendation: se um VPS configurável precisa de mais CPU, memória ou disco, julgado pela carga sustentada que seu agente relata.
impreza_get_host_inventory omite impressões digitais de chave de host SSH, a menos que você passe include_ssh_fingerprints: true.
Erros de API retornam como structuredContent com um code e next_steps.
npx -y impreza-mcp login --code <code> emparelha o servidor local com um código de uso único da área do cliente (consulte Emparelhar o CLI local).
O playbook de publicação diagnostica um deploy com falha com impreza_doctor e impreza_get_logs.

Visão geral da conta, playbooks e operações mais seguras (0.47.0)

Doze novas ferramentas e cinco prompts:

Visão geral da conta: impreza_get_account_overview posiciona um assistente na conta em uma única chamada somente leitura: servidores, aplicativos e ambientes, domínios, alertas abertos, falhas recentes de implantação e as próximas ações sugeridas. Uma credencial restrita a alguns recursos vê cada seção filtrada para eles.
Playbooks como prompts: prompts/list oferece cinco procedimentos guiados: impreza_publish_git, impreza_change_domain, impreza_diagnose_deployment, impreza_restore_backup e impreza_update_agent. Eles não concedem autoridade; cada etapa ainda passa pelas ferramentas e suas confirmações.
Pausar e retomar o agente de um servidor: impreza_pause_agent interrompe o envio de novos comandos e suspende credenciais restritas àquele servidor; impreza_resume_agent as traz de volta. Trabalho já enviado pode ser concluído. Ambos exigem uma credencial sem restrições com escopo de gerenciamento e confirm: true.
Planos de host com aprovação humana: impreza_host_permissions, impreza_prepare_host_plan, impreza_get_host_plan e impreza_apply_host_plan preparam uma reinstalação de VPS que uma pessoa aprova no painel (servidor exato, template, digest e prazo) antes de ser executada. Uma IA não pode aprovar seu próprio plano.
Reimplantações sem tempo de inatividade: impreza_get_zero_downtime explica se um aplicativo se qualifica e todos os motivos pelos quais não; impreza_set_zero_downtime ativa isso para um aplicativo personalizado e define a verificação de prontidão. Requer agente 0.6.27 ou posterior.
Leituras: impreza_get_shield (política de Shield e as últimas 24 horas de descobertas de WAF, sem identidade do visitante), impreza_privileged_audit (a auditoria de admissão de operações privilegiadas na conta) e impreza_get_host_inventory (fatos de host na lista de permissões; requer agente 0.6.28, ainda não lançado, e informa isso).
Saída estruturada: ferramentas de leitura declaram um outputSchema e retornam structuredContent; segredos de uso único permanecem no texto e nunca no resultado estruturado.

Paridade local e hospedada (0.46.0)

O pacote local agora inclui as 16 ferramentas que apenas o conector hospedado tinha:

projetos e ambientes: impreza_rename_project, impreza_delete_project, impreza_rename_environment e impreza_delete_environment;
grupos de variáveis: impreza_get_variable_group e impreza_set_variable_group;
promoção de configuração: impreza_prepare_config_promotion, impreza_get_config_promotion e impreza_apply_config_promotion;
implantações ordenadas por ambiente: impreza_deploy_environment, impreza_get_environment_deploy e impreza_list_environment_deploys;
atualizações de agente: impreza_get_update_policy, impreza_set_update_policy e impreza_request_agent_update;
Shield: impreza_set_shield.

As anotações de ferramentas (somente leitura, destrutivas, idempotentes) agora correspondem ao conector hospedado. Uma ferramenta destrutiva chamada com confirm ausente ou falso é recusada antes que qualquer solicitação seja enviada.

Recuperação pontual de PostgreSQL (0.45.0)

Seis ferramentas cobrem status, configuração, um exercício de recuperação e preparação/obtenção/aplicação de um ponto de recuperação UTC revisado: impreza_get_pitr, impreza_configure_pitr, impreza_drill_pitr, impreza_prepare_pitr_restore, impreza_get_pitr_restore e impreza_apply_pitr_restore. Status usa escopo de leitura; alterações usam escopo de implantação. O conector hospedado exige uma credencial sem confinamento de recursos porque a recuperação física de PostgreSQL pode cobrir várias vinculações em um provedor.

Backups WAL e base consomem o armazenamento da conta. Após seis falhas consecutivas, o trabalho automático pausa até que a causa seja reparada e a configuração seja salva novamente. Desativar interrompe a proteção, mas retém objetos armazenados. Uma restauração exige o digest de revisão e confirm: true, cria um novo banco de dados e nunca redireciona o aplicativo ativo. Consulte a revisão até que o recibo diga verified ou failed; a aceitação sozinha não é uma recuperação bem-sucedida.

Tarefas agendadas (0.45.0)

impreza_create_task cria uma tarefa agendada em um aplicativo e impreza_update_task altera uma existente (qualquer campo que você omitir mantém seu valor atual, então enabled=false pausa uma tarefa sem perder sua programação ou histórico), como no conector hospedado. Elas substituem impreza_schedule_task, que foi removido: atualize qualquer cliente ou prompt que ainda o chame. impreza_list_tasks, impreza_run_task e impreza_delete_task permanecem inalterados.

Redimensionamento de VPS (0.44.0)

impreza_vps_resize dá a um VPS configurável mais vCPUs, memória ou disco. Calcule o preço primeiro com impreza_api_call em /services/{id}/resize/quote, passando os novos tamanhos como query: ele retorna o valor proporcional devido hoje (o próprio valor do sistema de cobrança), o valor de renovação do VPS e se o saldo cobre isso. Em seguida, chame impreza_vps_resize com os mesmos tamanhos e max_amount definido como esse due_today, para que um preço que mudou no meio seja recusado em vez de cobrado. Os tamanhos só aumentam. O disco é ampliado imediatamente; a nova contagem de vCPUs e a memória entram em vigor quando o VPS é reiniciado com impreza_vps_power action=reboot (uma reinicialização de dentro do servidor mantém os antigos). Veja Redimensionar um VPS.

VPS configurável (0.43.0)

O VPS é um produto configurável: escolha a localização, o sistema operacional, vCPUs, memória e disco SSD. impreza_vps_offer lista cada escolha com seu preço por unidade para cada ciclo de cobrança, na moeda da conta; dada uma configuração completa (billing_cycle, location, os, cpu_cores, memory_gb, disk_gb), ele retorna o preço exato, se o saldo cobre e se essa localização tem espaço agora. impreza_order_vps pede essa configuração com product_id omitido; planos fixos como Tor Hosting ainda são pedidos por product_id. O preço cobrado é o preço cotado. Veja Pedir um VPS.

Pré-visualizações privadas de onion e identidades retidas (0.42.0)

A criação de pré-visualizações suporta private: true; opcionalmente, forneça um ou mais onion_clients. Revisores fornecidos usam um nome e chave pública X25519. Sem clientes fornecidos, um par de chaves de revisor é gerado e a chave privada é mostrada uma vez. Este modo requer agente 0.6.20 com onion-private-preview-v1; a autorização do revisor é instalada antes da primeira publicação de onion. Implantações repetidas preservam revogações posteriores. Não combine esta opção com pré-visualizações HTTPS protegidas por senha.

impreza_purge_onion_key exige o endereço onion antigo exato e confirmação explícita. Trabalho enfileirado não é prova de exclusão: inspecione seu resultado concluído. Endereços ativos são recusados. A purga remove cópias retidas naquele servidor; exportações e backups em outros lugares permanecem. Liberar uma reserva para um aplicativo não instalado não exclui material de chave.

Veja o guia de onion para permissões, etapas de atualização do cliente e limitações suportadas.

Versões de dependências

O manifesto do pacote fixa cada dependência direta de runtime a uma versão exata: @modelcontextprotocol/sdk 1.29.0, tar 7.5.22 e zod 3.25.76. Builds de fonte usam package-lock.json para a árvore de dependências testada. Dependências transitivas podem mudar durante uma instalação nova do consumidor; atualizações de dependências exigem um pacote reconstruído, um teste de instalação limpo e uma revisão da árvore instalada antes do lançamento.