@maki/local-agent

MarkHub 로컬 에이전트 데몬. 유저 컴퓨터에 설치되어, 마크헙 에이전트가 큐에 쌓은 "브라우저 유즈" 잡을 주기적으로 폴링·claim 하고, 로컬에 설치된 Claude Code 또는 Codex SDK 로 브라우저를 제어(Playwright MCP, read-only)한 뒤 결과를 서버에 보고한다. 서버는 결과를 지정 허브의 마크로 기록한다.

특징

• CLI spawn 없음 — 벤더 공식 Node SDK(@anthropic-ai/claude-agent-sdk, @openai/codex-sdk)를 in-process 로 사용.
• API 키 불필요 — 로컬 CLI 로그인(Claude Code 구독 / codex login)을 그대로 재사용.
• 아웃바운드 폴링 — 인바운드 포트를 열지 않고 서버 REST 2개(claim/report)만 호출.
• read-only 강제 — Playwright 툴 화이트리스트(Claude) / sandboxMode: read-only(Codex) + 시스템 프롬프트.

설치 (유저)

npm i -g markhub-local-agent   # 전역 설치 → `maki-agent` 명령 노출
# 또는 설치 없이 1회 실행:
npx markhub-local-agent <command>

사전 조건

• Node.js ≥ 20
• Google Chrome 설치 — 에이전트가 전용 Chrome 프로필(~/.maki-agent/chrome-profile)로 로그인 세션을 재사용한다.
• 백엔드 로그인 — 쓰려는 backend 가 로그인돼 있어야 한다: Claude Code 로그인(구독) 또는 codex login.
• 첫 잡 실행 시 @playwright/mcp 가 npx 로 1회 다운로드된다(네트워크 필요).

사용

1. 마크헙 워크스페이스 설정 → Local Agent 탭에서 페어링 코드 발급.
2. 이 컴퓨터에서 페어링:

maki-agent pair --server https://<markhub-api> --code <8자코드> [--backend claude|codex]

3. 데몬 실행:

maki-agent run                    # 기본 60초 폴링, 브라우저 headless(창 안 뜸)
maki-agent run --backend codex    # 로컬 backend override
maki-agent run --interval 30      # 폴링 주기(초, 최소 30)
maki-agent run --headed           # 브라우저 창 띄우기(로그인 세팅/봇탐지 회피)

브라우저는 기본 headless(창 안 뜸)로 실행된다. 전용 프로필(~/.maki-agent/chrome-profile)에 처음 로그인하거나 headless 를 봇으로 차단하는 사이트를 탐색할 땐 --headed(또는 MAKI_AGENT_HEADED=1)로 창을 띄운다.

토큰/설정은 ~/.maki-agent/ (token, config.json, chrome-profile/, codex-home/) 에 chmod 600 으로 저장된다.

로그인 시 자동 실행 (시스템 등록)

run 은 포그라운드 실행이라 터미널을 닫으면 멈춘다. 컴퓨터에 로그인할 때마다 백그라운드로 자동 실행되게 하려면 등록한다.

maki-agent install     # 로그인 시 자동 실행 등록 + 지금 바로 백그라운드 시작
maki-agent uninstall   # 등록 해제

• macOS: launchd LaunchAgent (~/Library/LaunchAgents/ink.markhub.local-agent.plist). 로그는 ~/.maki-agent/agent.log.
• Linux: systemd --user 서비스 (maki-agent.service).
• Windows: 시작프로그램 폴더에 배치 등록 — 다음 로그인부터 적용된다.

install 은 페어링(maki-agent pair) 후, 전역 설치(npm i -g) 상태에서 사용한다 (npx 임시 경로는 다음 실행 때 사라진다). 서비스는 headless run(자동 로그인 창 없음)으로 돈다 — 로그인이 필요한 사이트는 미리 maki-agent login <domain> 으로 등록해 둘 것. 설정에서 기기를 폐기(revoke)하면 서비스가 401 로 재기동을 반복하므로, 그 기기에선 maki-agent uninstall 로 등록을 해제한다.

backend 우선순위

--backend 플래그 > MAKI_AGENT_BACKEND 환경변수 > 서버 잡 stamp > claude.

로그인이 필요한 사이트

에이전트는 전용 Chrome 프로필(~/.maki-agent/chrome-profile)에 로그인 세션을 저장하고, 이후 headless 잡이 그 세션을 상속한다. 로그인 벽이 있는 사이트는 두 가지 방법으로 처리한다.

1. 미리 등록 — 자주 쓰는 로그인 사이트는 실행 전에 등록해 둔다.

   maki-agent login x.com     # 헤디드 창이 열림 → 직접 로그인 → 창을 닫으면 세션 저장
   maki-agent login           # 도메인 없이 열어 빈 프로필 창만 띄우기

2. 실행 중 자동 — 데몬을 --auto-login 으로 돌리면, 잡이 로그인 벽을 만나는 순간 해당 도메인 로그인 창이 자동으로 열린다.

   maki-agent run --auto-login      # MAKI_AGENT_AUTO_LOGIN=1 로도 동일

   로그인 후 창을 닫아야 폴링이 재개된다(프로필을 공유해 잡과 로그인 창을 동시에 열 수 없다). 디스플레이 없는 서버에선 켜지 말 것 — 창을 못 띄운다.

Codex 사용 시

codex login (ChatGPT 계정)이 되어 있어야 한다. 데몬은 ~/.codex/auth.json 을 격리 홈으로 복사해 재사용하며, 로그인이 없으면 브라우저를 띄우기 전에 실패한다. 기본 모델은 MAKI_AGENT_CODEX_MODEL 로 오버라이드 가능.

개발 (모노레포)

모노레포에서 직접 빌드/실행할 때:

cd apps/local-agent
pnpm install       # 두 SDK + @playwright/mcp 설치 (Playwright 브라우저 포함, 용량 큼)
pnpm build

SDK 버전은 package.json 에 핀 고정되어 있다([email protected], [email protected], @playwright/[email protected]). API 가 자주 바뀌므로 버전 변경 시 src/backends/*.ts 를 재검증할 것.

npm 배포

npm run build          # dist 생성
npm pack --dry-run     # tarball 내용 검수 (dist/** + README + package.json)
npm publish            # 무스코프 공개 (npm login 선행 필요)