Documentação

Tudo o que você precisa pra subir sua aplicação

Conecte um repositório GitHub, escolha os serviços que precisa (banco de dados, cache, mensageria, storage) e a plataforma cuida do resto: build automático, HTTPS válido e domínio próprio.

Introdução

A plataforma faz três coisas com você no controle:

1. Detecta sua linguagem automaticamente a partir dos arquivos do repositório (package.json, requirements.txt, go.mod, etc.). Você não escreve Dockerfile.

2. Sobe a aplicação em um endereço HTTPS válido (subdomínio nosso ou seu próprio domínio) com certificado emitido automaticamente.

3. Provê serviços auxiliares (banco de dados, cache, mensageria, object storage) com credenciais geradas e injetadas como variáveis de ambiente, prontas pra uso.

Linguagens suportadas

A detecção é automática. Basta dar push no repositório que a build identifica a stack e usa as melhores práticas pra cada uma:

Node.js

npm · yarn · pnpm

TypeScript

detecção automática

Bun

runtime + package manager

Deno

runtime nativo TS

Python

pip · Poetry · uv

PHP

composer

Go

go.mod

Rust

cargo

Java

Maven · Gradle

Ruby

bundler · Rails

Elixir

mix · Phoenix

Sites estáticos

HTML · CSS · JS

.NET

csproj · sln
A build é automática e não usa Dockerfile: o que define a stack são os arquivos do repositório, como na tabela abaixo. Precisa de outra linguagem? Fale com o suporte.

Preparar o repositório

A build olha a raiz do repositório (ou a pasta indicada em Diretório do projeto) e reconhece o projeto por um arquivo. Sem nenhum deles, o deploy falha com não identificamos como construir o projeto.

Site estático (HTML, CSS e JS)

precisa de index.html. Na raiz, com esse nome exato.

Node.js e TypeScript

precisa de package.json. Com script `start`. Se houver package-lock.json, ele precisa estar em sintonia com o package.json.

Deno

precisa de deno.json ou main.ts

Python

precisa de requirements.txt ou pyproject.toml

PHP

precisa de composer.json ou index.php

Go

precisa de go.mod

Java

precisa de pom.xml ou build.gradle

Ruby

precisa de Gemfile

Rust

precisa de Cargo.toml

Elixir

precisa de mix.exs

.NET

precisa de arquivo .csproj ou .sln

Script shell

precisa de start.sh

Vale para qualquer linguagem:

  • A aplicação deve escutar na porta da variável PORT, que a plataforma injeta. Porta fixa no código não recebe tráfego.
  • Projeto numa subpasta (monorepo): informe a pasta em Diretório do projeto, na aba Rede.
  • Precisa de comandos próprios de build ou de start? Configure na aba Comandos, usando os scripts do seu projeto (por exemplo npm run build).
Dois tropeços comuns: arquivo salvo como index.html.html, que não é reconhecido; e package-lock.json desatualizado, que faz o npm ci parar o build. Rode npm install e comite o arquivo.

Serviços disponíveis

Crie ao lado da aplicação. Cada serviço gera variáveis de ambiente automaticamente (URL de conexão, usuário, senha) que ficam disponíveis pra suas apps.

PostgreSQL
v16

Banco relacional. Endpoint TCP estável; DATABASE_URL pronta.

MariaDB
v10.11

Compatível com MySQL. DATABASE_URL com driver mysql.

MongoDB
v4.4

Banco NoSQL com autenticação root habilitada.

Redis
v7

Cache/queue com senha forte gerada automaticamente.

RabbitMQ
v3 (management)

Mensageria AMQP com 2 users (app + admin) e UI HTTPS num subdomínio próprio.

Mosquitto
v2.0

Broker MQTT para IoT e telemetria. Porta TCP para dispositivo e endereço WebSocket com HTTPS para navegador, com usuário e senha gerados.

MinIO
v2023.09

Object storage compatível com S3, exposto via HTTPS.

n8n
vlatest

Automação de fluxos low-code. Editor + webhook URL prontos com basic auth gerado.

Como funciona na prática
EvolutionAPI
v2.3.7

REST API pra WhatsApp (Baileys). A plataforma sobe Postgres + Redis dedicados juntos e injeta as connection strings. AUTHENTICATION_API_KEY auto-gerada (mostrada 1x).

Como funciona na prática

Variáveis de ambiente

Variáveis ficam disponíveis pra sua aplicação em tempo de execução via process.env, os.getenv, System.getenv ou equivalente da sua linguagem.

Quando você cria um banco de dados, Redis, RabbitMQ ou Mosquittono mesmo projeto, a plataforma injeta automaticamente as credenciais. Os nomes seguem convenções padrão da indústria:

DATABASE_URL=postgresql://user:pass@host.speedtrail.com.br:18192/dbname
DATABASE_HOST=app-db.speedtrail.com.br
DATABASE_PORT=18192
DATABASE_USER=u_appname
DATABASE_PASSWORD=...

REDIS_URL=redis://default:senha@cache.speedtrail.com.br:17430
REDIS_HOST=cache.speedtrail.com.br
REDIS_PORT=17430
REDIS_PASSWORD=...

RABBITMQ_URL=amqp://app_x:senha@queue.speedtrail.com.br:17890/%2F
RABBITMQ_HOST=queue.speedtrail.com.br
RABBITMQ_PORT=17890
RABBITMQ_USER=app_x
RABBITMQ_PASSWORD=...
RABBITMQ_MANAGEMENT_URL=https://queue-mgmt.speedtrail.com.br
RABBITMQ_ADMIN_USER=admin_x
RABBITMQ_ADMIN_PASSWORD=...

MQTT_URL=mqtt://app_x:senha@broker.speedtrail.com.br:17421
MQTT_HOST=broker.speedtrail.com.br
MQTT_PORT=17421
MQTT_USER=app_x
MQTT_PASSWORD=...
MQTT_WS_URL=wss://broker.speedtrail.com.br
Você também adiciona variáveis customizadas pela aba Variáveis da aplicação. Evite fazer echo $VAR em scripts de build, porque os logs ficam armazenados no painel.

Deploy automático via GitHub

Configuração em 3 passos:

1. No painel, instale o SpeedTrail Deploy (GitHub App) na sua conta ou organização.

2. Crie uma aplicação selecionando o repositório.

3. Faça push no branch padrão. A build inicia automaticamente, com logs em tempo real na aba Deploys.

Você também pode disparar deploy manual a qualquer momento pelo botão "Refazer deploy".

Domínio próprio

Por padrão sua aplicação responde em seuapp.speedtrail.com.br. Pra usar seu próprio domínio:

1. Na aba Rede da aplicação, seção Domínio próprio, digite o hostname (ex.: app.suaempresa.com) e clique em Adicionar.

2. Configure o DNS no seu provedor (Cloudflare, Registro.br, etc.):

• Subdomínio (ex.: app.empresa.com) pede um CNAME:

CNAME  app.empresa.com  →  cname.speedtrail.com.br

• Domínio raiz / apex (ex.: empresa.com) pede um A record:

A  empresa.com  →  45.234.95.183
No Cloudflare funciona com DNS only (nuvem cinza) ou proxied (laranja).

3. Clique em Verificar DNS. Se o registro está correto, o domínio passa pra Aguardando certificado.

4. O certificado HTTPS (Let's Encrypt) é emitido automaticamente no primeiro acesso. Quando ativo, o status vira Ativo.

Limite atual: 1 domínio próprio por aplicação. O subdomínio da plataforma continua funcionando em paralelo.

Backups e restauração

Todo dia às 00:30 (horário de Brasília) a plataforma copia seus dados e guarda a cópia por sete dias, fora do servidor onde a aplicação roda. Está incluso em todos os planos: não há adicional a contratar.

• Banco de dados: dump lógico, no formato nativo de cada motor: .dump no PostgreSQL, .sql.gz no MySQL/MariaDB e .archive.gz no MongoDB. Abre em qualquer instalação daquele banco, inclusive na sua máquina.

• Volume persistente: um .tar.gz com o conteúdo do disco da aplicação, para quem grava arquivo (sessão, upload, arquivo gerado).

As cópias ficam na aba Backups da aplicação. O download sai por link temporário de cinco minutos, direto do armazenamento, sem o arquivo passar pela plataforma.

Restaurar um banco você faz pelo próprio painel, sem abrir chamado. Antes de sobrescrever qualquer coisa, a plataforma tira uma cópia do estado atual e deixa na mesma lista, marcada como pre-restauracao-…. Se a restauração for a errada, o caminho de volta está lá. A cópia de volume não restaura pelo painel: baixe e extraia onde quiser conferir antes.

tar -xzf volume-....tar.gz -C ./conteudo
A cópia do volume é feita com a aplicação no ar, sem congelar o disco: um arquivo que esteja sendo escrito no instante exato da cópia pode sair incompleto. Para dado que não admite isso, use um banco de dados: o dump dele é consistente.

Restrição de acesso

Por padrão sua aplicação responde a qualquer pessoa na internet. Na aba Rede, em Restrição por IP, você lista quem pode alcançá-la, uma faixa por linha, aceitando IP solto ou CIDR, IPv4 e IPv6:

203.0.113.4
198.51.100.0/24

• Caixa vazia mantém a aplicação aberta, como sempre foi.

• Vale para todos os endereços da aplicação: o da plataforma e os domínios próprios. Fechar um e deixar o outro aberto seria porta trancada ao lado de porta aberta.

• Entra em vigor na hora, sem novo deploy: quem fecha o acesso espera que feche agora.

Atenção se o seu domínio estiver atrás de CDN em modo proxy (Cloudflare com a nuvem laranja, por exemplo): quem chega até nós é a CDN, não o visitante. Nesse caso a lista precisa conter as faixas dela, ou o site sai do ar para todo mundo.

Conectar sua IA

A SpeedTrail fala MCP, o protocolo que dá ferramentas a uma IA. Conectando, ela passa a enxergar seus projetos e a agir dentro do que você permitir. O uso mais comum é pedir que ela leia os logs de uma publicação que falhou e explique o motivo.

No painel, em Conectar IA, você gera um token e marca o que aquela IA pode fazer. O token carrega escopos, e é por eles que você decide o alcance dela. Os dois primeiros vêm marcados; os outros três não:

• Leitura: projetos, aplicações, status, publicações, logs e custos. Lista as chaves das variáveis de ambiente, mas com o valor mascarado.

• Publicar: dispara uma publicação e aplica configuração em serviço já existente.

• Segredos: mostra o valor das variáveis de ambiente. Pense duas vezes: o valor passa para a IA e fica no histórico dela, que não é seu.

• Escrita: cria aplicação e banco, escreve variáveis e altera CPU, memória e réplicas. Pode gerar custo.

• Apagar: remove aplicação, banco ou variável. Não tem desfazer.

Apagar exige um passo a mais: a primeira chamada da IA devolve o que seria apagado sem apagar nada, e ela precisa confirmar numa segunda chamada. É o degrau que o diálogo do painel tem e que, sem isso, não existiria pelo MCP.

Onde colar o token

O endereço é sempre https://api.speedtrail.com.br/mcp, e a credencial é o cabeçalho Authorization: Bearer SEU_TOKEN. O que muda de um cliente para outro é onde isso fica guardado:

Claude Code

Um comando no terminal, dentro do projeto:

claude mcp add --transport http speedtrail https://api.speedtrail.com.br/mcp \
  --header "Authorization: Bearer SEU_TOKEN"
claude mcp list diz se conectou. Assim o servidor vale no projeto atual; com --scope user no fim do comando, vale em todos.
Claude no app e no site

Nas configurações do Claude, em Connectors, clique em Add custom connector. Dê um nome e use a URL https://api.speedtrail.com.br/mcp. Em Authentication, escolha No sign-in; em Request headers, ponha o nome authorization com o valor Bearer SEU_TOKEN. O Bearer e o espaço fazem parte do valor.

O campo de cabeçalhos está em beta e ainda não aparece em toda conta. Se o seu Claude não mostrar Request headers, conecte pelo Claude Code ou pela ponte do último item.
Cursor

Crie o arquivo ~/.cursor/mcp.json, que vale em todos os projetos, ou .cursor/mcp.json, que vale só neste:

{
  "mcpServers": {
    "speedtrail": {
      "url": "https://api.speedtrail.com.br/mcp",
      "headers": { "Authorization": "Bearer SEU_TOKEN" }
    }
  }
}
Se a SpeedTrail não aparecer na lista de servidores MCP, feche e abra o Cursor.
VS Code com Copilot

No arquivo .vscode/mcp.json do projeto:

{
  "inputs": [
    {
      "id": "speedtrail-token",
      "type": "promptString",
      "description": "Token MCP da SpeedTrail",
      "password": true
    }
  ],
  "servers": {
    "speedtrail": {
      "type": "http",
      "url": "https://api.speedtrail.com.br/mcp",
      "headers": { "Authorization": "Bearer ${input:speedtrail-token}" }
    }
  }
}
O token não fica escrito no arquivo: o VS Code pergunta na primeira vez que sobe o servidor. Dá pra versionar esse arquivo no repositório sem vazar nada.
ChatGPT

Ainda não dá. O formulário de conector personalizado aceita OAuth ou servidor sem autenticação, e não tem campo pra token fixo; o nosso endpoint exige o token, então a conexão não fecha. Quando houver login por OAuth aqui, o ChatGPT entra nesta lista.

Outros clientes

Windsurf, Zed, Gemini CLI e afins: se o cliente aceita servidor remoto com cabeçalho, use o mesmo JSON do Cursor. Se ele só fala com servidor local, a ponte mcp-remote resolve:

{
  "mcpServers": {
    "speedtrail": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.speedtrail.com.br/mcp",
        "--header",
        "Authorization:${AUTH}"
      ],
      "env": { "AUTH": "Bearer SEU_TOKEN" }
    }
  }
}
O Authorization: vai sem espaço depois dos dois-pontos de propósito: alguns clientes cortam o argumento no espaço antes de chamar o npx. O espaço fica dentro da variável de ambiente, onde ninguém mexe.

Se não conectar, teste o token direto antes de brigar com a configuração do cliente:

curl -X POST https://api.speedtrail.com.br/mcp \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
Com o token certo, volta a lista de ferramentas que ele enxerga. Com o token errado, volta Token ausente ou inválido. Os dois tipos no Accept são exigência do protocolo: sem eles, a resposta é 406.O token age como você, sem senha e sem segundo fator: trate como senha e revogue se vazar. Ele aparece uma única vez, na hora de gerar. Você pode ter vários, um por IA, e revogar qualquer um a qualquer momento na mesma tela, onde também vê quando cada um foi usado pela última vez. O limite é de 120 chamadas por minuto por token.

API para sistemas

Um sistema seu pode criar, configurar e publicar aplicações na SpeedTrail pela API, sem navegador e sem senha. O caso típico é um produto que sobe uma instância por cliente: o backend dele cria a aplicação, espera o deploy terminar e segue.

No painel, em Tokens de API, você gera um token stapi_ e escolhe três coisas:

• Projeto: preso a um projeto, o token não enxerga os outros. Prenda sempre que puder.

• Escopos: leitura (sempre incluída), escrita, deploy, segredos (ler o valor das variáveis) e destrutivo (apagar). Os mesmos do token de IA, com outro prefixo.

• Validade: de 1 a 365 dias. Não existe token sem validade.

O token vai no cabeçalho Authorization: Bearer stapi_.... Ele vale para projetos e aplicações e não vale para conta, cobrança, plano, administração nem para criar ou revogar tokens: isso continua exigindo login no painel. O limite é de 120 chamadas por minuto por token, e a resposta traz X-RateLimit-Remaining.

Criar já configurada, numa chamada

A criação aceita, além de nome e repositório, a porta, os comandos, a rede privada, o endereço público, o prefixo, a restrição por IP e as variáveis em texto .env. Com deploy: true o primeiro deploy sai junto (exige o escopo deploy). Se alguma regra recusar, nada é criado.

curl -X POST https://api.speedtrail.com.br/api/v1/projects/12/applications \
  -H "Authorization: Bearer stapi_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "api-fortaleza",
    "slug": "api-fortaleza",
    "serviceCategory": "github_app",
    "serviceKind": "github_repository",
    "githubRepoFullName": "empresa/api",
    "branch": "main",
    "containerPort": 3333,
    "startCommand": "node build/bin/server.js",
    "preDeployCommand": "node build/ace.js migration:run --force",
    "publicRouteEnabled": false,
    "env": "DB_HOST=db\nDB_DATABASE=fortaleza",
    "deploy": true
  }'

A resposta é 201 com a aplicação em data, avisos em avisos e, quando pediu deploy, deployment com deploymentId. Se o deploy não puder sair (porta faltando, repositório sem acesso), a aplicação continua criada e o motivo vem em deployment.message. O slug informado é exato: ocupado vira erro, em vez de ganhar um sufixo, porque é por ele que as outras aplicações chegam nesta.

Sem endereço público

Com publicRouteEnabled: false a aplicação não ganha URL nem certificado: fica só na rede privada do ambiente, e as outras aplicações do mesmo ambiente a alcançam pelo slug e pela porta interna, como http://api-fortaleza:3333. A rede privada liga junto, e domínio próprio é recusado. É o arranjo de uma API que só o front chama: o front fica público, com o proxy dele encaminhando /api para o endereço interno. A mesma opção existe na aba Rede do painel.

Acompanhar o deploy

Não há aviso de fim de deploy: consulte as publicações a cada 10 ou 15 segundos até o status sair de queued ou running para succeeded ou failed. Em falha, os logs dizem o motivo.

curl https://api.speedtrail.com.br/api/v1/projects/12/applications/345/deployments \
  -H "Authorization: Bearer stapi_..."

curl https://api.speedtrail.com.br/api/v1/projects/12/applications/345/deployments/678/logs \
  -H "Authorization: Bearer stapi_..."

Principais endpoints

Base https://api.speedtrail.com.br/api/v1. Na tabela, {app} é /projects/:projectId/applications/:applicationId.

GET/projectsleituraProjetos que o token enxerga
GET/projects/:projectId/environmentsleituraAmbientes do projeto
POST/projects/:projectId/applicationsescritaCria a aplicação já configurada
GET{app}leituraDetalhe da aplicação
PATCH{app}escritaAltera porta, comandos, rede, prefixo, IPs
PUT{app}/environment-variables/bulkescritaTroca as variáveis por um texto .env
GET{app}/environment-variablessegredosVariáveis com os valores
POST{app}/deploymentsdeployDispara uma publicação
GET{app}/deploymentsleituraPublicações e o status de cada uma
GET{app}/deployments/:deploymentId/logsleituraLogs de build e de deploy
POST{app}/custom-domainsescritaAdiciona domínio próprio
DELETE{app}destrutivoApaga a aplicação

As respostas seguem o formato { success, data, message }. Os erros:

• 401: token ausente, inválido, vencido ou revogado.

• 403: rota fora do alcance do token, escopo faltando ou projeto diferente do vinculado. A mensagem diz qual dos três.

• 422: campo com formato inválido, detalhado em data.

• 400: regra de negócio, como prefixo já em uso, limite do plano ou slug ocupado.

• 429: passou de 120 chamadas no minuto. Espere o que diz o Retry-After.

O token age como você dentro do que os escopos permitem: trate como senha e revogue se vazar. Ele aparece uma única vez, na hora de gerar, e a tela mostra quando cada um foi usado pela última vez.

Planos e limites

Conta nova começa no plano Free. Pra mais aplicações, bancos ou domínio próprio, escolha um plano pago:

Free
1 app · 0 db · sem domínio próprio
Hobby
3 apps · 1 db · domínio próprio
Pro
10 apps · 3 dbs · domínio próprio

Fatura em atraso

Atraso não apaga nada. Passado o prazo, as aplicações da conta podem ser suspensas: elas param e as rotinas agendadas ficam pausadas, enquanto bancos, volumes, domínios, variáveis e backups continuam exatamente onde estão. Publicar fica bloqueado enquanto a conta estiver suspensa, inclusive por push no GitHub.

Antes disso você recebe aviso por e-mail, e o painel mostra o valor em aberto com o link de pagamento. Assim que a fatura é paga, a conta volta sozinha, com as mesmas réplicas do seu plano, sem precisar publicar de novo nem falar com o suporte.

Suspender não é apagar: nenhum dado é removido por atraso de pagamento. Se precisar de prazo, fale com a gente pelo atendimento do painel antes do vencimento.