Sprocket 소개: 하드웨어 및 소프트웨어 개발을 위한 최고의 AI 에이전트

목표: 하드웨어와 소프트웨어를 개발하는 세계 최고의 플랫폼을 만드는 것입니다.

Sprocket이 특별한 점은 다음과 같습니다:

• 하드웨어와 소프트웨어 모두에서 작업할 수 있는 유일한 AI 에이전트입니다.
• 모든 작업을 수행할 때 웹에서 최고 수준의 컨텍스트를 검색하여 매우 신뢰성이 높게 유지됩니다.
• 요청하면 하드웨어 부품부터 SaaS 구독까지 모든 것을 어떤 웹사이트에서든 구매합니다.
• 아름답고 상세한 회로도(schematics)를 만들고, BOM(Bill of Materials)을 생성하며, 조립 설명서를 작성합니다.

참고

아래 정의된 방법 중 어느 것으로든 Sprocket을 실행할 수 있으며, 이는 Sprocket의 기능이나 성능에 영향을 미치지 않습니다. 데스크톱 앱은 브라우저를 통해 Sprocket을 사용하는 것보다 더 많은 RAM을 사용할 수 있습니다.

npx @spikonado/sprocket

위 명령어는 데스크톱 앱이 설치되어 있지 않은 경우 브라우저를 통해 Sprocket을 실행합니다. 브라우저 실행 URL에는 작업 공간 탐색 상태만 포함됩니다. 로컬 서버는 소켓 피어(socket peer), Origin, Host를 확인한 후 브라우저 세션을 생성합니다.

Sprocket은 기본 루프백 주소에 두고 HTTPS 리버스 프록시를 앞에 두세요. 예를 들어, Tailscale Serve를 사용하여 로컬 서버를 tailnet 내부로 노출할 수 있습니다:

tailscale serve --bg http://127.0.0.1:17731

Tailscale이 출력하는 HTTPS URL을 엽니다. 원격 브라우저 로그인에는 WorkOS 장치 인증(device authorization)이 사용되며, 호스트에서 sprocket login으로 이미 로그인된 계정만 허용합니다. 해당 브라우저에서 로그아웃하면 호스트를 로그아웃시키지 않고도 브라우저 세션을 취소할 수 있습니다. 일반 원격 HTTP는 거부됩니다. 다른 리버스 프록시는 루프백을 통해 Sprocket에 연결하고 브라우저에 노출되는 Host 헤더를 유지해야 합니다.

최신 GitHub 릴리스 아티팩트에서 OS용으로 설치하고 실행하세요.

npm i -g @spikonado/sprocket
sprocket

위 명령어는 데스크톱 앱이 설치되어 있지 않은 경우 브라우저를 통해 Sprocket을 실행합니다.

Sprocket 사용 시 항상 브라우저에 탭을 열려면 --web 플래그를 사용하세요:

sprocket --web

인라인 프롬프트(Inline prompts), --prompt-file, 그리고 stdin은 현재 실행 결과만 보고합니다. --thread는 재생하지 않고 자체 기록을 컨텍스트로 사용합니다. 진행 상황은 stderr로, 최종 답변은 stdout으로 가며, 전체 스크립트는 데이터 디렉터리 및 앱에 남아 있습니다.

새로운 스레드에서 열거나 다시 연결할 작업 공간(workspace)이 있는 경우 디렉터리를 전달하세요:

sprocket .
sprocket --web ../my-robot

Sprocket은 실행 간에 첨부된 작업 공간과 로컬 서버 세션을 기억합니다. 로컬 상태는 $HOME/.sprocket (또는 HOME이 설정되지 않은 Windows의 경우 %USERPROFILE%\.sprocket)에 저장됩니다.
SPROCKET_DATA_DIR로 덮어쓸 수 있습니다.

| 명령어 | 동작 | |
|---|---||
sprocket update | 현재 채널에서 전역 npm, bun, pnpm, 또는 yarn 설치를 업데이트합니다. |
sprocket update --check | 설치 없이 업데이트 가능 여부를 보고합니다. |
sprocket upgrade | update의 별칭입니다. |
sprocket serve | 클라이언트를 실행하지 않고 로컬 서버를 포그라운드에서 실행합니다. |
sprocket serve --api-only | /api만 서비스합니다; 개발용으로 의도되었습니다 (개발 참고). |

모든 옵션은 sprocket --help 또는 sprocket serve --help를 실행하세요.

일반적인 Sprocket 서버 오버라이드는 환경 변수로 사용할 수 있습니다:

| 변수 | 목적 | |
|---|---||
SPROCKET_DATA_DIR | 내부 프로세스 식별자, 세션 및 작업 공간 상태용 디렉터리. |
SPROCKET_PORT | 로컬 서버 포트; 설치된 사용의 기본값은 17731입니다. |
SPROCKET_HOST | 바인딩 호스트; 기본값은 127.0.0.1입니다. |
SPROCKET_DESKTOP_EXECUTABLE | Sprocket CLI가 사용할 데스크톱 실행 파일의 전체 경로. |
PUBLIC_CONVEX_URL | 에이전트 런타임에서 사용되는 Convex 배포 URL. |
PUBLIC_MODEL_GATEWAY_URL | UI 카탈로그(GET /api/v1/models)를 위한 공개 AI 게이트웨이 오리진. |SPROCKET_STATIC_DIR | 번들된 빌드 대신 서비스할 웹 빌드. |

• Bun 1.x, version 1.4.2 이상 또는 그 이상
• Node.js 24.x, version 24.14 이상 또는 그 이상
• 최신 안정화된 Rust toolchain

의존성을 설치하려면:

bun install

브라우저 개발 환경을 시작하려면:

bun dev

이 명령어는 http://localhost:5173에서 Vite를, 그리고 http://127.0.0.1:7731에서 Rust API를 실행하며, 개발 상태는 리포지토리 내 .sprocket-dev에 유지합니다.
그것은 dev Convex 배포판을 대상으로 합니다. 대신 ~/.sprocket 상태와 함께 프로덕션 Convex 배포판으로 실행하려면:

bun dev:prod

Electron을 대상으로 개발하려면 다음을 실행하세요:

bun dev:desktop

dev:prod / dev:prod:desktop 변형은 프로덕션 Convex 배포판과 ~/.sprocket을 사용합니다.

Convex 배포판을 생성하고 AuthKit을 구성한 후, 활성화하려는 각 모델 제공업체에 대해 해당 배포판에 API 키를 부여하세요.

spikonado.com/pricing에서의 셀프 서비스 결제는 Sprocket Convex 배포판을 사용합니다. 이 변수들을 각 Convex 배포판에 구성해야 합니다:

DODO_PAYMENTS_API_KEY
DODO_PAYMENTS_ENVIRONMENT, test_mode 또는 live_mode로 설정
DODO_PAYMENTS_WEBHOOK_SECRET
DODO_CHECKOUT_IDEMPOTENCY_WINDOW_MS, 선택적 제공업체 확인 양수 정수 보존 기간; 누락되거나 만료된 증명은 모호한 생성 재시도를 비활성화하지만 상태 조회를 비활성화하지 않습니다.
SPROCKET_MARKETING_ORIGIN, 프로덕션에서는 https://spikonado.com으로 설정
SPROCKET_BILLING_STAGING_ORIGIN, 선택적 단일 운영자 승인 HTTPS 원본(test mode용); 와일드카드, 자격 증명, 경로 또는 쿼리 불가

결제에 필요한 누락되거나 잘못된 구성은 비결제 기능을 방해하지 않도록 폐쇄적으로 실패해야 합니다. 제공업체 자격 증명을 클라이언트 PUBLIC_* 변수에 절대 넣지 마세요. 웹사이트의 PUBLIC_CONVEX_URL과 명시적인 PUBLIC_DODO_CHECKOUT_MODE는 일치하는 배포판/모드를 대상으로 해야 합니다. 유효하지 않은 반환 원본은 조용한 프로덕션 리디렉션이 아닌 오류입니다. apps/web/.env.example을 참조하세요.

. Merchant 설정, 출시 테스트 및 운영 복구는 Sprocket 프로젝트 아티팩트인 Dodo 대시보드 설정 for Sprocket (ks74f9xxtjp9hmgj0ackvxk9698f0f2g)에서 유지됩니다. 구성된 자격 증명과 제품을 통해 결제가 가능하며, 별도의 활성화 플래그는 없습니다.

Convex의 tiers 테이블에 있는 모든 행이 가격 책정 페이지에 표시됩니다. 특정 행에 monthlyProductId와 annualProductId를 설정하여 일치하는 반복 Dodo 제품을 지정합니다. 두 제품 중 어느 것도 생략할 수 있어 해당 청구 간격을 사용할 수 없게 만듭니다. 제품 ID는 모든 티어 및 간격 필드에서 고유해야 합니다. 선택적인 description, features, displayOrder, 그리고 highlighted 필드는 가격 카드(pricing card)를 제어합니다.

결제를 활성화하기 전에 Dodo의 구독 설정에서 **여러 구독 허용(Allow Multiple Subscriptions)**을 비활성화하십시오. 모든 결제는 재시도 및 다양한 플랜 선택을 포함하여 계정에 저장된 Dodo 고객 ID를 사용합니다. 고객은 미완료 구매를 즉시 변경할 수 있으며, 이전 링크는 Dodo가 만료시키기 전까지 지불 가능하므로, Dodo는 고객당 하나의 구독만 강제해야 합니다. 테스트 모드에서 두 개의 열린 결제 링크로 이를 확인하십시오. 결제 실패 또는 취소 후에도 고객 포털은 계속 사용 가능하며, 유료 접근 권한이 종료된 경우에도 마찬가지입니다.

실시간 결제(Live checkout)는 **활성 운영자 지급 승인(active operator-paid grants)**을 필요로 하지 않습니다: subscriptions 테이블에 status: 'active'이고, tier !== 'free'이며, dodoSubscriptionId가 없는 행이 없음을 확인하십시오. 그러한 모든 승인은 소유자와 함께 해결해야 하며, 절대 자동으로 삭제하거나 덮어쓰지 마십시오. 투영(projection)은 이러한 승인을 제공업체 이벤트에 대비하여 보존하므로, 해당 계정의 구매는 활성화시키지 않을 것입니다. 출시 후 새로운 비-Free 지급 승인(non-Free grants)을 발행하지 마십시오. 정상적인 활동 중인 Free 부트스트랩 행은 허용됩니다.

무료 유료 티어 접근 권한을 얻으려면, 먼저 새 수신자에게 Sprocket의 로그인된 결제 페이지를 열게 하되 완료하지 않도록 합니다. 이렇게 하면 해당 사용자의 저장된 Dodo 고객이 생성되며, 운영자는 이 ID를 계정의 billingCustomers에서 얻습니다.

mapping이 아니라 공개 체크아웃 응답을 생성합니다. 100% Dodo 구독 할인을 생성하고, 이를 의도된 제품과 특정 고객에게만 제한하며, 무기한 액세스를 위해 **구독 주기 제한(Subscription Cycle Limit)**은 비워둡니다 (또는 약속된 주기 수를 설정합니다). 수신자는 대시보드에서 생성된 고객이나 일반 결제 링크가 아닌 동일한 소유 체크아웃에서 이를 사용합니다. Dodo의 $0 가격 옵션이 있는 카드 선택 사항(Card-Optional at $0 Price) 제품 설정은 카드 요구사항을 제거할 수 있습니다. 이것은 로컬 운영자가 부여하는 것이 아니라 Dodo와 연결된 구독이며, 서명된 구독 이벤트는 여전히 액세스를 확립합니다. 무료 구독을 발급하기 전에 테스트 모드에서 제로 차지 활성화(zero-charge activation), 갱신(renewal), 할인 종료 동작을 확인하십시오. 절차 및 출처는 대시보드 아티팩트를 참조하십시오.

주간 사용량은 UTC 기준 월요일 00:00에 초기화됩니다. 무료 월별 사용량은 매월 첫날에 초기화됩니다. 월별 유료 사용량은 확인된 Dodo 청구 날짜를 따릅니다. 연간 유료 기간은 원래의 UTC 기간 앵커에서 월말 클램핑(month-end clamping)을 통해 파생되며 실제 확인된 기간 종료일로 제한됩니다. 일반적으로 갱신되는 구독은 그 종료일 이후 최대 한 시간 동안 갱신 처리 액세스를 받으며, 이전 월별 버킷과 남은 할당량을 유지하다가 갱신이 확인될 때까지 유지됩니다. 소진된 할당량은 계속 소진된 상태로 남아 있습니다. 확인된 실패/보류(hold)/만료/실효 취소는 즉시 액세스를 종료하며, 예정된 취소 후에는 처리 유예 기간이 없습니다. 이것은 결제 복구 유예가 아닙니다. 확인된 past_due

은 접근 연장으로 간주되지 않고 on_hold로 처리됩니다. 고객은 포털을 통해 실패한 결제를 수정할 수 있으며, 확인된 활성 구독만이 유료 액세스를 복원합니다.

확정된 유효 등급 변경은 갱신 시 적용되는 동등 할당량 변경 및 다운그레이드를 포함하여 사용량을 한 번 초기화합니다. 예약된 변경, 중복/재생된 이벤트, 상태 복구, 그리고 변경되지 않은 제품의 재매핑은 사용량을 초기화하지 않습니다. 진정으로 새로운 구독만이 새로운 세대를 시작합니다. Dodo 구독 ID가 없는 운영자 승인은 변경되지 않고 유지됩니다. 호환성 마이그레이션 및 제거 게이트는 BACKWARDS_COMPATIBILITY.md에 기록되어 있습니다.

Dodo 웹훅을 https://<deployment>.convex.site/dodopayments-webhook으로 지정하십시오.

, renewed`

, plan_changed`

, updated`

, on_hold`

, cancelled`

, expired`

, 및 failed`

. 일시 중지/재개 또는 환불/분쟁 구독은 추가하지 마십시오. 예상치 못한 검증된 유형은 기능 지원이 아닌 영구적으로 지원되지 않는 결과입니다. AuthKit은 CORS를 위해 승인된 웹사이트 출처와 /pricing/callback 리디렉트 URI를 허용해야 합니다.

청구 불만 및 환불 요청은 [email protected]으로 보내십시오. 운영자는 Dodo/이메일에서 환불 및 분쟁을 처리하며, Sprocket에는 환불 요청 양식이나 전용 환불/분쟁 하위 시스템이 없습니다. 환불 자체는 미래 청구를 취소하거나 사용 할당량을 변경하지 않습니다.

cargo test
bun run test
bun run build
...

다음과 같이 로컬 Electron 설치 패키지를 생성하십시오:

bun run build:release

아티팩트는 호스트 OS에 따라 sprocket-desktop-* (.AppImage / .dmg / .exe)로 apps/desktop/dist/에 작성됩니다.
게시된 설치 프로그램은 GitHub Releases에서 가져오며, sprocket CLI는 npm에서 별도로 게시됩니다.

Sprocket은 Functional Source License, Version 1.1, ALv2 Future License 하에 라이선스가 부여됩니다. 제3자 자료는 THIRD_PARTY_NOTICES.md에 나열된 라이선스 하에 유지됩니다.

• 17731이 이미 사용 중인 경우, 실행 전에 SPROCKET_PORT를 설정하십시오. - 설치된 로그인 기능이 네이티브 세션을 저장하거나 복원할 수 없는 경우, 운영 체제 자격 증명 서비스가 사용 가능한지 확인하십시오. Linux 개발 환경에서는 작동하는 Secret Service Provider가 필요합니다.
• sprocket

브라우저를 열고 데스크톱 앱 대신, GitHub Releases에서 sprocket-desktop을 PATH에 설치하거나 SPROCKET_DESKTOP_EXECUTABLE을 설정하십시오.

• 서명되지 않은 macOS 및 Windows 데스크톱 빌드는 처음 열 때 Gatekeeper/SmartScreen 우회(override)가 필요할 수 있습니다.
• 도움말은 [email protected]으로 문의하십시오.