runapps/skills

RunApps via MCP

RunApps (https://www.runapps.ai) publica aplicativos web de IA: um criador envia um pacote de frontend estático (zip), ele é servido em seu próprio https://<slug>.runapps.dev, os usuários fazem login com uma conta RunApps e pagam por seu próprio uso de modelo, e o criador ganha uma taxa em cada chamada. Tudo abaixo é feito através do servidor MCP runapps e do SDK. Ainda não está conectado? Veja "Conectando".

Este arquivo é o ponto de entrada: conexão, o modelo da plataforma, o catálogo de ferramentas, o fluxo de trabalho e as regras. O SDK (como o código do aplicativo se comunica com modelos e arquivos) está em references/sdk.md; os parâmetros exatos das ferramentas estão em references/tools.md. Leia apenas o que a tarefa precisar.

Conectando (autorização)

A versão oficial e sempre atual é https://www.runapps.ai/agent/setup.md; esta é a versão resumida. O usuário nunca digita uma senha para você e você nunca vê uma: você pede uma chave, o usuário clica em Aprovar uma vez em um navegador.

1. Solicitar uma chave: POST https://www.runapps.ai/api/agent/device/code com JSON {"name": "<seu nome> @ <máquina>", "scopes": "read,develop,publish,gateway"}. A resposta contém device_code, user_code, verification_uri_complete (https://www.runapps.ai/agent/authorize?code=XXXX-XXXX), expires_in (600 s) e interval (5 s). Mostre verification_uri_complete ao usuário exatamente como está e peça para ele abrir e aprovar. name é a identidade da chave: aprovar uma solicitação com o mesmo nome revoga a chave anterior com esse nome, então reexecutar a configuração não acumula chaves.
2. Verificar (polling): POST https://www.runapps.ai/api/agent/device/token com {"device_code": "…"} a cada interval segundos. O status pode ser pending (aguarde), slow_down (diminua a frequência), denied / expired (pare e informe o usuário) ou approved, que retorna api_key (rk_…), key_prefix, scopes e mcp_url — uma vez. Escreva-a imediatamente na sua configuração MCP; nunca na conversa, logs ou repositório.
3. Conectar: MCP Streamable HTTP em https://www.runapps.ai/api/mcp com cabeçalho Authorization: Bearer <api_key>. Claude Code: claude mcp add --transport http runapps "https://www.runapps.ai/api/mcp" --header "Authorization: Bearer <api_key>". Codex: [mcp_servers.runapps] url = "https://www.runapps.ai/api/mcp", http_headers = { Authorization = "Bearer <api_key>" }. Outros clientes: a mesma URL e cabeçalho. Em seguida, tools/list; as instructions de initialize fornecem o fluxo de trabalho recomendado.

Escopos: read, develop, publish, gateway são concedidos por padrão; danger (excluir / cancelar publicação) nunca é incluído a menos que você o solicite explicitamente e informe ao usuário o motivo. O usuário pode desmarcar escopos na página de aprovação e, posteriormente, renomear a chave, alterar seus escopos ou revogá-la em https://www.runapps.ai/dashboard/api (uma alteração de escopo é aplicada na sua próxima chamada, nenhuma nova chave é necessária). Uma ferramenta chamada sem seu escopo responde com um erro nomeando o escopo: peça ao usuário para autorizar novamente, não contorne isso.

A mesma chave funciona no gateway (https://www.runapps.ai/v1, compatível com OpenAI, Authorization: Bearer rk_…) quando tem o escopo gateway — para testar o aplicativo que você está construindo; cada chamada é cobrada do usuário. Para desconectar definitivamente, chame revoke_my_key com confirm: true.

O modelo da plataforma

Objeto	O que é	Como você o acessa
App (projeto)	Um pacote publicado com um slug atribuído pela plataforma, nome, descrição de uma linha, descrição longa em Markdown, categoria, ícone, visibilidade e taxa do criador (rebate_rate). Criado como rascunho sem pacote, para que o slug exista antes de qualquer código.	list_apps, get_app, create_app, update_app
Pacote (bundle)	O zip do build do aplicativo. Armazenado inteiro; os arquivos são servidos a partir dele em https://<slug>.runapps.dev. Arquivos ocultos (.private/…) nunca são servidos; index.html na raiz do zip é a entrada padrão.	upload_bundle (+ PUT), upload_bundle_base64, check_bundle
Visibilidade	draft (apenas o criador) → private (não listado: qualquer pessoa com o link, sem revisão) ou public (na biblioteca; a primeira mudança para público é revisada e mostra pending, atualizações posteriores são publicadas imediatamente; uma rejeição inclui review_note).	update_app com visibility, get_review
Usuário e login	Os usuários fazem login com sua conta RunApps dentro do aplicativo (o SDK faz isso; new RunApps() sem chave). Cada usuário paga por seu próprio uso de modelo mais a taxa do criador. O aplicativo nunca contém uma chave.	SDK (references/sdk.md)
Prompts privados	Arquivos de prompt que o aplicativo envia, mas os navegadores nunca veem: .private/prompts/<id>.md no zip; o aplicativo envia prompt: { id, vars } e o gateway preenche e anexa o prompt.	get_app / check_bundle listam os ids encontrados
Arquivos e sincronização por usuário	Cada usuário tem um espaço de arquivos por aplicativo (client.files), e uma sincronização IndexedDB (client.sync) espelha um banco de dados local nele.	SDK
Modelos	Um catálogo de modelos de chat, visão, imagem, fala, transcrição, vídeo, embedding e tempo real; a requisição nomeia o modelo pelo seu nome no catálogo.	list_models
Chave de agente	A chave rk_ que você possui: kind = agent, com escopos; listada nas Chaves de API do usuário.	revoke_my_key

Categorias: Criativo, Conteúdo, Produtividade, Marketing, Engenharia, Design, Pesquisa, Análise de Dados, Negócios, Finanças.

Fluxo de trabalho

1. Criar: create_app com name (e description, category). O resultado tem slug (proj-xxxxxxxx, atribuído pela plataforma e nunca escolhido por você ou pelo usuário; um administrador pode posteriormente dar um slug legível a um aplicativo listado) e url. Informe o slug ao usuário.
2. Desenvolver localmente usando o slug (references/sdk.md, "Build an app"):

   <script src="https://www.runapps.ai/sdk/latest.js"></script>
   <script>
     const client = new RunApps({ project: "<slug>" });
     const r = await client.chat.create({ model: "Claude Sonnet 4.6", messages: [{ role: "user", content: "oi" }] });
   </script>
   

   O login de http://localhost:<porta> funciona e as chamadas passam pelo gateway real. Escolha modelos de list_models (nomes exatos). Nunca coloque uma chave rk_ no código do aplicativo.
3. Compilar e zipar o conteúdo da pasta de build: cd dist && zip -r ../app.zip . para que index.html esteja na raiz do zip (zipar a própria pasta é o erro mais comum). Caminhos absolutos de assets funcionam; pastas ocultas são escondidas.
4. Enviar (upload): upload_bundle → PUT do zip em upload_url (curl -sS -X PUT -H 'Content-Type: application/zip' --data-binary @app.zip '<upload_url>'). A resposta do PUT é o relatório do pacote: corrija todos os avisos (SDK não carregado, entrada não na raiz, uma chave na página). check_bundle o relê a qualquer momento.
5. Descrever: update_app com description (uma linha, o que faz), long_description (Markdown: o que o usuário obtém, como usar, quanto custa na prática), category, icon_url (PNG/SVG quadrado, https ou data URL).
6. Publicar: update_app visibility: "private" para um link para compartilhar, ou "public" para a biblioteca. Após "public", get_review mostra pending até que um revisor decida; rejected vem com um review_note para agir, depois defina public novamente. Abra url você mesmo (ou peça ao usuário) antes de publicar: um pacote que retorna 404 ou mostra uma página em branco será rejeitado.

Atualizações: envie um novo pacote ou altere metadados a qualquer momento; um aplicativo público permanece público.

Regras

• Ferramentas [danger] (unp_app, delete_app) removem algo que outras pessoas podem estar usando. Pergunte ao usuário primeiro e passe confirm: true somente após ele concordar; sem o escopo danger elas são recusadas de qualquer forma.
• Cada chamada de modelo feita com o escopo gateway, e cada chamada que o aplicativo do usuário faz, custa dinheiro real. Teste com prompts curtos e modelos baratos; list_models fornece preços.
• A chave é do usuário: uma por máquina (o name as distingue), nunca compartilhada, nunca escrita em nenhum lugar exceto na configuração MCP. Revogue com revoke_my_key quando solicitado a desconectar.
• Não invente nomes de modelos; use list_models. Um nome desconhecido resulta em 400, nunca em uma troca silenciosa.
• O texto de um prompt privado deve permanecer privado: o gateway retém respostas que o ecoam.

Onde ler a seguir

Tarefa	Leia
Escrever o aplicativo: login, chat, streaming, imagens, áudio, vídeo, arquivos, sincronização, prompts privados, erros	references/sdk.md
Parâmetros exatos das ferramentas e formas dos resultados	references/tools.md
Conectando (texto completo, sempre atual)	https://www.runapps.ai/agent/setup.md
Construir um pacote, publicar, ganhos	references/sdk.md → "Build an app", "Publish it"