MIT License · by Sunny J LabMIT License · Sunny J Lab

nongside documentationnongside 문서

On a closed network the model was never trained on, nongside finds the way by reading the screen, then keeps that path on this machine for the next time.모델이 학습한 적 없는 폐쇄망에서, nongside는 화면을 읽으며 길을 찾고 그 경로를 이 기기에 남겨 다음에 다시 씁니다.

Overview개요#Link to this section이 섹션 링크

nongside drives the Edge or Chrome already installed on this machine. Each turn it reads the interactive elements on the page and lets the model you configured choose the next tool. There is no web-search tool. find only looks up an element by text.nongside는 이 기기에 설치된 Edge 또는 Chrome을 움직입니다. 매 턴 페이지의 조작 요소를 읽고, 설정한 모델이 다음 도구를 고릅니다. 웹 검색 도구는 없습니다. find는 텍스트로 요소를 찾을 뿐입니다.

On a closed network, internal sites were never in the model’s training data, and the public web is not there to search. The first time, nongside reads the screen and walks the path. A path that succeeds is saved on this machine as a task recipe, and the next request can open that recipe by name.폐쇄망의 사내 사이트는 모델이 학습한 적이 없고, 웹 검색으로 찾을 수도 없습니다. 처음에는 화면을 읽으며 길을 찾습니다. 성공한 진입 경로와 작업 순서는 이 기기의 작업 레시피로 남고, 다음 요청은 그 이름으로 엽니다.

Who it's for누구를 위한 것인가#Link to this section이 섹션 링크

• People who repeat the same reading, navigation, and form filling on sites a model has never learned.모델이 학습한 적 없는 사이트에서 같은 조회, 이동, 입력을 반복하는 사람.
• A closed network: the public internet is blocked, external SaaS is not available, only an internal model gateway is allowed, and security software may block a headless browser.폐쇄망: 인터넷이 막혀 있고 외부 SaaS는 쓸 수 없습니다. 허용된 것은 사내 LLM 게이트웨이뿐이고, 보안 소프트웨어가 headless 브라우저를 막을 수 있습니다.
• What it does inside those limits: it drives installed Edge or Chrome, sends model calls only to the URL you set, and keeps the working path locally, with the caps below.그 안에서 하는 일: 설치된 Edge나 Chrome을 움직이고, 모델 호출은 지정한 주소로만 보내며, 통한 경로는 아래 상한 안에서 이 기기에 남깁니다.

Requirements요구 사항#Link to this section이 섹션 링크

Installation설치#Link to this section이 섹션 링크

requirements-ui.txt is optional. Skip that line if you want the app-window chat instead of pywebview. Run later commands with the venv interpreter, not the system python.requirements-ui.txt는 선택입니다. pywebview 대신 앱 창을 쓰려면 그 줄을 빼세요. 이후 명령은 시스템 python이 아니라 venv의 인터프리터로 실행합니다.

WindowsWindows#Link to this section이 섹션 링크

git clone https://github.com/bamtang/nongside
cd nongside
python -m venv .venv
.venv\Scripts\python -m pip install -r requirements.txt
.venv\Scripts\python -m pip install -r requirements-ui.txt
.venv\Scripts\python main.py

macOSmacOS#Link to this section이 섹션 링크

git clone https://github.com/bamtang/nongside
cd nongside
python -m venv .venv
.venv/bin/python -m pip install -r requirements.txt
.venv/bin/python -m pip install -r requirements-ui.txt
.venv/bin/python main.py

Linux uses the same .venv/bin/python paths as macOS.Linux도 macOS와 같이 .venv/bin/python을 씁니다.

First run첫 실행#Link to this section이 섹션 링크

python main.py, using the venv interpreter above, opens the chat window. Closing the window exits. A first message can be passed as an argument and runs as soon as the window is up.위의 venv 인터프리터로 python main.py를 실행하면 챗 창이 열립니다. 창을 닫으면 끝납니다. 첫 문장을 인자로 넘기면 창이 뜨자마자 그 작업이 실행됩니다.

• With pywebview, the chat talks to Python directly and does not open an HTTP port.pywebview가 있으면 챗은 파이썬과 직접 이야기하고 HTTP 포트를 열지 않습니다.
• Without it, nongside opens an Edge or Chrome --app window. That fallback listens on 127.0.0.1 and checks a token in the window URL.없으면 Edge 또는 Chrome --app 창을 엽니다. 이 대체 경로는 127.0.0.1에서 듣고, 창 URL의 토큰을 확인합니다.
• The gear icon shows the current endpoint, model, vision model, browser, log level, and memory path. It is read-only. Change .env, the process environment, or ~/.claude/settings.json, then start again.톱니 아이콘은 현재 엔드포인트, 모델, 비전 모델, 브라우저, 로그 수준, 기억 경로를 보여 줍니다. 읽기 전용입니다. .env, 프로세스 환경 변수, 또는 ~/.claude/settings.json을 고친 뒤 다시 실행하세요.
• python main.py --selftest checks the tool schema and one agent loop without Playwright, then prints selftest ok.python main.py --selftest는 Playwright 없이 도구 스키마와 에이전트 루프 한 바퀴를 확인하고 selftest ok를 출력합니다.

Settings설정#Link to this section이 섹션 링크

A value already in the process environment wins. Next is a .env file next to the program. Anything still missing is read from the env object in ~/.claude/settings.json (endpoint, key, model, and vision model). .env is not part of the git tree. Quote marks around a value are stripped.프로세스 환경 변수가 우선입니다. 다음은 프로그램 옆의 .env입니다. 그래도 없으면 ~/.claude/settings.json의 env에서 엔드포인트, 키, 모델, 비전 모델을 읽습니다. .env는 git에 넣지 않습니다. 값 양쪽의 따옴표는 벗깁니다.

ANTHROPIC_BASE_URL=http://127.0.0.1:8080
ANTHROPIC_API_KEY=your-key
AGENT_MODEL=your-model
AGENT_CHANNEL=msedge

The example host is only a placeholder on this machine. Replace the model name with the one your gateway serves.예시 주소는 이 기기 안의 자리표시자입니다. 모델 이름은 게이트웨이가 제공하는 이름으로 바꾸세요.

Using it사용법#Link to this section이 섹션 링크

Chat window챗 창#Link to this section이 섹션 링크

The window is Korean. The hint under the composer says a risky action asks before it runs. A running task shows a Stop button, which also drops a model call that is still waiting. Confirmations are 실행 and 취소.창은 한국어입니다. 입력창 아래에는 위험한 동작이 실행 전에 확인을 받는다는 안내가 있습니다. 작업이 도는 동안 중지 버튼이 보이고, 아직 기다리는 모델 호출도 끊습니다. 확인 버튼은 실행과 취소입니다.

A chip above the composer shows the tab you are looking at. The first request in a chat pins that tab until you start a new chat. New chat clears the pin and the conversation.입력창 위 칩이 지금 보는 탭을 보여 줍니다. 대화의 첫 요청이 그 탭을 새 채팅 전까지 고정합니다. 새 채팅은 고정과 대화를 비웁니다.

• Close the chip, or send the first CLI line as /bg …, before anything is pinned: that chat stays off the current tab until a new chat.아직 고정되기 전에 칩을 닫거나, CLI 첫 줄을 /bg …로 보내면, 그 대화는 새 채팅 전까지 현재 탭을 쓰지 않습니다.
• After the tab is pinned, closing the chip applies to that request only. The next message uses the pinned tab again.이미 고정된 뒤 칩을 닫으면 그 요청만 탭 없이 처리합니다. 다음 메시지는 다시 고정된 탭을 씁니다.
• If the pinned tab is closed, the next turn continues on the tab you are looking at and says so.고정한 탭이 닫히면 다음 턴은 지금 보는 탭에서 이어지고, 그 사실을 알립니다.

Terminal터미널#Link to this section이 섹션 링크

With no flags, a terminal that is not a pipe opens the chat. --cli always uses the terminal. --ui always uses the chat, even when stdin is a pipe. If stdin is a pipe and neither flag is set, nongside uses the terminal.플래그가 없고 입력이 파이프가 아니면 챗이 열립니다. --cli는 항상 터미널입니다. --ui는 입력이 파이프여도 챗입니다. 둘 다 없고 입력이 파이프면 터미널입니다.

python main.py
python main.py "summarize this tab"
python main.py --cli
python main.py --ui
python main.py --debug
python main.py --quiet
python main.py --selftest

In --cli, exit with exit. Prefix a task with /bg to run it off the current tab, the same as closing the chip. If stdin is not a terminal, a confirmation is answered n.--cli는 exit로 끝냅니다. 작업 앞에 /bg 를 붙이면 칩을 닫은 것과 같이 현재 탭 없이 실행합니다. 표준 입력이 터미널이 아니면 확인은 n입니다.

Off-screen window화면 밖 창#Link to this section이 섹션 링크

With AGENT_BACKGROUND left at 1, a page that is not the current tab opens in a normal browser window placed at (-20000, -20000), not a headless process. The window is created the first time it is needed and then reused. Cookies are copied from the browser you are using. A cookie that does not fit is skipped on its own, so one bad cookie does not drop the rest. This is not a copy of the whole profile.AGENT_BACKGROUND가 1이면, 현재 탭에 없는 페이지는 headless가 아니라 (-20000, -20000)에 둔 일반 창에서 엽니다. 창은 처음 필요할 때 만들고 다시 씁니다. 쿠키는 사용 중인 브라우저에서 복사합니다. 형식이 안 맞는 쿠키는 그것만 건너뛰어, 하나 때문에 전부를 버리지 않습니다. 프로필 전체를 복사하는 것은 아닙니다.

• On Windows the background window is removed from the taskbar, and focus is returned if that window took it.Windows에서는 백그라운드 창을 작업 표시줄에서 빼고, 그 창이 포커스를 가져갔으면 되돌립니다.
• On macOS, off-screen coordinates are pulled back on screen, so the code hides the background browser app instead.macOS는 화면 밖 좌표를 도로 화면 안으로 가져오므로, 코드는 백그라운드 브라우저 앱을 숨깁니다.
• A popup opened from that window becomes another tab in the same window, so it does not appear on your screen. Say that you want it opened when the page should move to your tab.그 창에서 연 팝업은 같은 창의 탭이 되어 화면에 뜨지 않습니다. 사용자 탭으로 옮기려면 열어 달라고 말합니다.
• The progress log says when work ran in the background.백그라운드에서 한 일은 진행 표시에 나옵니다.

Site and task memory사이트·작업 기억#Link to this section이 섹션 링크

Memory is one local JSON file, format version 3: {"version": 3, "sites": …}. The default path is _local/memory/sites.json next to the program. There is no delete button. Delete that file to forget. If an older file was migrated, sites.v1.bak or sites.v2.bak remains beside it, and a file that could not be parsed is kept as sites.corrupt.bak. Delete those too if you want the old copy gone.기억은 로컬 JSON 파일 하나이고 형식은 버전 3입니다. {"version": 3, "sites": …}. 기본 경로는 프로그램 옆의 _local/memory/sites.json입니다. 지우는 버튼은 없습니다. 파일을 지우면 잊습니다. 옛 파일을 옮겼으면 옆에 sites.v1.bak 또는 sites.v2.bak가 남고, 읽지 못한 파일은 sites.corrupt.bak로 남습니다. 옛 사본까지 없애려면 그 파일도 지우세요.

Writes go to a temporary file and then replace the real file, so a crash mid-write does not leave a half-written JSON.저장은 임시 파일에 쓴 뒤 실제 파일을 교체하므로, 쓰는 도중 죽어도 JSON이 반쪽로 남지 않습니다.

What it keeps저장하는 것#Link to this section이 섹션 링크

• A site name, up to 8 aliases, a home URL, and up to 8 URL fragments used to recognize the site.사이트 이름, 별칭 최대 8개, 홈 URL, 사이트를 알아보는 URL 조각 최대 8개.
• Up to 5 notes. A key is at most 30 characters and a value at most 300. Notes are short constraints, such as a login being required.메모 최대 5개. 키는 30자, 값은 300자까지. 메모는 로그인이 필요하다 같은 짧은 제약입니다.
• Up to 20 tasks per site. A task stores the kind (read or act), the entry URL, the labels clicked to get there, the later steps, a check URL, a success count, a consecutive-failure count, and the last success date. Search slots in a URL look like {q}. Typed text is stored as a field-label placeholder, not the characters you typed.사이트당 작업 최대 20개. 작업에는 종류(읽기 또는 조작), 진입 URL, 거기까지 누른 라벨, 그 뒤의 단계, 확인 URL, 성공 횟수, 연속 실패 횟수, 마지막 성공 날짜가 있습니다. URL의 검색 자리는 {q} 꼴입니다. 입력한 글은 저장하지 않고 칸 이름 자리만 남깁니다.
• A use count and a last-used time, for the eviction score.퇴출 점수에 쓰는 사용 횟수와 마지막 사용 시각.

What it drops저장하지 않는 것#Link to this section이 섹션 링크

• The page body, query results, and the text you typed.글 본문, 조회 결과, 입력한 글.
• A note that looks like a selector, code, a URL, a price, or a date. That note is discarded. The rest of the site is still saved.셀렉터, 코드, URL, 가격, 날짜처럼 보이는 메모. 그 항목만 버리고, 사이트의 나머지는 저장합니다.
• A recipe opened by name is not saved as a success if the turn ends without done: cancel, a repeat block, the step cap, or Stop. Its consecutive-failure count goes up instead. A read that lands on a single article URL is not stored as the entry.이름으로 연 레시피는 done 없이 끝나면(취소, 반복 차단, 스텝 상한, 중지) 성공으로 저장하지 않고 연속 실패만 올립니다. 글 하나의 URL에 도착한 읽기는 진입으로 저장하지 않습니다.

Caps: 50 sites, 20 tasks and 5 notes each, 8 aliases, 8 match fragments, keys of 30 characters, values of 300. Past 50 sites, the lowest score is dropped. The score is uses times recency, with a 30-day half-life. A recipe that fails twice in a row is hidden until it is found again. Replaying a recipe still asks before a risky click.상한: 사이트 50, 사이트당 작업 20·메모 5, 별칭 8, 주소 조각 8, 키 30자, 값 300자. 50곳을 넘으면 점수가 가장 낮은 사이트를 버립니다. 점수는 사용 횟수와 최근성을 곱하고, 반감기는 30일입니다. 연속 두 번 실패한 레시피는 다시 찾을 때까지 숨깁니다. 재생 중에도 위험한 클릭은 매번 묻습니다.

Tool reference도구 레퍼런스#Link to this section이 섹션 링크

Seventeen tools. The observation list is capped at 300 elements and looks like [i] <tag> "label", with markers for a collapsed control, a popup, a hidden menu, an autocomplete candidate, and select options.도구는 17개입니다. 관찰 목록은 요소 300개까지이고 [i] <tag> "label" 꼴입니다. 접힘, 팝업, 숨은 메뉴, 자동완성 후보, select 옵션이 표시로 붙습니다.

A turn stops at 25 steps. The same action three times inside the last 10 steps is blocked, and five such blocks end the turn with a summary. run_code may fail twice per turn before another script is refused.한 턴은 25스텝에서 멈춥니다. 최근 10스텝 안에 같은 동작이 세 번이면 막고, 그런 차단이 다섯 번이면 요약으로 끝냅니다. run_code는 한 턴에 두 번 실패하면 새 스크립트를 더 실행하지 않습니다.

Safety and limits안전 설계와 한계#Link to this section이 섹션 링크

Confirmation is a keyword check, not a policy engine. It looks at the click label, and, for run_code, at the target of an actual click or submit. Comments and print text do not count. Words such as delete, send, pay, submit, and the matching Korean verbs ask first. Some menu-title phrases are removed before the check, so a word inside a menu name does not by itself open a prompt. A label that is only clearing a search box can pass. A real destructive control can pass too. Typing into a field is not asked.확인은 정책 엔진이 아니라 키워드 검사입니다. 클릭 라벨을 보고, run_code에서는 실제로 클릭하거나 제출하는 대상을 봅니다. 주석과 print 문구는 세지 않습니다. 삭제, 전송, 결제, 제출 같은 말과 그에 해당하는 영어 단어는 먼저 묻습니다. 일부 메뉴 이름 구절은 검사 전에 지워서, 메뉴 이름 안의 단어만으로 묻지 않습니다. 검색창을 비우는 라벨은 통과할 수 있고, 진짜로 되돌리기 어려운 버튼도 통과할 수 있습니다. 칸에 입력하는 것은 묻지 않습니다.

• A typed password is shown as **** in the log. On the settings screen, an API key longer than 8 characters shows only its last 4. Page text still goes to the model.입력한 비밀번호는 로그에서 ****입니다. 설정 화면의 API 키는 8자를 넘으면 끝 4자리만 보입니다. 페이지 내용은 모델로 갑니다.
• A frame that contains a filled password or one-time-code field is read as text, not as an accessibility snapshot. run_code output has those current values removed.값이 들어 있는 비밀번호·일회용 코드 칸이 있는 프레임은 접근성 스냅샷 대신 텍스트로 읽습니다. run_code 출력에서는 그 칸의 현재 값을 지웁니다.
• Attaching to a debug port only disconnects on exit. A browser nongside launched itself is closed with the app.디버그 포트에 붙었으면 종료 때 연결만 끊습니다. nongside가 직접 띄운 브라우저는 함께 닫힙니다.
• There is no OS sandbox and no network policy in this app. A CDP port that answers is attached to, whatever process owns it.이 앱에는 OS 샌드박스도 네트워크 정책도 없습니다. 응답하는 CDP 포트에는 그 프로세스가 무엇이든 붙습니다.
• Captchas, two-factor prompts, certificate choices, and the browser’s own dialogs are handed back with ask_user.캡차, 2단계 인증, 인증서 선택, 브라우저 창 자체의 대화는 ask_user로 사람에게 넘깁니다.
• A model call is tried up to 3 times. Connection errors wait 1, then 2, then 4 seconds. HTTP 429, 500, 502, 503, and 529 are retried the same way, or for the seconds in Retry-After, capped at 10. A 120 second timeout is not retried.모델 호출은 최대 3번입니다. 연결 오류는 1초, 2초, 4초를 기다립니다. HTTP 429, 500, 502, 503, 529도 같이 재시도하고, Retry-After가 있으면 그 초를 따르되 10초를 넘기지 않습니다. 120초 시간 초과는 재시도하지 않습니다.

Troubleshooting문제 해결#Link to this section이 섹션 링크

The wrong browser opens다른 브라우저에 붙음#Link to this section이 섹션 링크

If 127.0.0.1:9222 already answers, nongside attaches to that process and will not show a new window of its own. Set AGENT_CDP_PORT to a port nothing else is using, then start again.127.0.0.1:9222가 이미 응답하면 nongside는 그 프로세스에 붙고, 자기 창을 새로 띄우지 않습니다. AGENT_CDP_PORT를 아무도 쓰지 않는 포트로 바꾼 뒤 다시 실행하세요.

Profile directory프로필 디렉터리#Link to this section이 섹션 링크

A launched browser uses .edge-profile in the current working directory, unless AGENT_PROFILE says otherwise. Give a second copy its own directory and its own AGENT_CDP_PORT. Attaching does not create that profile; it joins the browser already on the port.직접 띄우는 브라우저는 AGENT_PROFILE이 없으면 현재 작업 디렉터리의 .edge-profile을 씁니다. 두 번째로 띄울 때는 디렉터리와 AGENT_CDP_PORT를 따로 주세요. 붙기 모드는 그 프로필을 만들지 않고, 포트에 이미 있는 브라우저에 합류합니다.

Chrome instead of EdgeEdge 대신 Chrome#Link to this section이 섹션 링크

The default channel is msedge. Where Edge is not installed, set AGENT_CHANNEL=chrome. The chat window is chosen separately with AGENT_UI_BROWSER.기본 채널은 msedge입니다. Edge가 없으면 AGENT_CHANNEL=chrome입니다. 챗 창은 AGENT_UI_BROWSER로 따로 고릅니다.

A headless browser is blockedheadless 브라우저가 막힘#Link to this section이 섹션 링크

The background window is not started with --headless. It is a normal window moved off screen, for environments where security software blocks a headless browser. If that window is still blocked, set AGENT_BACKGROUND=0 and work stays on the current tab.백그라운드 창은 --headless로 시작하지 않습니다. 보안 소프트웨어가 headless 브라우저를 막는 환경을 위해, 일반 창을 화면 밖에 둡니다. 그 창도 막히면 AGENT_BACKGROUND=0으로 현재 탭에서만 작업합니다.

The chat window챗 창#Link to this section이 섹션 링크

AGENT_UI_BROWSER=webview exits with an error if pywebview is not installed. Leave the variable empty to fall back to an app window, or install requirements-ui.txt inside the venv.AGENT_UI_BROWSER=webview는 pywebview가 없으면 오류로 끝납니다. 변수를 비우면 앱 창으로 내려가고, 네이티브 창이 필요하면 venv 안에서 requirements-ui.txt를 설치하세요.

FAQFAQ#Link to this section이 섹션 링크

License라이선스#Link to this section이 섹션 링크

nongside is released under the MIT License.nongside는 MIT License로 배포됩니다.

Edit on GitHubGitHub에서 편집 MIT License