Agentty/문서

원격 접속

다른 기기의 브라우저에서 Tailscale 네트워크로 Agentty 워크스페이스를 열기.

원격 접속을 켜면 휴대폰, 태블릿, 다른 컴퓨터 같은 다른 기기의 브라우저에서 Agentty 워크스페이스를 열 수 있습니다. 내 Tailscale 네트워크 안에서 터미널 세션을 보고 명령을 직접 입력하고 에이전트에게 프롬프트를 보냅니다.

화면에 보이는 것#

페이지는 Agentty 앱과 같은 구성입니다.

  • 홈 — 페이지를 열면 처음 나오는 화면입니다. 답을 기다리는 터미널 수와 작업 중인 터미널 수가 나오고, 기다리는 터미널마다 무엇을 묻는지도 보입니다. 작업 중인 에이전트, 모든 워크스페이스(쉬는 것 포함), 플러그인과 그 상태도 한눈에 볼 수 있습니다. 터미널이나 워크스페이스를 누르면 그리로 갑니다. ☰ 메뉴 맨 위의 홈으로 돌아옵니다.
  • ☰ 메뉴 — 그룹과 워크스페이스가 사이드바와 같은 순서·색으로 나오고 브랜치와 폴더도 함께 보입니다. 빨간 숫자는 그 워크스페이스에서 답을 기다리는 터미널 수입니다. 넓은 화면에서는 왼쪽에 항상 펼쳐져 있습니다.
  • 탭 — 고른 워크스페이스의 탭이 위에 나란히 나옵니다. 점은 작업 중이거나 답을 기다리는 탭, ▥2는 분할창 2개로 나뉜 탭입니다.
  • 분할창 — 탭이 나뉘어 있으면 오른쪽 위 버튼으로 분할창 목록을 엽니다. 창마다 상태와 요청이 보이고, 누르면 그 창으로 전환합니다.
  • 터미널 — 가운데에 고른 창의 실시간 화면이 나옵니다.
  • 채팅 작업공간 — 채팅 작업공간은 채팅으로 열립니다. 대화, 요금제 사용량, 리드에게 쓰는 입력창이 보이고, 터미널로 리드의 터미널로 바꿀 수 있습니다.
  • 출력 속 파일 — 터미널이나 채팅에 나온 파일 경로(shots/home.png, NOTES.md, src/app.ts)에 밑줄이 그어지고, 누르면 페이지 위 뷰어에서 파일마다 탭으로 열립니다. 그림은 그대로, Markdown은 렌더링해서, 다른 텍스트는 텍스트로 보여 주고, PDF는 새 탭에서 열립니다. 그 터미널의 프로젝트 폴더 안 파일만 열리며, 숨김 파일(.env, .git 등)과 키 파일은 열리지 않습니다.

새 탭 — 탭 끝의 +(또는 홈의 워크스페이스 옆 +)를 누르면 그 워크스페이스에 터미널, Claude Code, Codex 중 하나로 새 탭을 엽니다. 새 탭은 워크스페이스 폴더에서 시작하고, 페이지도 그 탭으로 넘어갑니다.

새 워크스페이스 — 홈의 워크스페이스 목록 아래나 ☰ 메뉴에 있는 + 새 작업공간을 누르면 Mac의 ~/AgenttyRemote 안에 있는 폴더에서 새 워크스페이스를 터미널, Claude Code, Codex 중 하나로 엽니다. 폴더를 둘러보거나 새로 만든 뒤 시작할 도구를 고르면 페이지가 그 워크스페이스로 넘어갑니다. 웹에서는 ~/AgenttyRemote 밖의 폴더에 접근할 수 없습니다. 이 폴더는 처음 쓸 때 Agentty가 만들고, 원격 접속 페이지의 Finder에서 보기로 Mac에서 열 수 있습니다.

쉬는 워크스페이스 — Agentty에서 쉬고 있는 워크스페이스에는 깨우기가 나옵니다. 누르면 저장된 탭이 다시 시작되고 페이지에 나옵니다. 새 탭을 열거나 깨워도 Mac 화면에 보이는 것은 바뀌지 않습니다.

플러그인 — 홈에 설치된 플러그인과 상태(실행 중, 멈춤, 오류로 멈춤), 각 자동화가 지금 하는 일이 나옵니다. 보여 주기만 합니다. 플러그인 워크스페이스는 페이지에서 열리지 않고, 페이지에서 플러그인을 켜거나 끌 수 없습니다.

화면의 키 막대로 터미널에 직접 입력할 수 있습니다. Esc, Tab, Shift+Tab, 화살표, Enter, Ctrl+C, 고정되는 Ctrl 키가 있고, 에이전트가 답을 요청하면 빠른 버튼(1/2/3)도 나옵니다. 아래 상자에서 프롬프트를 보내도 됩니다. 컴퓨터에서는 Enter로 보내고 Shift+Enter로 줄을 추가합니다.

이미지 — 입력 상자 옆 그림 버튼으로 사진이나 스크린샷을 첨부합니다. 상자에 붙여 넣거나 끌어다 놓아도 됩니다. 첨부한 이미지는 다음 프롬프트와 함께 갑니다. Mac에서 터미널에 끌어다 놓은 것과 같아서 Claude Code나 Codex가 이미지로 봅니다. 큰 사진은 휴대폰에서 먼저 줄여서 보냅니다. Mac은 이미지를 Agentty 데이터 폴더에 일주일 동안 보관하고, 본인만 읽을 수 있습니다.

페이지의 알림 받기를 누르면 다른 일을 하는 동안 세션이 끝나거나 무언가 물을 때 브라우저 알림이 옵니다.

웹에서 터미널을 보는 동안에는 터미널 크기가 웹 화면에 맞춰집니다. 화면에 들어가는 만큼만 칸과 줄을 쓰므로 줄이 꺾이거나 옆으로 스크롤되지 않습니다. A− / **A+**로 글자 크기를 바꿀 수 있습니다(기기마다 기억). 그 터미널을 보는 페이지가 하나도 없으면 앱에서의 원래 크기로 돌아갑니다. 이 페이지를 홈 화면에 앱으로 추가할 수 있습니다.

Slack·Discord·Telegram 알림을 설정해 두었다면(설정 → 연동), 원격 접속이 켜져 있는 동안 메시지 아래에 **바로 확인하기: <주소>**가 붙습니다. 이 주소를 열면 Tailscale과 웹 비밀번호 확인을 거친 뒤 그 터미널이 바로 열립니다. 이 주소에는 Mac과 tailnet 이름이 들어 있어서 에이전트 질문 내용 포함을 켰을 때만 보냅니다.

필요한 것#

다음이 필요합니다.

  • Tailscale Mac에 설치되고 연결되어 있음 (다른 기기도 같은 Tailscale 계정으로 로그인)
  • MagicDNS와 HTTPS 인증서 tailnet에 활성화됨 (Tailscale 관리 콘솔 → DNS)
  • Tailscale Serve tailnet에서 허용됨 — 그렇지 않으면 Agentty가 켜기 버튼을 보여줍니다

설정하기#

  1. 사이드 메뉴의 원격 접속(지구본과 모니터 아이콘) 열기
  2. 웹 비밀번호 설정 (영문·숫자·기호로 12자 이상, 두 번 입력. 눈 아이콘을 누르면 입력한 비밀번호가 보입니다)
  3. 켜기 전에 준비할 것에서 인증서 발급 누르기: Tailscale이 이 컴퓨터의 HTTPS 인증서를 받습니다 (컴퓨터마다 한 번, 처음에는 1분쯤 걸릴 수 있고 갱신은 Tailscale이 알아서 합니다)
  4. 원격 접속 켜기 켜기 — 켜기 전에 준비할 것의 단계가 모두 체크되어야 켜집니다
  5. 나타난 주소 복사 (https://<machine>.<tailnet>.ts.net:8743/) 또는 열기를 탭해 바로 이동
  6. 다른 기기에서 웹 비밀번호로 로그인

끝입니다. 이제 그 기기에서 세션이 보입니다.

Tailscale이 감지되지 않을 때#

켜기 전에 준비할 것의 첫 단계에 무엇이 문제인지와 해결 버튼이 나옵니다. 화면이 자동으로 다시 확인하므로 해결되면 따로 누를 것이 없습니다.

나오는 문구할 일
설치되어 있지 않음Tailscale 받기. 방금 설치했다면 앱을 한 번 여세요.
이 Mac에서 꺼져 있음Tailscale 열기를 누르고 Connect를 켜세요. macOS가 VPN 추가나 시스템 확장 허용을 물으면 허용하세요.
로그인되어 있지 않음로그인하기. 휴대폰에서도 쓸 계정으로 로그인하세요.
승인을 기다리는 중Machines 페이지에서 이 기기를 승인하거나 tailnet 관리자에게 부탁하세요.
백그라운드 서비스가 응답하지 않음Tailscale을 열어 처음 설정을 끝내세요. Mac은 시스템 설정 → 일반 → 로그인 항목 및 확장 프로그램에서 시스템 확장을 허용하고, Windows는 컴퓨터를 다시 시작하세요. Linux는 sudo systemctl enable --now tailscaled와 sudo tailscale up을 실행하세요.
macOS가 허용을 기다림시스템 설정 → 일반 → 로그인 항목 및 확장 프로그램 → 네트워크 확장에서 Tailscale을 켜세요.
다른 VPN이 막고 있을 수 있음화면에 나온 VPN을 끊은 뒤 Tailscale에서 Connect를 켜세요.
이 Mac 계정에 권한이 없음Tailscale 접근 파일은 관리자 계정만 읽을 수 있습니다. 관리자 계정을 쓰거나 시스템 설정 → 사용자 및 그룹에서 이 계정에 관리자 권한을 주세요.
Tailscale이 이 계정을 거부함Linux는 sudo tailscale set --operator=$USER를 한 번 실행하세요. Windows는 다른 계정이 Tailscale을 쓰고 있을 수 있습니다. 회사에서 관리하는 Mac은 정책이 막고 있을 수 있습니다.
응답을 읽지 못함Tailscale을 종료했다가 다시 열거나 업데이트하세요. Tailscale이 낸 오류 문구가 안내 아래에 함께 나옵니다.

그래도 안 되면 에이전트에게 맡기기를 누르세요. 찾은 내용을 전달받은 에이전트가 새 탭에서 먼저 확인만 하고, 무언가 바꾸기 전에는 물어봅니다. 진단 내용 복사는 같은 요약을 복사해 질문에 붙여 넣을 수 있게 합니다. 버전과 상태만 들어 있고 계정, 기기, tailnet 이름은 들어 있지 않습니다.

어떤 계정이어야 하나요? Tailscale 계정이면 무엇이든 됩니다. Apple 계정이나 컴퓨터 사용자 계정과 같을 필요는 없습니다. 같아야 하는 것은 이 컴퓨터와 접속할 기기의 Tailscale 계정입니다.

보안#

원격 접속은 Tailscale 네트워크 안에서만 열리고 공개 인터넷으로는 절대 나가지 않습니다. Agentty의 포트에 Funnel이 켜져 있으면 실행을 거부합니다. 접속하려면 아래 두 가지를 모두 통과해야 합니다.

  1. Tailscale 계정 — 이 Mac의 주인 계정만 들어올 수 있습니다. 같은 tailnet을 함께 쓰는 다른 사람이나 태그된 기기는 거부됩니다.
  2. 웹 비밀번호 — 원격 접속 화면에서 정한 비밀번호.

다른 사람의 Tailscale 계정은 같은 tailnet 안에 있어도 들어올 수 없습니다. 내 Tailscale 계정으로 로그인된 기기에서 웹 비밀번호까지 맞혀야 터미널에 입력할 수 있습니다. 터미널에 입력할 수 있다는 것은 Mac에서 명령을 실행할 수 있다는 뜻입니다. 그러니 웹 비밀번호는 혼자만 알고 다른 곳에서 쓰지 않는 것으로 정하세요. 필요 없을 때는 원격 접속을 꺼 두세요.

Agentty의 페이지에는 Tailscale만 닿을 수 있습니다. Agentty는 Tailscale의 serve만 들어올 수 있는 곳에서 대기합니다. Tailscale이 열 수 있으면 전용 소켓을 쓰고, 아니면 Tailscale에게만 알려 준 비밀 경로가 붙은 로컬 포트를 씁니다. 그래서 Mac 안의 다른 프로그램이나 다른 사용자 계정은 직접 들어올 수 없습니다. 페이지는 Tailscale이 켜져 있는 동안에만 동작합니다. Tailscale이 끊기거나 로그아웃되거나 종료되면 몇 초 안에 페이지를 내리고, 다시 연결되면 자동으로 다시 엽니다. 켜져 있는 동안에는 30초마다(그리고 Mac이 잠자기에서 깨어날 때) Tailscale을 거쳐 페이지가 응답하는지도 확인합니다. 응답이 없으면 끄고 다시 켠 것처럼 원격 접속을 스스로 다시 시작하고, 페이지에서는 웹 비밀번호를 다시 입력합니다.

로그인 실패에는 속도 제한이 있습니다. 비밀번호를 5번 틀리면 1분간 잠깁니다. 잠긴 뒤로는 틀릴 때마다 대기 시간이 2배로 늘어나며 최대 1시간입니다. 기기가 로그인할 때와 페이지가 잠길 때 데스크톱 알림이 옵니다. 내가 틀린 게 아닌데 잠겼다면 원격 접속 화면의 잠금 해제로 바로 풀 수 있습니다.

비밀번호는 시스템 키체인에 해시로만 저장됩니다. 로그인은 최대 7일(유휴 상태로는 12시간) 유지됩니다. Agentty를 종료하거나, 비밀번호를 바꾸거나, 모든 기기 로그아웃을 탭하면 모든 기기가 한 번에 로그아웃됩니다.

깨어 있게 하기#

원격 접속이 켜져 있는 동안 Agentty는 Mac이 유휴 절전에 들어가지 않게 막아 계속 접속할 수 있게 합니다. 디스플레이는 꺼질 수 있습니다. 원하면 이 기능을 끌 수 있습니다.

절전 중인 Mac이나 덮개를 닫은 노트북에는 접속할 수 없습니다.

원격 접속은 재시작해도 끌 때까지 켜진 상태로 남습니다. Tailscale 포트 8743을 쓰며, Tailscale로 서비스하는 다른 것에는 영향을 주지 않습니다. 포트 8743을 이미 다른 것이 쓰고 있으면 Agentty가 오류를 보여 줍니다.

Mac 앱에서 음성 입력#

앱 안에서도 바로 말로 지시할 수 있습니다. 마이크는 에이전트 탭(Claude Code, Codex 등)과 채팅에만 나옵니다. 일반 셸에서는 말로 한 프롬프트를 쓸 데가 없으니까요. 에이전트 CLI에도 자체 음성 기능이 있습니다. Claude Code의 /voice는 입력창에 받아씁니다(Space 길게 누르기). 음성은 Anthropic 서버에서 변환되며 claude.ai 로그인이 필요합니다. Codex의 /voice는 받아쓰기가 아니라 Codex가 말로 답하는 음성 대화입니다. Agentty의 마이크는 어느 에이전트에서든, 채팅과 원격 페이지에서도 똑같이 동작하며 음성을 Mac 밖으로 보내지 않습니다. 상태바 오른쪽 끝의 마이크를 누르거나 ⇧⌘M을 누르고 말하세요. 듣는 동안 상태바에 녹음 중 0:05와 음량 막대가 보입니다.

  • ⏎ Enter — 멈추고 말한 내용을 터미널에 바로 프롬프트로 전송합니다.
  • 마이크 다시 클릭 또는 ⇧⌘M — 멈추고 입력만 해 둡니다. 확인하거나 고친 뒤 직접 전송하세요.
  • Esc — 녹음을 취소합니다.

내용은 녹음을 시작할 때 활성화돼 있던 터미널에 들어갑니다. 언어는 말소리로 자동 감지하므로 한국어, 영어, 섞어 말하기 모두 됩니다. 처음 한 번은 macOS가 마이크 권한을 묻습니다. 권한을 꺼 두었다면 Agentty가 시스템 설정의 마이크 화면을 열어 줍니다. 모델이 아직 없으면 마이크를 눌렀을 때 그 자리에서 모델 설치 화면(아래와 같은 것)이 열립니다.

음성으로 프롬프트 보내기#

원격 페이지에서는 타이핑 대신 음성으로 프롬프트를 보낼 수 있습니다. 프롬프트 입력창의 마이크를 누르고 말한 뒤 다시 누르면 멈춥니다. 변환된 문장이 입력창에 들어가니 확인하고 전송하면 됩니다.

음성은 이 Mac에서 로컬 모델로 변환되며 외부 서비스로는 아무것도 보내지 않습니다. 모델은 설정 → 음성 입력에서 한 번만 설치하면 됩니다(원격 접속 화면에도 같은 카드가 있습니다). Large-v3 Turbo(추천, 약 574MB)나 더 가벼운 Small(약 488MB)을 고르세요. 모델은 Mac에 내려받아 검증한 뒤 보관하고, 변환은 Mac의 GPU에서 합니다. 같은 곳에서 말하는 언어(자동·한국어·영어)를 고르고, 설치된 모델 중 무엇을 쓸지 정하고, 모델을 삭제할 수 있습니다. 자동 감지는 짧은 말을 다른 언어로 잘못 알아들을 때가 있습니다. 모델을 설치하면 원격 페이지에 마이크 버튼이 저절로 나타납니다.

브라우저가 처음에 마이크 권한을 묻습니다. 페이지는 HTTPS로 제공되어야 하는데, Tailscale을 거치므로 HTTPS로 제공됩니다.

개발 서버#

작업공간의 터미널에서 로컬 서버(npm run dev, rails s, 정적 사이트 미리보기 등)를 실행하면, 페이지의 작업공간 탭 아래에 그 포트가 ↗ localhost:3000처럼 나타납니다. 누르면 새 브라우저 탭에서 https://<machine>.<tailnet>.ts.net:3000/으로 서버가 열립니다. 페이지와 같은 주소에 서버의 포트를 붙인 주소입니다. 처음에는 Tailscale이 포트를 준비하느라 몇 초 걸립니다.

페이지와 마찬가지로 본인만 들어갈 수 있습니다. 그 주소는 Agentty가 직접 받아서, 본인의 Tailscale 계정이면서 웹 비밀번호로 로그인한 기기에서 온 요청만 서버에 넘깁니다(먼저 페이지에서 로그인하세요). 서버는 요청을 localhost:<포트>로 온 것으로 보며, Agentty 로그인 정보는 받지 않습니다. Mac의 브라우저에서 여는 것과 똑같이 동작하고, 핫 리로드도 됩니다.

서버가 멈추거나, 원격 접속을 끄거나, Agentty를 종료하면 주소도 사라집니다. Tailscale이 이미 다른 용도로 쓰는 포트나 Funnel로 공개된 포트는 열지 않고, 페이지에서 이유를 알려 줍니다.

휴대폰 앱에서 보낸 작업공간#

Agentty Remote 앱으로 휴대폰에서 작업공간을 보낼 수 있습니다. 보낸 작업공간은 자기 이름으로, 따로 만든 그룹 안에 열립니다. 함께 보낸 파일은 작업공간 폴더의 .agentty-remote/ 아래에 저장되며 git에는 들어가지 않습니다. 원격 접속 페이지의 로그인한 기기에는 앱으로 로그인한 휴대폰이 브라우저 이름 대신 Agentty Remote로 나옵니다.

앱에서는 작업공간을 잠재우고, 탭을 닫고(분할된 창까지 함께 닫히며, 닫은 탭에서 다시 열 수 있습니다), 작업공간을 휴지통으로 옮길 수도 있습니다. 휴대폰에서 한 일로 무언가가 완전히 지워지지는 않습니다. 앱으로 휴지통에 옮긴 작업공간은 워크트리와 동기화 데이터를 그대로 두며, 다른 항목처럼 휴지통에서 되살릴 수 있습니다.

휴대폰 앱에서 채팅과 오케스트레이션#

Agentty Remote 앱은 페인을 채팅으로 보여 주고 오케스트레이션을 따라갈 수 있습니다. 로그인과 확인 절차는 페이지와 같습니다. 휴대폰에서 채팅을 골라도 Mac에서 페인이 보이는 방식은 바뀌지 않습니다. 휴대폰에서 오케스트레이션을 시작하거나 다시 시작해도 Mac은 보고 있던 작업공간에 그대로 있고, 토스트로 알려 줍니다.

원격 접속에서 뺀 작업공간과 그 안의 오케스트레이션은 나타나지 않습니다. 휴대폰에서 시작한 오케스트레이션은 ~/AgenttyRemote 아래 폴더에서 일하고, Mac의 대화상자처럼 목표에 적힌 링크나 파일을 먼저 읽지 않습니다. 에이전트는 목표만 받습니다.

대화에는 에이전트가 읽고 출력한 것이 모두 들어 있습니다. Mac을 떠나기 전에 홈 폴더는 ~로 줄이고, 알려진 형식의 자격 증명처럼 보이는 글자는 가립니다. 흔한 형식만 잡아내므로 모든 것을 가려 준다고 생각하지 마세요. 터미널과 같은 세션입니다.

기능 숨기기#

원격 접속을 쓰지 않는다면 설정 → 일반 → 원격 접속 기능 사용을 끄거나(기본값은 켜짐), 원격 접속 화면의 원격 접속 비활성 버튼을 누르세요. 사이드 메뉴에서 아이콘이 사라지고 원격 접속도 꺼집니다. 다시 쓰려면 그 설정을 켜면 됩니다.

특정 작업공간만 웹에서 빼고 싶다면 그 작업공간 카드의 메뉴(우클릭)에서 원격 접속에서 숨기기를 고르세요. 웹 페이지 목록에서 사라지고 그 터미널에도 접근할 수 없습니다.

문제 해결#

Tailscale이 연결되지 않음 Mac의 Tailscale 앱에서 연결하세요.

HTTPS 인증서가 꺼짐 Tailscale 관리 콘솔(DNS 설정)에서 MagicDNS와 HTTPS를 활성화하세요. 그러면 tailnet 도메인용 인증서가 만들어집니다.

켜지 못했습니다: Tailscale can't reach Agentty's page 이 컴퓨터의 HTTPS 인증서가 아직 없었던 경우가 많습니다. 원격 접속을 끄고 인증서 발급을 누른 뒤 다시 켜세요.

Serve가 꺼짐 Agentty 설정에 Serve를 켜는 버튼이 나옵니다. 누르면 Tailscale 관리 콘솔이 열립니다.

이 Tailscale 계정은 이 Agentty를 사용할 수 없음 (로그인 화면에 표시됨) 다른 기기가 다른 Tailscale 계정으로 로그인되어 있습니다. Mac과 같은 계정으로 로그인하세요.

화면에 잠김이라고 표시됨 (로그인 양식 대신 표시됨) 본인이나 다른 누군가가 비밀번호를 5번 잘못 입력했습니다. 잠시 기다리거나 원격 접속 → 최근 접속 기록에서 무슨 일이 있었는지 확인하세요. 본인이 한 게 아니라면 Mac의 원격 접속 화면에서 잠금 해제를 누르세요.