StudioForge 2.0: Contas, Chaves de API Escopadas e um Caminho de Atualização Seguro

O StudioForge é o servidor de modelos baseado exclusivamente em GPU que criei para substituir o LM Studio no meu computador (a história completa está descrita neste artigo). A versão 2.0 alterou quem pode se comunicar com ele. Na versão 0.2.0, o servidor escutava em todas as interfaces de rede e confiava em qualquer um que conseguisse acessá-lo; havia também um PIN opcional para as ferramentas de agente. Já na versão 2.0, ele escuta apenas na máquina onde está rodando, a menos que você configure de outra forma; além disso, agora todos os solicitantes precisam de uma chave de acesso.

Código-fonte no GitHub

Eu atualizei meu próprio computador em 19/10/2026. Todos os programas que tentavam se conectar ao StudioForge sem uma chave começaram a receber erro 401 em poucos minutos: minha ferramenta de e-mail, meu aplicativo de chat, o mecanismo de busca de memória do gateway de agentes, além de vários scripts. Nenhum deles estava com problema; simplesmente ainda não tinham a chave necessária. Esta página é exatamente o que eu gostaria de ter lido antes.

O que muda para você

Três coisas, em termos simples.

• É privado por padrão. O gateway (porta 1234), o painel de controle (8080) e o mecanismo de recuperação (1235) ficam vinculados ao 127.0.0.1. Outras máquinas não conseguem acessá-los de forma alguma.
• Para abrir o acesso, é necessário fazer login. Se algum dos três serviços passar a escutar em um endereço de rede, mas não houver conta de proprietário nem chave de administrador, o studioforge serve será encerrado com código de saída 4, indicando como corrigir isso. Assim, você não conseguirá mais executar um servidor aberto por acidente.
• Cada programa recebe sua própria chave. Uma chave é uma string do tipo sf-i-… que o programa envia como Authorization: Bearer <key>. Cada chave possui um nome, um escopo, uma data de expiração opcional e um limite opcional de requisições por minuto; você pode revogar uma chave sem afetar as demais.

Aqui está a rejeição, resultante do meu teste inicial com os três hosts configurados como 0.0.0.0 e sem nenhuma conta criada:

error: Refusing to start: the gateway, the control panel, the watchdog would listen on a
non-loopback address (0.0.0.0, 0.0.0.0, 0.0.0.0) but no owner account or admin API key exists,
so anyone on the network could drive this server. Fix: run `studioforge setup` (creates the
owner account) or `studioforge keys create --name admin --scope admin`, then start again.

Um detalhe me pegou de surpresa: a criação da primeira chave ativa a autenticação para todos, incluindo programas rodando na mesma máquina. Criei uma chave em um servidor de teste configurado apenas para loopback; logo após isso, uma requisição simples via curl para /v1/models na mesma máquina passou do código 200 para 401. A CLI, a bandeja e o painel do StudioForge continuam funcionando normalmente, pois criam sua própria chave de administrador local (local-cli, armazenada apenas para o proprietário no diretório de dados). Tudo o mais, a partir daí, passa a exigir uma chave válida.

A atualização segura em dez minutos

Esta é a ordem correta para manter o tempo de indisponibilidade curto. Ela segue os passos de migração descritos no CHANGELOG, com duas correções baseadas na minha própria experiência.

1. Liste todos os seus clientes. Todo aplicativo de chat, agente, script ou outro mecanismo que se comunica com o servidor. Se não tiver certeza, procure nos arquivos de configuração pelo endereço do servidor. Essa lista representa todo o trabalho necessário.
2. Faça backup e pré-visualização. Copie o diretório de dados, atualize o código (git pull) e reinstale-o no seu venv conforme descrito no README para a sua plataforma. Em seguida, execute studioforge migrate --dry-run. A versão 2.0.1 move o banco de dados para o esquema 10; o comando studioforge migrate faz backup antes de aplicar as alterações.
3. Crie a credencial necessária para iniciar o servidor. Use studioforge setup (o processo guiado na primeira execução; ele cria a conta de administrador e, se você escolher “minha rede local”, ativa o HTTPS e gera uma chave administrativa), ou simplesmente execute studioforge keys create --name admin --scope admin.
4. Crie uma chave para cada cliente, todas de uma vez, antes de iniciar o novo servidor:

   studioforge keys create --name chat-app  --scope inference --rate-limit-rpm 120
   studioforge keys create --name dashboard --scope read
   studioforge keys create --name laptop    --scope admin --expires-in-days 30

   Cada token é exibido apenas uma vez e nunca armazenado; portanto, cole-o imediatamente na configuração do respectivo cliente.
5. Inicie o servidor e teste cada cliente com uma requisição real. Um erro 401 invalid_api_key indica que o cliente ainda não possui chave; um erro 403 permission_denied significa que o escopo da chave é insuficiente para a operação solicitada.
6. Desative as credenciais antigas por último. Depois que todos os clientes estiverem funcionando com suas próprias chaves: execute studioforge keys revoke legacy, remova o valor de server.api_key e desative o PIN do MCP. Consulte o problema relacionado ao PIN abaixo; apenas remover o PIN não é suficiente.
7. Execute studioforge doctor e leia as informações retornadas.

Se você já utilizava server.api_key, a atualização em si não causa problemas: a chave antiga é copiada para a tabela de chaves como uma chave administrativa chamada legacy e continua funcionando. No meu caso, não havia nenhuma chave compartilhada, apenas o PIN; por isso todos os clientes pararam de funcionar ao mesmo tempo. Fazer o passo 4 antes do passo 5 teria evitado a maior parte desse problema.

O painel: login, configuração e criação de chaves

Estas capturas de tela são de uma instância temporária do StudioForge versão 2.0.1 que executei no Podman em um computador sem GPU da NVIDIA (mais detalhes abaixo); portanto, os dois cartões gráficos são simulados e as chaves não têm valor real.

O painel agora possui uma página de login. Use o nome de usuário e a senha do proprietário, ou deixe o nome de usuário em branco e cole uma chave de administrador. Uma chave de read ou de inference não consegue acessá-lo.

O guia de configuração em /setup explica oito etapas: conta do proprietário, hardware, motor de processamento, bibliotecas de modelos, um modelo inicial, um teste de chat, trechos de código para clientes e quem pode acessar o servidor. Cada etapa pode ser ignorada. Na última etapa, você escolhe entre “apenas este computador” e “minha rede local, via HTTPS”.

As chaves ficam em Usuários & Chaves. Dê um nome que indique qual programa as usará, escolha o escopo e, opcionalmente, uma data de expiração e um limite de uso.

O token é exibido apenas uma vez. Ocultei-o nesta captura de tela, mas num servidor real este diálogo é a única oportunidade para visualizá-lo.

A tabela exibe o escopo de cada chave, os primeiros caracteres do token, a última data de uso, data de expiração, limite de requisições e estado atual. Abaixo dela está o log de auditoria: todas as chaves criadas ou revogadas, todos os logins e alterações feitas por administradores, com informações sobre quem realizou a ação e de onde veio. Os segredos nunca são registrados nesse log.

Escopos: read, inference, admin

Escopo	O que pode fazer	Para quem pode ser concedido
read	Visualizar: status, listas de modelos, /metrics, além de ferramentas MCP somente para leitura. Não pode realizar operações POST.	Dashboards, sistemas de monitoramento
inference	Leitura, além de funcionalidades de chat (/v1/chat/completions, /v1/messages, /v1/responses), carregar, descarregar e testar modelos, bem como assumir ou liberar o uso da GPU.	Aplicativos de chat, agentes, scripts e outros programas que utilizam GPU
admin	Alterar configurações do sistema: parâmetros, reinicializações, instalação/atualização de motores, downloads, exclusão de dados, gerenciamento de chaves e contas, além do uso de ferramentas MCP destrutivas.	Você

A regra é baseada em código, não em convenções (api/auth.py:required_scope). A verificação do escopo é feita com base no prefixo do caminho; qualquer rota que altere o estado do sistema e que não tenha um escopo definido requer admin. Assim, novas rotas são automaticamente cobertas por essa regra. O escopo é sempre verificado quando uma chave é enviada, mesmo em servidores que, teoricamente, não precisariam dele: uma chave read também não pode realizar operações POST em um servidor restrito ao loopback. Testei os limites na instância de teste: uma chave inference retornou 200 para /v1/models e 403 para /api/keys.

Os agentes também recebem uma chave, nunca a senha do proprietário. Na página de Integrações do painel, são exibidos blocos prontos para cópia destinados ao OpenClaw, aos SDKs Python da OpenAI e da Anthropic, ao DisPatch, ao curl e ao arquivo --mcp-config do Claude. Primeiro é preciso selecionar uma chave no menu suspenso; com o valor padrão selecionado, o bloco de código curl omite o cabeçalho Authorization, portanto, ao ser colado assim como está, resultará em um erro 401.

A conta do proprietário, a chave compartilhada antiga e o PIN

A versão 2.0 possui três tipos de credenciais; duas delas estão em processo de desativação.

• A conta do proprietário é usada para fazer login no painel. A senha deve ter pelo menos 10 caracteres e é criptografada com o algoritmo argon2id. O hash resultante é armazenado no “keyring” do sistema operacional, caso o componente opcional keyring esteja instalado; caso contrário, é salvo em um arquivo acessível apenas ao proprietário. Essa senha não fica no banco de dados, portanto uma cópia do banco não contém informações de login.
• server.api_key (obsoleto) ainda funciona como credencial de administrador em todos os lugares; é exibido como a chave legacy. O comando keys revoke legacy realmente o desativa.
• mcp.pin (obsoleto) é uma credencial de administrador composta por oito dígitos, válida apenas para os endpoints do MCP. Em um servidor sem nenhuma outra chave, essa credencial ainda permite o acesso às rotas HTTP destinadas a chamadas remotas; assim, os pares de autenticação antigos continuam funcionando. Contudo, assim que qualquer outra chave é configurada, esse comportamento cessa.

O “problema” com o PIN. O CHANGELOG indica que se deve “limpar server.api_key e mcp.pin”. Porém, se você definir apenas mcp.pin: null, na próxima inicialização um novo PIN aleatório será gerado e salvo, pois mcp.pin_required permanece como true. Eu vi isso acontecer pessoalmente. Para desativá-lo de verdade, defina ambos os valores:

mcp:
  pin: null
  pin_required: false

Pela mesma lógica, uma instalação nova da versão 2.0.1 gera um PIN na primeira inicialização; posteriormente, o comando studioforge doctor o identifica como obsoleto. Isso não causa nenhum problema, mas não se surpreenda ao ver esse comportamento.

Vinculação de rede, HTTPS e navegadores

• Regra de vinculação. server.host, gui.host e watchdog.host têm como valor padrão 127.0.0.1. Uma configuração criada por uma versão mais antiga especifica explicitamente 0.0.0.0; portanto, o novo valor padrão não a altera. Essa configuração bloqueia todas as solicitações até que uma credencial válida seja fornecida.
• HTTPS. server.tls.mode é um único parâmetro que controla os três listeners: off, self_signed (um certificado gerado no diretório de dados; sua impressão digital SHA-256 é exibida no painel para que os clientes possam validá-lo) ou cert (arquivos de certificado fornecidos pelo usuário). Quando a vinculação de rede está ativada e o TLS desligado, doctor avisa que as chaves são transmitidas pela rede em texto puro. Um proxy reverso ou o uso do tailscale serve também funcionam como solução.
• Navegadores. Agora, server.cors_origins tem valor padrão vazio (antes era ["*"]). Clientes não navegadores não são afetados por essa mudança. Os endpoints MCP realizam sua própria verificação de origem: uma solicitação que contenha o cabeçalho Origin deve vir de uma página local ou de um domínio listado; o valor * não é considerado válido. Isso impede que qualquer página da web controle as ferramentas de gestão do seu sistema através do navegador.
• Força bruta. Após três tentativas incorretas por endereço IP, o sistema impõe um tempo de espera progressivo, chegando a cinco minutos; esse bloqueio é aplicado separadamente à API, ao painel e ao watchdog.

Compartilhamento das GPUs: concessões e tenants

Se houver outro programa no sistema utilizando as GPUs (um gerador de imagens, um servidor de voz, um benchmark), esse programa pode primeiro obter uma concessão para usar uma GPU. Nesse caso, o StudioForge não carregará nenhum modelo naquela GPU até que a concessão seja liberada ou permaneça inativa após o período de timeout definido. A versão 2.0 introduz um registro de tenants, permitindo que esses programas se anunciem e apareçam na página de Placement com informações atualizadas sobre seu status. Além disso, existe a opção devices: "auto", que permite que um tenant solicite qualquer GPU que tenha memória livre suficiente, em vez de especificar uma GPU específica. O StudioForge exibe os tenants e pode solicitar que um deles “aqueça” ou libere uma GPU, mas nunca inicia ou para esses programas.

A correção da versão 2.0.1 é importante caso você utilize algum desses programas: na versão 2.0.0, as rotas destinadas aos tenants exigiam uma chave admin; assim, um servidor de voz ou de geração de imagens que utilizasse uma chave inference recebia o erro 403 ao tentar obter uma concessão. Na versão 2.0.1, essas rotas passaram a ser do tipo inference; cada concessão fica vinculada à chave que a solicitou: outra chave inference não consegue liberar essa concessão (eu tentei e recebi o erro 403 permission_denied com a mensagem “A concessão … não foi criada por esta chave API”). Já uma chave admin ainda consegue fazer isso.

Uma coisa importante a saber ao registrar um tenant: as concessões são vinculadas aos tenants com base na família, que corresponde ao nome do tenant até o primeiro -. Um tenant registrado como speech-demo não consegue ver sua própria concessão speech-demo (pois a “família” dessa concessão é speech); porém, se registrado como speech, consegue vê-la. Portanto, recomenda-se usar nomes de tenant sem hífens. O próprio protocolo está documentado no arquivo docs/TENANTS.md do repositório.

sfctl 2.0.1, o controle remoto

sfctl é um pequeno cliente para controlar um servidor StudioForge a partir de outra máquina, além de atuar como ponte MCP para agentes. Agora ele requer uma chave para funcionar. O pacote não está disponível no PyPI (o comando uv tool install studioforge-companion mencionado no README falha), portanto é preciso instalá-lo a partir de um clone:

git clone https://github.com/LaserLloyd/StudioForge.git
uv tool install ./StudioForge/packages/studioforge-companion
sfctl servers add rig http://192.0.2.10:1234 --api-key sf-i-your-key --use
sfctl status

O perfil de configuração deve ser salvo em ~/.config/studioforge/companion.toml; esse arquivo é acessível apenas pelo proprietário, pois contém a chave necessária. Como alternativa, você pode usar a variável de ambiente SF_API_KEY. Caso o gateway não esteja na porta 1234, adicione o parâmetro --watchdog-url, já que o endereço do watchdog é derivado do endereço do gateway. No meu ambiente de teste, utilizei uma chave do tipo inference:

$ sfctl status
┏━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━┳━━━━━━━━━━┓
┃ GPU ┃ Name                           ┃ Total    ┃ Used ┃ Free     ┃
┡━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━╇━━━━━━━━━━┩
│ 0   │ Demo GPU 0 (simulated) (sm_86) │ 24.0 GiB │ 0 B  │ 24.0 GiB │
│ 1   │ Demo GPU 1 (simulated) (sm_86) │ 24.0 GiB │ 0 B  │ 24.0 GiB │
└─────┴────────────────────────────────┴──────────┴──────┴──────────┘
no models loaded

$ sfctl leases add --devices 1 --holder image-render --reason "a render job outside StudioForge"
lease 933d9554c0c6 holds GPU 1 for image-render
release it with: sfctl leases release 933d9554c0c6

(Eu removi as colunas “Util” e “Temp”, bem como a tabela de servidores, para caber no espaço disponível.)

Doctor e o pacote de suporte

studioforge doctor verifica portas, GPUs, o motor do sistema, disco, permissões de arquivos, certificados, migrações e configurações de autenticação, exibindo uma solução para cada problema encontrado. O parâmetro --strict faz com que o programa retorne um código diferente de zero também em caso de avisos, o que é útil para monitoramento. Este é o container de demonstração: ele escuta na rede com uma conta de proprietário e sem TLS ativado:

[ok  ] GPU: 2 GPU(s) via fake: Demo GPU 0 (simulated) (24 GiB), Demo GPU 1 (simulated) (24 GiB).
[WARN] Engine: No llama.cpp engine is installed.
        fix: Run `studioforge setup` or `studioforge engine --update` to install and smoke-test one.
[ok  ] Permissions: The data directory is writable and credential files are owner-only.
[ok  ] Migrations: The database is at schema 10 (current).
[info] Authentication: The server listens on the network and requires an API key or an account.
[WARN] Authentication: The network listeners use plain HTTP, so keys and passwords cross the network in the clear.
        fix: Set server.tls.mode to self_signed (or cert), or front the server with a TLS reverse proxy / `tailscale serve`.
[info] Authentication: mcp.pin is set. It is deprecated and grants admin on the MCP endpoints.

9 ok, 3 info, 2 warnings, 0 failures.

No servidor de teste local, onde ainda estava definido o parâmetro server.api_key, o mesmo comando exibiu o aviso: “server.api_key está definido. Continua funcionando (como a chave de administrador ‘legacy’), mas está obsoleto”. A solução sugerida foi criar chaves com escopo específico, migrar os clientes e revogar a chave legacy.

studioforge support-bundle gera um pequeno arquivo ZIP para relatórios de erros: uma configuração anonimizada, os resultados do diagnóstico, versões dos componentes, lista de GPUs e trechos dos logs. O meu arquivo tinha 6 KiB; o PIN aparecia como [REDACTED]. O comando também anonimiza o valor de engine.pinned_tag, que corresponde ao número da versão do llama.cpp. Esse dado é útil em relatórios de erros, mas não é um segredo; portanto, deve ser inserido manualmente. O próprio comando adverte: “olhe antes de compartilhar”, e isso é muito certo.

Executando em um container

A versão 2.0 inclui um Dockerfile com variantes para CUDA, ROCm e Vulkan, além de um usuário não-root, um sistema de arquivos raiz somente leitura e um volume nomeado. Também há arquivos compose para Docker e Podman. O container cria a conta do proprietário na primeira inicialização, utilizando a senha definida em SF_OWNER_PASSWORD ou uma senha gerada e salva no volume; isso ocorre porque uma porta publicada é considerada “fora do loopback” dentro do container. As portas são publicadas para 127.0.0.1, a menos que você defina SF_BIND.

As imagens ainda não estão disponíveis em nenhum registro (hoje, o pull de ghcr.io/laserlloyd/studioforge é recusado); portanto, você precisa compilar a imagem por conta própria. O README contém os comandos exatos para cada plataforma. Para estas capturas de tela, compilei a imagem Vulkan usando o Podman: ela tem 568 MB e funciona em modo somente leitura, com todas as capacidades desativadas. A imagem NVIDIA é a única que já executou um modelo real; as imagens para AMD e Vulkan inicializam normalmente e respondem ao endpoint /health, mas ainda não foram testadas em hardware AMD ou Intel. O tamanho das imagens, os parâmetros relacionados às GPUs, os testes de atualização e os backups de toda a pilha estão descritos em Cada módulo no Docker; por isso, não os repetirei aqui.

Também novo na versão 2.0

• Mais clientes funcionam sem alterações: A API REST nativa do LM Studio em /api/v1, uma API compatível com o Anthropic em /v1/messages (os parâmetros x-api-key ou bearer funcionam igualmente), e uma interface sem estado da OpenAI em /v1/responses.
• Erros que indicam como ser corrigidos: 76 códigos de erro, cada um com os campos fix e docs no corpo da mensagem de erro. O código 401, retornado para clientes sem chave, indica qual comando deve ser usado para gerar uma chave.
• Suporte a mais plataformas do que apenas NVIDIA: Detecção de GPUs ROCm, Vulkan e Metal, além de um instalador de mecanismos capaz de verificar as somas de verificação dos arquivos. Os testes foram feitos com saídas de detecção simuladas, não em hardware real da AMD ou Apple. Dispositivos Vulkan de software, como o llvmpipe, são rejeitados, pois a execução de modelos na CPU é exatamente o que o StudioForge foi criado para evitar.
• Um painel mais completo: 11 seções (Visão Geral, Modelos, Serviço, Mecanismos, Integrações, Usuários & Chaves, Atualizações, Logs & Métricas, Diagnósticos e Avançado) e três novos temas visuais.
• Controle de versão semântico: A versão 2.0.0 segue a versão anterior (1.26-09-23); o sistema de atualizações consegue ordenar corretamente ambos os esquemas de numeração.

Como testei isso, e o que não testei

A máquina em que escrevo este texto não possui nenhuma GPU da NVIDIA; por isso, não consegui carregar nenhum modelo. O StudioForge dispõe de um backend de GPU simulado para seu conjunto de testes (SF_GPU_PROBE=fake, com uma lista de placas de vídeo em formato JSON em SF_FAKE_GPUS). O painel, as chaves, as contas, os “leases”, os “tenants”, o módulo “doctor” e o pacote de suporte são todos executados nesse ambiente simulado. Tudo o que está descrito acima como “eu tentei” ou que exibe alguma saída foi testado na versão 2.0.1: uma vez a partir de uma cópia do repositório em um diretório temporário, e outra vez dentro de um container Podman; ambos os testes foram realizados em portas de loopback, usando arquivos de modelo que contêm cabeçalhos, mas sem pesos reais. Os tamanhos dos modelos e as informações de quantização exibidas no painel são valores reais extraídos desses cabeçalhos; os modelos em si, porém, não existem de fato.

O que eu não testei aqui: o carregamento ou a disponibilização de modelos, o TLS no modo self_signed, o ícone da área de notificação no Windows, e um upgrade “in-place” a partir de um diretório de dados da versão 1.26 (o artigo sobre Docker descreve um processo de upgrade no mesmo volume). A informação sobre o upgrade mencionada no início deste texto vem do meu próprio computador, e não da instância temporária usada nos testes.

Pontos problemáticos

• Ainda não há lançamento. A versão 2.0.1 encontra-se no branch main, sem nenhuma tag, sem lançamento no GitHub, sem pacote no PyPI e sem imagem publicada. O sistema de autoatualização não tem nada para atualizar enquanto isso não acontecer.
• Um aviso enganoso. Num servidor em rede que possui uma conta de administrador, mas nenhuma chave server.api_key, a lista de verificação de configuração ainda indica que o servidor está acessível “sem nenhuma chave de API: qualquer pessoa na rede local pode carregar, descarregar e excluir modelos”. Na verdade não é assim: tanto a página “Usuários & Chaves” quanto as requisições reais indicam que o login é obrigatório. A lista de verificação considera apenas a antiga chave compartilhada.
• A documentação diverge quanto ao motor do contêiner. O guia de uso do Docker no README utiliza a imagem de 14 GB -cuda-devel e compila o llama.cpp na primeira inicialização; já o guia de contêineres afirma que a imagem mais leve -cuda baixa um motor pré-compilado. Não consegui resolver essa discrepância sem uma placa NVIDIA; por enquanto, siga as instruções do README até que ambos os guias fiquem alinhados.
• Ninguém mais fez auditoria no sistema. O modelo de segurança está descrito no arquivo docs/SECURITY.md do repositório, incluindo o que ele não protege (por exemplo, um administrador na mesma máquina ou comunicação HTTP padrão numa rede fora do seu controle). Leia-o antes de colocar o StudioForge numa rede compartilhada.

Obtenha-o

git clone https://github.com/LaserLloyd/StudioForge.git

</>

Em seguida, siga as instruções do README para a sua plataforma. O arquivo zip mais antigo no artigo original é a versão 0.2.0 e não contém nenhum desses recursos. Licença: MIT.

Relacionado: StudioForge: um servidor LLM que utiliza apenas GPU (o planejador, as medições e as ferramentas MCP), Todos os módulos em Docker (a rota de implantação do conjunto completo em contêineres), e DisPatch (um aplicativo de chat que se conecta a ele usando uma chave).