Servidor

El comando dropstone serve ejecuta un servidor HTTP sin interfaz gráfica que expone un endpoint OpenAPI que un cliente de Dropstone puede utilizar.

Uso

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

Opciones

--cors se puede pasar varias veces:

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

Autenticación

Establece DROPSTONE_SERVER_PASSWORD para proteger el servidor con autenticación básica HTTP. El nombre de usuario por defecto es dropstone, o establece DROPSTONE_SERVER_USERNAME para cambiarlo. Esto se aplica tanto a dropstone serve como a dropstone web.

DROPSTONE_SERVER_PASSWORD=tu-contraseña dropstone serve

Credenciales del agente

DROPSTONE_SERVER_PASSWORD protege el servidor en sí. No le indica al agente cómo conectarse a Dropstone. En una máquina desatendida no hay una cuenta iniciada de la que heredar, así que pasa una clave de API a través de la configuración del proveedor:

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

baseURL es importante. Las claves de API se aceptan en /api/v1, no en /v1, y una clave enviada a /v1 se rechaza con 403 Invalid token format. Please log in again. Establécelo aquí en lugar de a través de DROPSTONE_BASE_URL, que también se usa para construir los endpoints de cuenta, uso y memoria, y los romperá si lo apuntas a una ruta con versión.

Genera una clave en dropstone.io/dashboard/settings.

Enviar una solicitud

POST /session/:id/message requiere tanto agent como model. Si se omite model, no se resuelve ningún valor por defecto: el turno devuelve 200 con un cuerpo vacío y no se ejecuta nada.

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": "Add error handling to src/index.ts" }]
  }'

Un turno que falla aún devuelve 200. El motivo está en data.info.error, no a nivel de transporte, así que revisa ese campo en lugar de confiar en el código de estado.

Cómo funciona

dropstone serve expone las capacidades de Dropstone a través de un endpoint HTTP OpenAPI 3.1. El mismo endpoint se usa para generar el SDK.

Usa el servidor cuando quieras controlar Dropstone programáticamente: desde un script, una canalización de CI o una integración propia. La sesión interactiva y el servidor son independientes. Ejecutar dropstone serve inicia un servidor independiente nuevo, sin importar si tienes una sesión interactiva abierta.

Puedes cambiar la dirección de enlace con las banderas --hostname y --port.

Especificación

El servidor publica una especificación OpenAPI 3.1 que se puede ver en:

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

Por ejemplo, http://localhost:4096/doc. Usa la especificación para generar clientes o inspeccionar los tipos de solicitud y respuesta. O mírala en un explorador de Swagger.

APIs

El servidor de Dropstone expone las siguientes APIs.

Global

Proyecto

Ruta y VCS

Configuración

Sesiones

Mensajes

Comandos

Archivos

Parámetros de consulta de /find/file

• query (obligatorio): cadena de búsqueda (coincidencia difusa)
• type (opcional): limitar resultados a "file" o "directory"
• directory (opcional): anular la raíz del proyecto para la búsqueda
• limit (opcional): máximo de resultados (1–200)
• dirs (opcional): bandera heredada ("false" devuelve solo archivos)

LSP, Formateadores y MCP

Agentes

Registro

Autenticación

Eventos

Documentación