서버의 에이전트,
Mac에서 응답.

Gnista의 설정 ▸ 원격에서 ‘연결’을 클릭하고 ssh 설정에 있는 호스트를 고르세요. Gnista가 그곳에 헬퍼를 복사하고, 찾은 에이전트를 모두 연결한 뒤, 평소 쓰는 ssh로 연결 하나를 열어 둬요. 세션은 머신 이름과 함께 노치에 보여요.

• Mac에 Gnista, macOS 15 이상.
• x86_64나 arm64 Linux 서버, 또는 원격 로그인을 켠 Mac.
• 그곳에 로그인하는 사용자 계정에 설치된 에이전트: Claude Code, Codex, Gemini CLI, OpenCode, Copilot CLI, 그 밖에 Gnista가 Mac에서 연결하는 어떤 에이전트든.
• ~/.ssh/config에 있는 머신. 아무것도 묻지 않는 키가 가장 편해요. 로그인에 암호, 코드, 키 승인이 필요하면 Gnista가 Terminal에서 한 번 물어요.

이런 항목 하나면 충분해요. Gnista는 설정에 적힌 것을 모두 그대로 써서, 포트, 사용자, 키, ProxyJump, 그리고 Coder, Codespaces, DevPod가 추가한 호스트도 Terminal에서처럼 작동해요.

Host devbox
  HostName devbox.example.com
  User dev
  IdentityFile ~/.ssh/id_ed25519

ssh devbox uname -sm

Linux x86_64, Linux aarch64, Darwin arm64 중 하나가 출력되면 돼요. ssh가 호스트 키를 신뢰할지 물으면, 거기서 한 번 답하세요.

1. Gnista의 설정 ▸ 원격를 여세요. ‘연결’을 클릭하고 호스트(여기서는 devbox)를 고르세요. 설정에 없는 호스트라면 ‘다른 호스트…’를 고르고 입력하세요.
2. Gnista가 uname으로 시스템을 확인하고, 그 시스템용 헬퍼를 그곳의 ~/.gnista에 복사한 뒤, 바뀌지 않고 도착했는지 확인해요. 그다음 찾은 에이전트 각각에 훅을 추가해요.
3. 머신의 줄에 몇 개를 연결했는지 나와요. 예를 들면 “연결됨, 에이전트 2개”. 마우스를 올리면 이름이 보여요.
4. 줄에 “로그인이 필요합니다.”라고 나오면 ‘로그인’을 클릭하세요. Terminal이 열리고 한 번 로그인하면, Gnista의 연결은 그 로그인을 거쳐요.
5. 서버에서 세션을 시작하세요. 노치에 그 줄이 생기고, 프로젝트 옆에 서버 이름이 보여요.

• 세션마다 한 줄. 로컬 줄에 앱이 보이는 자리에 머신 이름이 보여요. 마우스를 올리면 “devbox에서 실행 중(SSH)”.
• 노치에 오는 요청. 에이전트가 물으면, 로컬 세션처럼 노치가 요청과 함께 열려요. 설정 ▸ 일반 ▸ ‘Gnista에서 권한 요청에 응답’이 켜져 있으면 거기서 응답해요. Gnista가 이 설정을 서버에도 맞춰 둬요.
• 세부 정보. 제목, 최근 메시지, 토큰과 비용. 기록을 남기는 에이전트라면 서버에서 읽어 와요.
• 맞는 탭. 클릭하면 에이전트가 들어온 ssh, mosh, Eternal Terminal이 열려 있는 Mac의 터미널 탭으로 이동하고, 그 안의 tmux 페인까지 띄워요. VS Code, Cursor, Windsurf, Zed의 원격 윈도우라면 그 윈도우로, Claude Desktop이 SSH로 시작한 세션이라면 그 채팅으로 이동해요.
• 로그인은 한 번. 설정, 연결, 클릭이 모두 ssh 연결 하나를 함께 써서, Duo 푸시나 키 승인은 매번이 아니라 한 번만 와요.
• 다시 이어지는 연결. 연결이 끊기거나, 잠자기나 네트워크 변경 뒤에도 Gnista가 알아서 다시 연결해요. 그동안 줄은 그대로 있고, 머신에는 “지금은 연결할 수 없습니다.”라고 나와요.

머신마다 ⋯ 메뉴에 ‘연결’ 설정이 있어요. 대부분의 서버에는 ‘자동’이 맞아요. ‘포워딩 없이’는 훅의 메시지를 포워딩 대신 평범한 ssh 명령으로 보내요. ‘내 ssh로’는 Gnista가 따로 연결을 열지 않아요. ‘설정’을 누르면 헬퍼를 한 번 설치하고 ssh 설정에 넣을 RemoteForward 줄을 알려 줘서, 내 ssh 세션이 에이전트의 이벤트를 실어 날라요. IT 팀용: 보안과 개인정보.

각 Mac에서 같은 서버를 연결하세요. 서버에는 Mac마다 소켓이 따로 생기고, 모든 Mac에 그 세션이 보이며, 요청에는 먼저 온 응답이 적용돼요. 한 Mac에서 ‘연결 해제’해도 다른 Mac을 위해 Gnista는 서버에 남아요.

연결이 시작될 때마다 Gnista가 이것들을 최신으로 맞춰요. Gnista가 업데이트되면 새 헬퍼를, 그사이 설치한 에이전트가 있으면 그 훅을요. Gnista가 훅을 추가하기 전에 에이전트 설정을 백업하고, 직접 넣은 훅은 그대로 남아요.

Gnista는 머신마다 Mac에 소켓을 하나 열고, 그 소켓으로 리버스 포워딩하는 ssh를 실행해요. 그래서 그곳의 훅은 그 연결을 거쳐 Mac의 Gnista와 이야기해요. 줄이면 이래요.

ssh -N -o ControlMaster=yes -R /home/dev/.gnista/sockets/<this Mac>.sock:<a socket on your Mac> -- devbox

서버가 소켓을 포워딩하지 않으면, Gnista는 대신 서버의 루프백 포트를 포워딩하고, 연결마다 그곳의 내 계정만 읽을 수 있는 암호로 시작해야 해요. 아무것도 포워딩하지 않는 서버라면, 헬퍼가 훅의 메시지를 평범한 ssh 명령으로 실어 날라요.

줄에 보이는 서버 이름은 서버가 하는 말이 아니라 이벤트가 어느 연결로 왔는지로 정해져서, 한 서버가 다른 서버인 척할 수 없어요. 연결이 끊겨 있으면 훅은 Gnista를 찾지 못하고 바로 돌아오고, 에이전트는 평소처럼 터미널에서 물어요.

Linux용 헬퍼는 Gnista 버전과 프로세서마다 한 번 GitHub에 있는 Gnista의 공개 다운로드에서 내려받고, 그 버전용으로 Gnista의 키로 서명된 경우에만 써요. Mac은 내 Gnista에서 서명과 공증을 마친 헬퍼를 받아요.

• “ssh 메시지: …” ssh가 마지막으로 남긴 말이에요. 같은 호스트로 위의 확인을 실행해 본 뒤, 다시 ‘연결’을 클릭하세요.
• “로그인이 필요합니다.” ‘로그인’을 클릭하고 Terminal에서 로그인하세요. 1Password를 쓴다면 그 창이 다른 윈도우 뒤에서 기다리고 있을 수 있어요. 줄에 마우스를 올리면 ssh가 한 말이 보여요.
• “지금은 연결할 수 없습니다.” 줄에 마우스를 올리면 ssh가 한 말이 보여요. Gnista는 간격을 점점 늘리며 계속 다시 시도해요.
• “Gnista는 Linux 머신과 Mac을 연결합니다. 이 머신은 “…”입니다.” 호스트가 다른 시스템이라서 Gnista가 연결할 수 없어요.
• “Gnista가 Linux용 도우미를 내려받지 못했어요. Mac이 온라인인지 확인한 뒤 다시 시도하세요.” 서버에 이 버전의 헬퍼가 처음 필요할 때, Mac이 github.com에 접속할 수 있어야 해요.
• “헬퍼가 전송 중에 바뀌어 도착해” Gnista는 그 헬퍼를 쓰지 않았어요. 다시 ‘연결’을 클릭하세요.
• “연결됨. 하지만 Gnista가 연결하는 에이전트가 없습니다.” 같은 사용자 계정으로 서버에 에이전트를 설치하세요. 다음에 연결이 시작될 때, 또는 ‘연결 해제’ 후 ‘연결’하면 바로 Gnista가 연결해요.
• “이미 연결된 …와 같은 계정입니다.” ssh 설정의 두 이름이 같은 계정으로 이어져요. 하나만 남기세요.
• 세션이 보이지 않아요. 머신의 줄에 ‘연결됨’이라고 나오는지 확인하고, 새 세션을 시작하세요. 이미 실행 중이던 세션에는 Gnista의 훅이 없을 수 있어요.
• “조직에서 꺼 두었습니다.” 관리되는 Mac이고, RemoteMachinesAllowed가 꺼져 있어요. IT 팀에 문의하세요.

• 터미널 알림: Claude Code의 자체 알림은 터미널의 이스케이프 코드라서, ssh를 거쳐 iTerm2처럼 알림을 보여 주는 터미널까지 와요. 무슨 일이 생겼다는 것만 알려 주고 어느 서버, 어느 세션인지는 알려 주지 않으며, 응답은 그 탭에서 해야 해요.
• tmux 벨: monitor-bell과 벨을 알림으로 바꿔 주는 터미널로. 무료지만 한계는 같아요.
• ntfy 같은 휴대폰 알림 서비스로 보내는 훅. 어디서든 받을 수 있지만, 직접 만들고 관리해야 하고, 응답하려면 결국 터미널로 가야 해요.

• 서버의 root 권한이 있는 사람은 소켓에 접근할 수 있어서, 누구나 승인 요청에 응답할 수 있어요. 신뢰하는 서버만 연결하세요.
• 노치에서 보내는 답장과 플랜 한도는 Mac의 세션에만 있어요. 서버의 줄에는 없어요.
• ‘연결 해제’하면 서버에서 Gnista의 훅과 ~/.gnista가 사라져요. 다른 Mac이 아직 쓰고 있다면 남겨 둬요. 그때 서버에 접속할 수 없으면 훅은 남지만, Gnista 없이는 아무 일도 하지 않아요.
• 컨테이너나 Kubernetes 파드의 에이전트: 컨테이너 속 에이전트.
• 조직은 관리하는 Mac에서 원격 머신을 끌 수 있어요: 관리 설정. Gnista가 무엇을 어디로 보내는지: 개인정보 처리방침.
• 7일 무료, 그다음 €19 한 번. 더 알아보기: Claude Code, Codex, Gemini CLI, OpenCode.