| name | remote-offload |
| description | 무거운 작업(스크래핑, 인코딩, 빌드, 대량 API 수집)을 SSH로 보조 머신에 넘긴다. 저사양 노트북에서 에이전트를 돌릴 때 메모리 부족을 피하는 패턴. |
원격 머신 오프로딩
바로 쓰는 스크립트
scripts/offload.sh — 무거운 작업을 원격 기기로 넘깁니다.
./scripts/offload.sh "python heavy_scraper.py"
./scripts/offload.sh --dir ~/Projects/app "npm run build"
./scripts/offload.sh --bg "ffmpeg -i in.mov -c:v libx264 out.mp4"
원격이 죽어 있으면 로컬로 폴백하지 않고 그냥 멈춥니다. 메모리 부족으로 노트북이 죽는 걸 막기 위해서입니다.
왜
| Aside 돌아가는 기기 | 오프로딩 대상 |
|---|
| 기기 | MacBook Air, Apple M1 | Mac mini, Apple M4 |
| 램 | 8 GB (상시 부족, 압축 2.6GB / 여유 70MB 수준) | 16 GB |
| 절전 | 사용자가 덮으면 멈춤 | pmset sleep 0 — 안 잠듦 |
| 디스크 여유 | 200 GB | 54 GB |
맥북에어는 램이 모자라 크로미움이 백그라운드 탭을 강제 종료한다. 로컬에서 무거운 걸 돌리면
사용자의 탭이 죽는다. 무거운 건 원격 머신로 넘기는 게 기본값이다.
접속
ssh remote-host
ssh remote-host-lan
비대화형에서는 -o BatchMode=yes -o ConnectTimeout=10을 붙인다.
PATH가 필요한 명령(brew 설치물 등)은 ssh remote-host 'bash -lc "..."'로 로그인 셸을 태운다.
작업공간 규약
~/Projects/<프로젝트>/offload/
├── run.sh 러너 (아래 참조)
├── jobs/ 실행할 스크립트를 여기로 scp
├── out/ 산출물 (이미지, csv, json 등)
├── logs/ <JOB_ID>.log / .pid / .cmd.sh
└── node_modules/ playwright 설치됨
기존 프로젝트 작업은 ~/Projects/<repo>에서 그대로 하고, 일회성 오프로딩만 여기를 쓴다.
판단 기준
넘긴다
- 헤드리스 스크래핑, 특히 여러 페이지 순회 (로그인 불필요한 공개 페이지)
- ffmpeg 인코딩, GIF 생성, 이미지 대량 변환
npm install, next build, 대형 저장소 clone- 대량 API 수집 (수백~수천 건 페이지네이션)
- 수십 MB 이상 파일 파싱/집계
- 30초 넘게 걸릴 것 같은 CPU 작업 전부
- 긴 문서/영상 스크립트 읽고 요약 (아래
claude -p 레시피)
안 넘긴다
- 사용자의 로그인 세션·쿠키가 필요한 브라우징 → Aside 브라우저에서 해야 함
- 사용자가 화면으로 확인해야 하는 UI 조작
- 몇 초 안에 끝나는 단순 조회 (ssh 왕복이 더 느림)
- 사용자 개인 파일이 맥북에어에만 있는 경우 (전송 비용 판단 후 결정)
표준 패턴: 스크립트를 보내서 실행
ssh + bash -lc + heredoc을 중첩하면 따옴표가 반드시 깨진다.
로컬에 파일로 쓰고 scp로 보낸 뒤 실행한다.
TMP=<세션 tmp 디렉토리>
cat > "$TMP/job.js" <<'EOF'
... 스크립트 ...
EOF
scp -q "$TMP/job.js" remote-host:~/Projects/<프로젝트>/offload/jobs/job.js
ssh remote-host 'cd ~/Projects/<프로젝트>/offload && node jobs/job.js'
긴 작업: run.sh
ssh 세션이 끊겨도 살아남아야 하는 작업은 러너로 띄운다.
R=~/Projects/<프로젝트>/offload/run.sh
ssh remote-host "$R start 'node jobs/scrape.js' scrape"
ssh remote-host "$R status scrape-20260811-124757"
ssh remote-host "$R tail scrape-20260811-124757"
ssh remote-host "$R log scrape-20260811-124757"
ssh remote-host "$R list"
작업이 오래 걸리면 붙잡고 기다리지 말고, 그동안 로컬에서 다른 일을 하다가 status로 확인한다.
산출물 회수
scp remote-host:~/Projects/<프로젝트>/offload/out/result.csv <세션 artifacts 디렉토리>/
scp -r remote-host:~/Projects/<프로젝트>/offload/out/frames <세션 tmp 디렉토리>/
사용자에게 보여줄 결과물은 artifacts 디렉토리로, 중간 확인용은 tmp로 가져온다.
레시피
헤드리스 브라우징 (playwright)
const { chromium } = require('playwright');
(async () => {
const b = await chromium.launch({ headless: true });
const p = await b.newPage();
await p.goto(url, { waitUntil: 'domcontentloaded' });
await p.screenshot({ path: 'out/shot.png' });
await b.close();
})();
워밍업 후 페이지 로드 0.3초 수준. 전역에 puppeteer도 있지만 playwright를 기본으로 쓴다.
미디어
ffmpeg는 /opt/homebrew/bin/ffmpeg. 인코딩·GIF 변환은 전부 원격 머신에서 한다.
web-demo-video 스킬의 프레임 합성 단계도 여기로 넘길 수 있다.
긴 문서 읽기를 CLI로 위임
메인 컨텍스트에 원문을 쌓지 않으면서 긴 자료를 요약할 때:
ssh remote-host 'bash -lc "cat ~/Projects/<프로젝트>/offload/jobs/doc.txt | claude -p --model claude-sonnet-4-5"'
사용량 한도가 걸리면 claude-codex-fallback 스킬의 판별 규칙을 따른다.
Codex CLI(codex)도 설치되어 있다.
설치된 도구
node v26 / npm 11 / python3.9 / uv / brew 6 / ffmpeg / rg / jq / git / gh 2.92 /
vercel / claude CLI 2.1 / codex CLI 0.147 / playwright(offload 로컬) / puppeteer(전역) /
Google Chrome
없는 게 필요하면 ssh remote-host 'bash -lc "brew install <pkg>"'로 설치하고 이 목록을 갱신한다.
주의
- 원격 머신는 이미 launchd 상주 작업이 여러 개 돈다 (
atlas-server, atlas-kakao-poll,
threads-fetch, voicememoimporter, 디스코드 채널 봇, 각종 리마인더). 코어를 다 쓰는
작업을 걸기 전에 run.sh list와 launchctl list | grep bambam을 확인한다.
- 예약 실행(리마인더/크론)은 이 스킬이 아니라
macmini-discord-reminder 스킬을 따른다.
- 자격증명은 원격 머신에 있는 기존
.env에서 런타임에만 읽고, 값을 출력하지 않는다.
- 디스크 여유가 54GB뿐이다. 대용량 임시 파일은 작업 후
out/에서 정리한다.
- 파괴적 작업(대량 삭제 등)은 AGENTS.md의 안전 규칙을 그대로 적용한다.
