Dropstone CLI

서버

HTTP를 통해 Dropstone 서버와 상호작용합니다.

dropstone serve 명령어는 Dropstone 클라이언트가 사용할 수 있는 OpenAPI 엔드포인트를 노출하는 헤드리스 HTTP 서버를 실행합니다.

사용법

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

옵션

플래그설명기본값
--port수신 대기할 포트4096
--hostname수신 대기할 호스트명127.0.0.1
--mdnsmDNS 검색 활성화false
--mdns-domainmDNS 서비스용 사용자 지정 도메인 이름dropstone.local
--cors허용할 추가 브라우저 출처[]

--cors는 여러 번 전달할 수 있습니다:

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

인증

DROPSTONE_SERVER_PASSWORD를 설정하여 HTTP 기본 인증으로 서버를 보호하세요. 사용자 이름은 기본적으로 dropstone이며, DROPSTONE_SERVER_USERNAME으로 재정의할 수 있습니다. 이는 dropstone serve와 dropstone web 모두에 적용됩니다.

DROPSTONE_SERVER_PASSWORD=your-password dropstone serve

에이전트 자격 증명

DROPSTONE_SERVER_PASSWORD는 서버 자체를 보호합니다. 에이전트에게 Dropstone에 연결하는 방법을 알려주지는 않습니다. 무인 머신에는 상속할 로그인 계정이 없으므로 공급자 구성에 API 키를 전달하세요:

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

baseURL이 중요합니다. API 키는 /v1이 아닌 /api/v1에서 허용되며, /v1로 보낸 키는 403 Invalid token format. Please log in again. 오류와 함께 거부됩니다. 계정, 사용량, 메모리 엔드포인트를 구성하는 데에도 사용되는 DROPSTONE_BASE_URL 대신 여기에서 설정하세요. 버전이 지정된 경로로 지정하면 해당 엔드포인트가 손상됩니다.

키는 dropstone.io/dashboard/settings에서 생성하세요.

Note

기본 build 에이전트는 모든 도구 호출 전에 질문을 합니다. 여기서는 해당 프롬프트에 응답할 수 있는 것이 없으므로 요청은 실패하지 않고 대기 상태로 유지됩니다. "agent": "accept all"을 보내거나 명시적 권한 허용 목록을 설정하세요. 권한을 참조하세요.

프롬프트 보내기

POST /session/:id/message는 agent와 model이 모두 필요합니다. model을 생략하면 기본값이 결정되지 않습니다: 턴은 빈 본문과 함께 200을 반환하고 아무것도 실행되지 않습니다.

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

실패한 턴도 여전히 200을 반환합니다. 이유는 전송 계층이 아닌 data.info.error에 있으므로 상태 코드에 의존하지 말고 해당 필드를 확인하세요.

작동 방식

dropstone serve는 OpenAPI 3.1 HTTP 엔드포인트를 통해 Dropstone의 기능을 노출합니다. 동일한 엔드포인트가 SDK를 생성하는 데 사용됩니다.

스크립트, CI 파이프라인 또는 자체 통합에서 Dropstone을 프로그래밍 방식으로 구동하려면 서버를 사용하세요. 대화형 세션과 서버는 독립적입니다. dropstone serve를 실행하면 대화형 세션이 열려 있는지 여부와 관계없이 새로운 독립형 서버가 시작됩니다.

--hostname 및 --port 플래그로 바인드 주소를 재정의할 수 있습니다.

스펙

서버는 다음에서 볼 수 있는 OpenAPI 3.1 스펙을 게시합니다:

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

예: http://localhost:4096/doc. 스펙을 사용하여 클라이언트를 생성하거나 요청 및 응답 유형을 검사하세요. 또는 Swagger 탐색기에서 볼 수 있습니다.

API

Dropstone 서버는 다음 API를 노출합니다.

전역

메서드경로설명응답
GET/global/health서버 상태 및 버전 가져오기{ healthy: true, version: string }
GET/global/event전역 이벤트 가져오기 (SSE 스트림)이벤트 스트림

프로젝트

메서드경로설명응답
GET/project모든 프로젝트 나열Project[]
GET/project/current현재 프로젝트 가져오기Project

경로 및 VCS

메서드경로설명응답
GET/path현재 경로 가져오기Path
GET/vcs현재 프로젝트의 VCS 정보 가져오기VcsInfo

구성

메서드경로설명응답
GET/config구성 정보 가져오기Config
PATCH/config구성 업데이트Config

세션

메서드경로설명참고
GET/session모든 세션 나열Session[] 반환
POST/session새 세션 생성본문: { parentID?, title? }, Session 반환
GET/session/status모든 세션의 상태 가져오기{ [sessionID: string]: SessionStatus } 반환
GET/session/:id세션 세부 정보 가져오기Session 반환
DELETE/session/:id세션 및 모든 데이터 삭제boolean 반환
PATCH/session/:id세션 속성 업데이트본문: { title? }, Session 반환
GET/session/:id/children세션의 하위 세션 가져오기Session[] 반환
GET/session/:id/todo세션의 할 일 목록 가져오기Todo[] 반환
POST/session/:id/init앱 분석 및 AGENTS.md 생성본문: { messageID, providerID, modelID }, boolean 반환
POST/session/:id/fork메시지에서 기존 세션 포크본문: { messageID? }, Session 반환
POST/session/:id/abort실행 중인 세션 중단boolean 반환
GET/session/:id/diff이 세션의 diff 가져오기쿼리: messageID?, FileDiff[] 반환
POST/session/:id/summarize세션 요약본문: { providerID, modelID }, boolean 반환
POST/session/:id/revert메시지 되돌리기본문: { messageID, partID? }, boolean 반환
POST/session/:id/unrevert되돌린 모든 메시지 복원boolean 반환
POST/session/:id/permissions/:permissionID권한 요청에 응답본문: { response, remember? }, boolean 반환

메시지

메서드경로설명참고
GET/session/:id/message세션의 메시지 나열쿼리: limit?, { info: Message, parts: Part[]}[] 반환
POST/session/:id/message메시지 보내기 및 응답 대기본문: { messageID?, model?, agent?, noReply?, system?, tools?, parts }, { info: Message, parts: Part[]} 반환
GET/session/:id/message/:messageID메시지 세부 정보 가져오기{ info: Message, parts: Part[]} 반환
POST/session/:id/prompt_async메시지 비동기 전송 (대기 없음)본문: /session/:id/message와 동일, 204 No Content 반환
POST/session/:id/command슬래시 명령어 실행본문: { messageID?, agent?, model?, command, arguments }, { info: Message, parts: Part[]} 반환
POST/session/:id/shell셸 명령어 실행본문: { agent, model?, command }, { info: Message, parts: Part[]} 반환

명령어

메서드경로설명응답
GET/command모든 명령어 나열Command[]

파일

메서드경로설명응답
GET/find?pattern=<pat>파일에서 텍스트 검색path, lines, line_number, absolute_offset, submatches가 포함된 일치 객체 배열
GET/find/file?query=<q>이름으로 파일 및 디렉터리 찾기string[] (경로)
GET/find/symbol?query=<q>작업공간 기호 찾기Symbol[]
GET/file?path=<path>파일 및 디렉터리 나열FileNode[]
GET/file/content?path=<p>파일 읽기FileContent
GET/file/status추적된 파일의 상태 가져오기File[]

/find/file 쿼리 매개변수

  • query (필수): 검색 문자열 (퍼지 매칭)
  • type (선택): 결과를 "file" 또는 "directory"로 제한
  • directory (선택): 검색의 프로젝트 루트 재정의
  • limit (선택): 최대 결과 수 (1–200)
  • dirs (선택): 레거시 플래그 ("false"는 파일만 반환)

LSP, 포매터 및 MCP

메서드경로설명응답
GET/lspLSP 서버 상태 가져오기LSPStatus[]
GET/formatter포매터 상태 가져오기FormatterStatus[]
GET/mcpMCP 서버 상태 가져오기{ [name: string]: MCPStatus }
POST/mcpMCP 서버 동적 추가본문: { name, config }, MCP 상태 객체 반환

에이전트

메서드경로설명응답
GET/agent사용 가능한 모든 에이전트 나열Agent[]

로깅

메서드경로설명응답
POST/log로그 항목 작성. 본문: { service, level, message, extra? }boolean

인증

메서드경로설명응답
PUT/auth/:id지정된 대상에 대한 인증 자격 증명 설정.boolean

이벤트

메서드경로설명응답
GET/event서버 전송 이벤트 스트림. 첫 번째 이벤트는 server.connected, 그 다음은 버스 이벤트서버 전송 이벤트 스트림

문서

메서드경로설명응답
GET/docOpenAPI 3.1 스펙OpenAPI 스펙이 포함된 HTML 페이지
Ctrl+I