Servidor

O comando dropstone serve executa um servidor HTTP headless que expõe um endpoint OpenAPI que um cliente Dropstone pode usar.

Uso

dropstone serve [--port <number>] [--hostname <string>] [--cors <origin>]

Opções

--cors pode ser passado várias vezes:

dropstone serve --cors http://localhost:5173 --cors https://app.example.com

Autenticação

Defina DROPSTONE_SERVER_PASSWORD para proteger o servidor com autenticação básica HTTP. O nome de usuário padrão é dropstone, ou defina DROPSTONE_SERVER_USERNAME para substituí-lo. Isso se aplica tanto a dropstone serve quanto a dropstone web.

DROPSTONE_SERVER_PASSWORD=sua-senha dropstone serve

Credenciais do agente

DROPSTONE_SERVER_PASSWORD protege o próprio servidor. Ele não informa ao agente como alcançar o Dropstone. Em uma máquina não supervisionada, não há uma conta conectada para herdar, então passe uma chave de API através da configuração do provedor:

{
  "provider": {
    "dropstone": {
      "options": {
        "apiKey": "dsk_live_...",
        "baseURL": "https://api.dropstone.io/api/v1"
      }
    }
  }
}

baseURL é importante. As chaves de API são aceitas em /api/v1, não em /v1, e uma chave enviada para /v1 é rejeitada com 403 Invalid token format. Please log in again. Defina isso aqui em vez de usar DROPSTONE_BASE_URL, que também é usado para construir os endpoints de conta, uso e memória e os quebrará se você apontá-lo para um caminho versionado.

Gere uma chave em dropstone.io/dashboard/settings.

Enviando um prompt

POST /session/:id/message requer tanto agent quanto model. Omitir model não resolve nenhum padrão: o turno retorna 200 com um corpo vazio e nada é executado.

curl -X POST "http://127.0.0.1:4096/session/$SID/message?directory=$PWD" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "build",
    "model": { "providerID": "dropstone", "modelID": "dropstone-pro" },
    "parts": [{ "type": "text", "text": "Adicione tratamento de erros a src/index.ts" }]
  }'

Um turno que falha ainda retorna 200. O motivo está em data.info.error, não no nível de transporte, então verifique esse campo em vez de confiar no código de status.

Como funciona

dropstone serve expõe os recursos do Dropstone através de um endpoint HTTP OpenAPI 3.1. O mesmo endpoint é usado para gerar o SDK.

Use o servidor quando quiser controlar o Dropstone programaticamente: a partir de um script, um pipeline de CI ou uma integração própria. A sessão interativa e o servidor são independentes. Executar dropstone serve inicia um novo servidor autônomo, independentemente de você ter uma sessão interativa aberta.

Você pode substituir o endereço de bind com as bandeiras --hostname e --port.

Spec

O servidor publica uma spec OpenAPI 3.1 que pode ser visualizada em:

http://<hostname>:<port>/doc

Por exemplo, http://localhost:4096/doc. Use a spec para gerar clientes ou inspecionar tipos de solicitação e resposta. Ou visualize-a em um explorador Swagger.

APIs

O servidor dropstone expõe as seguintes APIs.

Global

Projeto

Caminho e VCS

Config

Sessões

Mensagens

Comandos

Arquivos

Parâmetros de consulta de /find/file

• query (obrigatório): string de pesquisa (correspondência difusa)
• type (opcional): limitar resultados a "file" ou "directory"
• directory (opcional): substituir a raiz do projeto para a pesquisa
• limit (opcional): máximo de resultados (1–200)
• dirs (opcional): bandeira legada ("false" retorna apenas arquivos)

LSP, Formatadores e MCP

Agentes

Registro

Autenticação

Eventos

Documentos