Server

The dropstone serve command runs a headless HTTP server that exposes an OpenAPI endpoint a Dropstone client can use.

Usage

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

Options

--cors can be passed multiple times:

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

Authentication

Set DROPSTONE_SERVER_PASSWORD to protect the server with HTTP basic auth. The username defaults to dropstone, or set DROPSTONE_SERVER_USERNAME to override it. This applies to both dropstone serve and dropstone web.

DROPSTONE_SERVER_PASSWORD=your-password dropstone serve

Agent credentials

DROPSTONE_SERVER_PASSWORD protects the server itself. It does not tell the agent how to reach Dropstone. On an unattended machine there is no signed-in account to inherit, so pass an API key through the provider config:

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

baseURL matters. API keys are accepted at /api/v1, not at /v1, and a key sent to /v1 is rejected with 403 Invalid token format. Please log in again. Set it here rather than through DROPSTONE_BASE_URL, which is also used to build the account, usage, and memory endpoints and will break them if you point it at a versioned path.

Generate a key at dropstone.io/dashboard/settings.

Sending a prompt

POST /session/:id/message requires both agent and model. Omitting model resolves no default: the turn returns 200 with an empty body and nothing runs.

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" }]
  }'

A turn that fails still returns 200. The reason is at data.info.error, not at the transport level, so check that field rather than relying on the status code.

How it works

dropstone serve exposes Dropstone's capabilities over an OpenAPI 3.1 HTTP endpoint. The same endpoint is used to generate the SDK.

Use the server when you want to drive Dropstone programmatically: from a script, a CI pipeline, or an integration of your own. The interactive session and the server are independent. Running dropstone serve starts a fresh standalone server regardless of whether you have an interactive session open.

You can override the bind address with the --hostname and --port flags.

Spec

The server publishes an OpenAPI 3.1 spec that can be viewed at:

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

For example, http://localhost:4096/doc. Use the spec to generate clients or inspect request and response types. Or view it in a Swagger explorer.

APIs

The dropstone server exposes the following APIs.

Global

Project

Path & VCS

Config

Sessions

Messages

Commands

Files

/find/file query parameters

• query (required): search string (fuzzy match)
• type (optional): limit results to "file" or "directory"
• directory (optional): override the project root for the search
• limit (optional): max results (1–200)
• dirs (optional): legacy flag ("false" returns only files)

LSP, Formatters & MCP

Agents

Logging

Auth

Events

Docs