Interaja com o servidor dropstone via HTTP.
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
| Flag | Descrição | Padrão |
|---|
--port | Porta para escutar | 4096 |
--hostname | Nome do host para escutar | 127.0.0.1 |
--mdns | Ativar descoberta mDNS | false |
--mdns-domain | Nome de domínio customizado para mDNS | dropstone.local |
--cors | Origens de navegador adicionais permitidas | [] |
--cors pode ser passado múltiplas 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 HTTP básica. O nome de usuário padrão é dropstone, ou defina DROPSTONE_SERVER_USERNAME para sobrescrevê-lo. Isso se aplica tanto a dropstone serve quanto a dropstone web.
DROPSTONE_SERVER_PASSWORD=your-password dropstone serve
Como funciona
dropstone serve expõe as capacidades do Dropstone por um endpoint HTTP OpenAPI 3.1. O mesmo endpoint é usado para gerar o SDK.
Use o servidor quando quiser dirigir o Dropstone programaticamente: a partir de um script, um pipeline de CI, ou uma integração sua. A sessão interativa e o servidor são independentes. Executar dropstone serve inicia um servidor standalone novo, independentemente de você ter uma sessão interativa aberta.
Você pode sobrescrever o endereço de bind com as flags --hostname e --port flags.
Especificação
O servidor publica uma especificação OpenAPI 3.1 que pode ser visualizada em:
http://<hostname>:<port>/doc
Por exemplo, http://localhost:4096/doc. Use a especificação para gerar clientes ou inspecionar tipos de requisição e resposta. Ou visualize-a em um explorador Swagger.
APIs
O servidor dropstone expõe as seguintes APIs.
Global
| Método | Caminho | Descrição | Resposta |
|---|
GET | /global/health | Obter saúde e versão do servidor | { healthy: true, version: string } |
GET | /global/event | Obter eventos globais (fluxo SSE) | Fluxo de eventos |
Projeto
| Método | Caminho | Descrição | Resposta |
|---|
GET | /project | Listar todos os projetos | Project[] |
GET | /project/current | Obter o projeto atual | Project |
Caminho & VCS
| Método | Caminho | Descrição | Resposta |
|---|
GET | /path | Obter o caminho atual | Path |
GET | /vcs | Obter informações de VCS do projeto atual | VcsInfo |
Config
| Método | Caminho | Descrição | Resposta |
|---|
GET | /config | Obter informações de config | Config |
PATCH | /config | Atualizar config | Config |
Sessões
| Método | Caminho | Descrição | Notas |
|---|
GET | /session | Listar todas as sessões | Retorna Session[] |
POST | /session | Criar uma nova sessão | corpo: { parentID?, title? }, retorna Session |
GET | /session/status | Obter status da sessão para todas as sessões | Retorna { [sessionID: string]: SessionStatus } |
GET | /session/:id | Obter detalhes da sessão | Retorna Session |
DELETE | /session/:id | Deletar uma sessão e todos seus dados | Retorna boolean |
PATCH | /session/:id | Atualizar propriedades da sessão | corpo: { title? }, retorna Session |
GET | /session/:id/children | Obter sessões filhas de uma sessão | Retorna Session[] |
GET | /session/:id/todo | Obter a lista de tarefas de uma sessão | Retorna Todo[] |
POST | /session/:id/init | Analisar app e criar AGENTS.md | corpo: { messageID, providerID, modelID }, retorna boolean |
POST | /session/:id/fork | Fazer fork de uma sessão existente em uma mensagem | corpo: { messageID? }, retorna Session |
POST | /session/:id/abort | Abortar uma sessão em execução | Retorna boolean |
GET | /session/:id/diff | Obter o diff desta sessão | query: messageID?, retorna FileDiff[] |
POST | /session/:id/summarize | Resumir a sessão | corpo: { providerID, modelID }, retorna boolean |
POST | /session/:id/revert | Reverter uma mensagem | corpo: { messageID, partID? }, retorna boolean |
POST | /session/:id/unrevert | Restaurar todas as mensagens revertidas | Retorna boolean |
POST | /session/:id/permissions/:permissionID | Responder a uma solicitação de permissão | corpo: { response, remember? }, retorna boolean |
Mensagens
| Método | Caminho | Descrição | Notas |
|---|
GET | /session/:id/message | Listar mensagens em uma sessão | query: limit?, retorna { info: Message, parts: Part[]}[] |
POST | /session/:id/message | Enviar uma mensagem e aguardar resposta | corpo: { messageID?, model?, agent?, noReply?, system?, tools?, parts }, retorna { info: Message, parts: Part[]} |
GET | /session/:id/message/:messageID | Obter detalhes da mensagem | Retorna { info: Message, parts: Part[]} |
POST | /session/:id/prompt_async | Enviar uma mensagem assincronamente (sem aguardar) | corpo: igual a /session/:id/message, retorna 204 No Content |
POST | /session/:id/command | Executar um comando slash | corpo: { messageID?, agent?, model?, command, arguments }, retorna { info: Message, parts: Part[]} |
POST | /session/:id/shell | Executar um comando shell | corpo: { agent, model?, command }, retorna { info: Message, parts: Part[]} |
Comandos
| Método | Caminho | Descrição | Resposta |
|---|
GET | /command | Listar todos os comandos | Command[] |
Arquivos
| Método | Caminho | Descrição | Resposta |
|---|
GET | /find?pattern=<pat> | Procurar texto em arquivos | Array de objetos de correspondência com path, lines, line_number, absolute_offset, submatches |
GET | /find/file?query=<q> | Encontrar arquivos e diretórios por nome | string[] (caminhos) |
GET | /find/symbol?query=<q> | Encontrar símbolos do workspace | Symbol[] |
GET | /file?path=<path> | Listar arquivos e diretórios | FileNode[] |
GET | /file/content?path=<p> | Ler um arquivo | FileContent |
GET | /file/status | Obter status para arquivos rastreados | File[] |
Parâmetros de query /find/file
query (obrigatório): string de busca (correspondência difusa)type (opcional): limitar resultados a "file" ou "directory"directory (opcional): sobrescrever a raiz do projeto para a buscalimit (opcional): máximo de resultados (1–200)dirs (opcional): flag legada ("false" retorna apenas arquivos)
| Método | Caminho | Descrição | Resposta |
|---|
GET | /lsp | Obter status do servidor LSP | LSPStatus[] |
GET | /formatter | Obter status do formatador | FormatterStatus[] |
GET | /mcp | Obter status do servidor MCP | { [name: string]: MCPStatus } |
POST | /mcp | Adicionar servidor MCP dinamicamente | corpo: { name, config }, retorna objeto de status MCP |
Agentes
| Método | Caminho | Descrição | Resposta |
|---|
GET | /agent | Listar todos os agentes disponíveis | Agent[] |
Logging
| Método | Caminho | Descrição | Resposta |
|---|
POST | /log | Escrever entrada de log. Corpo: { service, level, message, extra? } | boolean |
Auth
| Método | Caminho | Descrição | Resposta |
|---|
PUT | /auth/:id | Definir credenciais de autenticação para o alvo fornecido. | boolean |
Eventos
| Método | Caminho | Descrição | Resposta |
|---|
GET | /event | Fluxo de eventos enviados pelo servidor. Primeiro evento é server.connected, depois eventos do barramento | Fluxo de eventos enviados pelo servidor |
Docs
| Método | Caminho | Descrição | Resposta |
|---|
GET | /doc | Especificação OpenAPI 3.1 | Página HTML com especificação OpenAPI |