본문으로 건너뛰기
내 AI@https://hoody.com Connect to Hoody

개발자 모드

쉬운 말로 풀어 썼어요. 이제 Hoody를 구체적으로 살펴봐요.

이제 각 섹션에 실제 Bot API 호출이 그대로 표시돼요. 복사할 수 있고, 전체 호출은 맨 끝에 모아 뒀어요.

호출 보기

hoody / bots

Bots

Bot에게 말하세요
에이전트는 Bot이 실행해요

Bot은 채팅 하나로 대화 전체를 이어 가며 오래 함께하는 어시스턴트예요. 무엇이든 맡겨 보세요. 내 컴퓨터에서 에이전트를 열고, 작업을 지켜보다가 한 일을 알려 줘요. Bot에 .hoody.bot URL을 부여하면, 이름을 붙인 키로 믿을 수 있는 사람과 AI에게 공유할 수 있어요.

첫 번째 Bot인 chief는 처음부터 있어요. Hoody AI (무료)는 기본으로 들어 있어요. ChatGPT로 로그인할 수도 있어요. Bot의 도우미는 허용하면 Claude Code로 Claude Pro나 Max를 쓸 수 있어요.

구조예시
나

My site의 오타와 Shop 가격을 고치고, 새 사진을 정리해 주세요.

내 Bot

chief채팅 하나 · 이전 대화는 요약 · 내가 정한 한도

에이전트

완료My site 오타 수정

확인 요청Shop 가격 수정

작업 중새 사진 정리

내 컴퓨터
My site Shop Photos

에이전트는 모두 내 컴퓨터 한 대에서 실행되는 Hoody Agent 세션이에요.

구체적으로

첫 번째 Bot
GET /api/v1/agent/bots/chiefchief Bot은 처음 쓸 때 만들어지므로, Bots 목록이 비어 있는 일은 없어요.
실행되는 곳
https://{p}-{c}-agent-1.{node}.computers.hoody.com/api/v1/agent/botsBot은 Hoody Agent(agent-1)에서 실행돼요. /api/bot/의 채팅 앱 서비스가 아니에요.
hoody / how it flows

메시지 하나로 끝까지 진행돼요. 결과를 알려 줘요.

나

이 중 어디서든

보고서완료. Shop을 고쳤어요.

내 컴퓨터

내 Bot

메시지를 바로 받고, 끝나면 결과를 알려 줘요

에이전트

도우미

에이전트

도우미

  • My site업데이트
  • Shop수정
  • Photos백업

예시모두 내 컴퓨터에서 실행돼요. 내 Bot은 각 컴퓨터를 알고 있어요.

구체적으로

Bot의 에이전트
GET /api/v1/agent/bots/chief/delegates?state=open위임한 에이전트는 모두 일반 세션이에요. /sessions 경로로 읽거나 연결해요. 열려 있는 세션에는 capability, current_step 항목이 있어요.
자체 실시간 턴
GET /api/v1/agent/sessions/{session_id}/stream작성되는 대로 보이는 답변 텍스트와 생각, 도구 호출, 각 턴의 끝. session_id 항목은 Bot이 첫 메시지를 받은 뒤부터 GET /bots/{id}에서 와요.
더 보기: Bot별로 한 턴 전체 보기

한 번만 맡기세요. 작업은 Bot이 나눠 줘요.

Bot은 먼저 답하고, 오래 걸리는 부분은 에이전트를 열어 맡겨요. 에이전트의 질문과 결과는 다시 내게 전해 줘요.

예시 턴

나, 09:12

My site의 가격 오타를 고쳐 주세요. 그리고 Shop 결제가 왜 느려졌는지 알아봐 주세요.

Chief, 09:12

맡을게요. 에이전트 두 개를 열어요. 하나는 My site에서 수정하고, 하나는 Shop에서 결제 시간을 재요. 끝나면 알려 줄게요.

열었어요 에이전트 2개 · My site, Shop

Chief, 09:19

My site 에이전트가 오타를 고쳤고, 이 명령을 실행하려고 해요. 허용할까요?

bash: ./publish.sh

나, 09:20

네, 진행해 주세요.

[report] My site 에이전트 완료: 오타를 고쳤고 사이트를 업데이트했어요.

Chief, 09:31

My site 작업을 마쳤어요. 수정이 이미 적용됐어요. 결제는 느린 조회 하나를 기다리고 있고, Shop 에이전트가 시험해 볼 수정안을 준비했어요.

언제든 입력하세요Bot이 바쁠 때 보낸 메시지는 차례를 기다려요. 정정 내용을 보내면 둘을 함께 읽어요.
내 컴퓨터에서 일해요에이전트는 코드와 파일이 있는 곳에서 실행되고, 탭을 닫아도 계속 일해요.
돌아와서 물어봐요에이전트의 요청은 내가 보낸 메시지로만 승인돼요. 에이전트의 보고로는 승인되지 않아요.

구체적으로

내 메시지
POST /api/v1/agent/bots/chief/messages응답: 202(message_id, state, turn_id 포함). Bot이 바쁠 때: state: queued.
답장
GET /api/v1/agent/bots/chief/streamSSE: state 프레임 한 번, 이후 로그 행마다 row 한 번. 재개: Last-Event-ID 사용.
에이전트 하나 중지
POST /api/v1/agent/bots/chief/delegates/{sid}/stop해당 에이전트의 작업만 바로 중지하고, Bot은 중지하지 않아요. {"close": true} 사용 시 세션도 닫아요.
음성으로 말하기
POST /api/v1/agent/bots/chief/messages/audiowav 또는 mp3 녹음은 텍스트로 변환돼 내 메시지로 전송돼요.
hoody / api

Bot에 공개 URL 부여, 믿을 수 있는 사람과 앱, AI 연결

URL 하나로 세 가지 방법을 쓸 수 있어요. 기본 URL을 받는 앱과 SDK에서는 모델로(OpenAI 또는 Anthropic 형식), MCP 서버로, 스크립트에서는 일반 HTTP로 써요.

chief · Bot URL

https://<label>.hoody.bot
Bot의 QR 코드예요. 가운데에 Bot 마크가 있고, Hub에서 그리는 모양 그대로예요. 휴대폰으로 스캔하면 Bot의 채팅 페이지가 열려요. 이 샘플로 다음 주소가 열려요. hoody.com/bots.

1앱에서

내 앱예시 ID
형식
기본 URL<Bot URL>/v1
모델bot:global/chief
API 키내 hbk_ 키
기본 URL<Bot URL>
모델bot:global/chief
API 키내 hbk_ 키
서버 URL<Bot URL>/mcp
전송 방식HTTP, 요청마다 POST
API 키내 hbk_ 키

채팅 완성, 응답, 모델 목록을 다뤄요. 마지막 사용자 메시지만 전송되고, 앱의 자체 시스템 프롬프트와 설정은 빠져요.

/v1 없는 URL에서 메시지와 모델을 다뤄요. 마지막 사용자 메시지만 전송되고, 앱의 자체 시스템 프롬프트와 설정은 빠져요.

Bot을 MCP 서버로 써요. JSON-RPC로 응답하고, 유지할 세션도 이벤트 스트림도 없어요.

2스크립트에서

일반 HTTP

  • POST /bots/chief/messages

    스크립트, 크론 작업, 다른 AI에서 작업을 맡겨요.

  • GET /bots/chief/stream

    완료된 답장과 에이전트 이벤트를 따라가요. Bot의 세션 스트림에는 답장이 작성되는 대로 보여요.

  • POST /bots/chief/delegates/{sid}/stop

    에이전트 하나를 중지해도 Bot은 계속 실행돼요.

3접속할 수 있는 사람이나 앱

믿을 수 있는 사람이나 앱마다 이름을 붙인 키를 주세요. 키별로 일시정지하거나, 만료일이나 IPv4 제한을 설정하거나, 취소할 수 있어요.

키가 있는 사람은 모두 하나의 대화를 함께 써요. 믿을 수 있는 사람과 AI에게만 공유하세요.

Bot을 렐름(컴퓨터 묶음) 하나에 묶어 두세요. 에이전트는 렐름 안의 컴퓨터만 볼 수 있어요.

구체적으로

Bot 기본 URL
https://{p}-{c}-agent-1.{node}.computers.hoody.com/api/v1/agent/bots/{realm}/{bot}OpenAI는 <base>/v1, Anthropic은 기본 URL, MCP는 <base>/mcp 사용. {realm} 값은 global 또는 24자리 16진수 ID예요. Bot 목록은 GET /bots/{id}의 urls 아래에 있어요. 공유 Bot: Bearer 키와 함께 https://<label>.hoody.bot/v1/chat/completions 호출.
메시지 보내기
curl -X POST "<agent>/api/v1/agent/bots/chief/messages" -H "Authorization: Bearer <token>" -d '{"text":"Ship it"}'텍스트 최대 64KiB. 202로 응답해요.
에이전트 하나 중지
POST /api/v1/agent/bots/chief/delegates/{sid}/stop {"close":true}위임된 에이전트만 중지하고, Bot은 중지하지 않아요.
hoody / guardrails

평소 쓰는 말로 적는 것만으로 설정 완료

Bot이 절대 하면 안 되는 일을 내 말로 적으세요. 저장하면 끝이에요.

  • 문법 없음
  • 모든 에이전트에 적용돼요
  • 위험한 작업은 시작 전에 확인해요

chief · 안전장치예시

main에 직접 푸시하지 말고 PR을 열고 내 답을 기다리세요 결제 관리, DNS, 대금 지급은 건드리지 마세요 운영 데이터베이스는 읽기 전용이에요 작업 비용이 20달러를 넘으면 멈추고 물어보세요 확실하지 않으면 추측하지 말고 나에게 물어보세요

구체적으로

가드레일 교체
PUT /api/v1/agent/bots/chief/guardrails {"guardrails":"Never push to main."}텍스트 필드 하나예요. Bot은 다음 메시지 전에 각 줄을 [guardrails updated] 표시와 함께 받아요.
엄격도
"guardrail_check": "strict"strict(기본), lenient 또는 off. docs / api / agent / bots ↗

구체적으로

어디서든 보내기
POST /api/v1/agent/bots/chief/messages {"text":"Is staging up?"}202로 응답해요. Bot이 작업 중일 때는 queued도 함께 와요. 안전하게 다시 시도하려면 Idempotency-Key도 추가하세요.
스트림 이어받기
GET /api/v1/agent/bots/chief/stream?since=154Server-Sent Events를 써요. 각 행 프레임의 id가 해당 행의 seq 값이어서 Last-Event-ID가 자동으로 이어받아요.
음성 접속 방법
…/bots/{id}/voice · …/bots/{id}/realtimeBot 하나에는 실시간 음성 연결이 한 번에 하나만 열려요. takeover=true 실행 시 기존 연결이 대체돼요. docs / api / agent / bots ↗
더 보기: 로그
예시: 기기 네 대, Bot 하나, 로그 하나

기기 네 대에서 같은 Bot을 열어 두었어요. 휴대폰, 노트북, 터미널, AI 앱이에요. 휴대폰과 노트북이 22:31에 동시에 메시지를 보내면 #152, #153 순서로 들어오고, Bot의 답장은 #154가 돼요. 모든 기기에서 같은 순서로 보여요. 오래된 턴인 행 #1~#120은 짧은 요약으로 접히고, 최신 턴인 #121~#154는 원문 그대로 남아요. 전체 로그에는 모든 행이 남아요.

모든 기기가 하나의 대화를 봐요. 휴대폰, 노트북, 터미널, AI 앱이 같은 Bot을 동시에 열어 두고, 모든 기기에서 같은 순서로 보여요. 키를 가진 사람도 이 대화를 함께 보니, 믿을 수 있는 사람과만 공유하세요.

메시지마다 다음 번호가 붙어요. 동시에 보낸 두 메시지는 #152, #153 순서로 들어와요. Bot이 작업 중일 때 보낸 메시지는 다음 턴을 기다려요.

공간이 모자랄 일이 없어요. 모델의 컨텍스트 창이 가득 차면 오래된 턴은 짧은 요약으로 접히고, 최신 턴은 원문 그대로 남아서 Bot이 계속 이어 가요. 로그에는 모든 행이 남고, 잊기를 하면 행이 아카이브로 옮겨져요.

행에 담긴 정보
각 행의 항목: seq, at, role(user, bot, event 또는 system), text. 추가로 session_id도 담을 수 있어요. 로그는 seq 기준으로 페이지를 나누고, 스트림은 새 행이 기록되는 즉시 보내요.
모델 바꾸기
새 모델은 Bot의 다음 세션부터 적용돼요. 초기화하면 로그가 아카이브로 옮겨지고 새 세션이 열려요. 아카이브는 삭제하기 전까지 읽을 수 있어요.
에이전트가 기억하는 내용
에이전트는 스스로 기억한 내용도 저장하고 검색해요(키워드, 의미, 항목 간 링크 기준). 하나의 AI 앱에 묶여 있지 않아요. docs / api / agent / memory ↗

구체적으로

로그 읽기
GET /api/v1/agent/bots/chief/log행을 순서대로, seq 기준으로 나눠 가져와요.
따라가기
GET /api/v1/agent/bots/chief/streamstate 프레임이 먼저 오고 그다음 행이 와요. 아카이브로 옮겨진 커서에는 lagged 응답이 와요.
잊기
POST /api/v1/agent/bots/chief/forget나중에 읽기는 GET …/archive, 삭제는 POST …/purge.
더 보기: 훅

훅 연결: 스크립트가 호출을 먼저, 응답을 마지막에 보는 구조

훅은 조건에 맞는 HTTP 호출을 Bot이나 내 컴퓨터의 다른 서비스 대부분으로 보내기 전에, 내 Exec 스크립트 중 하나를 먼저 거치게 해요. 조건에 맞는 경로로 들어오는 WebSocket 업그레이드는 거부돼요. Bot 음성 경로 등은 조건에서 빼 두세요. 들어갈 때는 호출을 지켜보거나, 확인하거나, 바꾸거나, 직접 응답하거나, 막을 수 있어요. 나갈 때는 응답을 읽고, 호출한 쪽이 받기 전에 바꿀 수 있어요. 따로 패치할 필요가 없어요.

호출한 쪽에서 Bot 또는 내 컴퓨터의 다른 서비스 대부분까지 이어지는 순환 경로예요. 호출은 위쪽으로 들어가고, 응답은 아래쪽으로 돌아와요. Exec 스크립트 하나가 두 경로에 걸쳐 있어서, 들어갈 때는 모든 호출을 보고 나올 때는 모든 응답을 볼 수 있어요. 훅마다 시간 제한이 있고, 기본값은 500 ms예요.

들어감들어갈 때

  • 지켜보기누가 무엇을 호출했는지 기록하고 그대로 전달해요.스크립트 보기스크립트 숨기기

    규칙: POST /api/v1/agent/bots/* → /bot-audit

    module.exports = async function (req, res, metadata) {
      if (!metadata.hook) {
        res.writeHead(404);
        return res.end();
      }
      const ip = req.headers['x-real-ip'];
      console.log(metadata.hook.auditId,
        metadata.hook.origPath, ip);
      await metadata.hook.forward(req, res);
    };

    스크립트에는 실제 클라이언트 IP가 보여요. 훅 없이 호출하면 metadata.hook 값이 비어 있어서 404로 응답해요. forward()은 호출을 받은 그대로 Bot에 전달해요.

  • 확인로그인한 사람만 통과시켜요. 요청 제한도 같은 자리에 있어요.스크립트 보기스크립트 숨기기

    규칙: any method except OPTIONS /api/v1/agent/bots/* → /identity-gate

    module.exports = async function (req, res, metadata) {
      if (!metadata.hook) {
        res.writeHead(404);
        return res.end();
      }
      const user = verifyClaim(
        req.headers['x-hoody-claim']);
      if (!user) {
        res.writeHead(401);
        return res.end();
      }
      await metadata.hook.forward(req, res,
        { headers: {
          'x-hoody-claim': null,
          'x-hoody-user': user.username,
        } });
    };

    verifyClaim에서 ED25519로 서명된 Hoody 로그인 클레임을 확인해요. 전체 스크립트는 문서에 있어요. 클레임이 없으면 401을 받고 Bot에 닿지 못해요. 이 규칙을 그대로 두면 WebSocket 음성 경로도 거부돼요. 음성 경로가 빠지도록 범위를 좁혀 주세요.

  • 변경메서드, 경로, 헤더 또는 본문을 요청이 도착하기 전에 바꿔요.
  • 차단바이러스 검사를 통과하지 못한 업로드나 한도를 넘은 호출을 돌려보내요.
  • 응답“곧 돌아올게요”처럼 직접 답하면 Bot은 호출을 보지 못해요.스크립트 보기스크립트 숨기기

    규칙: POST /api/v1/agent/bots/* → /bot-gate

    module.exports = async function (req, res, metadata) {
      if (!metadata.hook) {
        res.writeHead(404);
        return res.end();
      }
      if (process.env.MAINTENANCE) {
        res.writeHead(503);
        return res.end('Back soon');
      }
      await metadata.hook.forward(req, res,
        { headers: { cookie: null } });
    };

    스크립트가 보낸 응답은 Bot에 전달되지 않아요. forward() 사용 시 메서드, 경로, 헤더 또는 본문도 바꿀 수 있고, null 값으로 설정한 헤더는 제거돼요.

나감나올 때

  • 응답 읽기호출한 쪽보다 먼저 상태, 헤더, 본문을 확인해요.
  • 다시 쓰기응답을 그대로 보내거나 직접 만든 응답을 보내요.스크립트 보기스크립트 숨기기

    규칙: any method except OPTIONS /api/v1/agent/bots/* → /bot-answer

    module.exports = async function (req, res, metadata) {
      if (!metadata.hook) {
        res.writeHead(404);
        return res.end();
      }
      const up = await metadata.hook.fetchUpstream(req);
      if (up.status === 401) {
        res.writeHead(401);
        return res.end('Please sign in again');
      }
      res.setHeader('x-hoody-hook-audit', metadata.hook.auditId);
      await metadata.hook.pipeResponse(up, res,
        { method: req.method });
    };

    fetchUpstream() 사용 시 Bot의 응답을 보내지 않고 가져오므로 스크립트가 먼저 읽어요. pipeResponse() 사용 시 응답을 그대로 전달해요. 스트리밍 응답은 훅의 제한 시간이 다 되면 끝나며, 최대 30,000ms예요.

  • 헤더 정리응답에서 비공개 헤더를 제거하고 CSP를 추가해요.

훅마다 시간 제한이 있고, 기본값은 500 ms예요. 스크립트가 실패하거나 시간이 초과되면 호출은 거기서 멈춰요. docs / proxy / hooks ↗

구체적으로

훅 추가
POST /api/v1/computers/{id}/proxy/hooks/agent · If-Match: file:v<N> {"match":{"method":["POST"],"path":"/api/v1/agent/bots/*"},"script":{"path":"/bot-audit"},"timeout":500}훅의 id는 서버가 정해요. 규칙은 순서대로 실행되고, 처음 일치한 규칙이 적용돼요.
버전 읽기
GET /api/v1/computers/{id}/proxy/hooks/agent훅을 바꿀 때마다 현재 버전을 담은 If-Match: file:v<N> 값이 필요해요.
스크립트
POST /api/v1/exec/scripts/write {"path":"bot-audit.js","content":"module.exports = async function (req, res, metadata) { … }"}여기 스크립트 본문은 형태만 보여 줘요. { … } 자리에 감사 코드를 넣으세요. script.path 값은 내 hoody-exec에 있는 스크립트 이름이에요. 스크립트는 exec 링크에 쓰세요. /bot-audit에서 bot-audit.js 내용을 제공해요. docs / api / exec / script-management ↗

한 줄로 무료로 시작하기

카드 없이 무료로 시작해요. Hoody AI가 기본으로 들어 있고, 이미 쓰고 있는 AI도 사용할 수 있어요.

코드 없이
코드
내 AI@https://hoody.com Connect to Hoody

ChatGPT, Claude 또는 페이지를 불러올 수 있는 어떤 AI에서든 작동해요. 복사해서 붙여 넣으세요.

내 AI
@https://hoody.com Connect to Hoody
docs / foundation / agent-skill-bundle
브라우저
https://hub.hoody.com
docs / kit / agent
터미널
ssh hoody.comssh 클라이언트가 있는 기기라면 어디서든 대화형 터미널에서 쓸 수 있어요. 설치할 필요가 없어요.
docs / kit / agent
스킬
npx skills add https://hoody.com/SKILLS/SKILL.mdnpx skills add HoodyNetwork/hoody-sdk두 번째 명령은 모든 문서 페이지를 디스크에 추가해서 오프라인에서 쓸 수 있어요.
docs / foundation / agent-skill-bundle
CLI
npm install -g hoody-sdkcurl -fsSL https://install.hoody.com | sh두 번째 명령은 Linux와 macOS용이에요. 설치 없이 쓰려면 다음처럼 실행하세요. npx hoody-sdk <command>
docs / foundation / cli
SDK
npm install hoody-sdkTypeScript. Node.js 20.19 이상, Bun, Deno를 지원해요.
docs / getting-started / quickstart
HTTP API
curl -H "Authorization: Bearer <token>" https://api.hoody.com/api/v1/computers/
docs / api / authentication
브라우저 SDK
<script src="https://cdn.jsdelivr.net/npm/hoody-sdk/dist/hoody-sdk.browser.min.js"></script>제공 항목: window.HoodySDK. 운영 환경에서는 버전을 고정하세요. 페이지에는 수명이 짧고 범위가 제한된 토큰을 주세요.
docs / getting-started / quickstart

2021년부터

프라이버시에서 에이전트 인프라로

hoody / kit

컴퓨터에 기본으로 들어 있는 것

서비스마다 고유한 링크가 있어요. 열거나, 공유하거나, AI에게 넘기세요. 링크를 아는 사람은 잠그기 전까지 누구나 열 수 있어요. Kit 링크 형태는 다음과 같아요. https://{p}-{c}-<kit>-1.{node}.computers.hoody.com 여기서 {p} 자리는 내 프로젝트, {c} 자리는 내 컴퓨터 중 하나, {node} 자리는 컴퓨터의 서버예요.

컴퓨터

Bots

API