SSH 개발환경 (Skills)

개요

agent.zio 플랫폼은 각 산업 도메인별 담당자를 위해 격리된 **독립 가상 개발 환경(SSH Docker Container)**을 제공합니다. 제공된 SSH 포트로 접속하면 /agent_skills 폴더에 직접 소스 코드를 생성하고 Git을 통해 버전을 관리할 수 있습니다. 해당 폴더 내부의 모든 작업물은 실제 구동 엔진과 실시간으로 연동됩니다.

접속 및 사용 방법

1단계

SSH 키 쌍 생성

로컬 PC의 터미널(Mac/Linux) 또는 Git Bash(Windows)를 열고 아래 명령어를 입력하여 SSH 키를 만듭니다. (이미 있는 경우 생략 가능)

ssh-keygen -t rsa -b 4096 -C "your_email@example.com"

키 저장 경로와 비밀번호 입력 프롬프트가 나타나면 엔터를 눌러 기본값으로 진행합니다.

2단계

공개키(Public Key) 등록 요청

생성된 공개키 파일(.pub로 끝나는 파일)의 텍스트 내용을 복사하여 플랫폼 운영자에게 전달하고 등록을 요청합니다.

Mac / Linux: ~/.ssh/id_rsa.pub
Windows: C:\Users\계정명\.ssh\id_rsa.pub

3단계

VS Code Remote - SSH 설치 및 연결

로컬 PC의 VS Code 마켓플레이스에서 Microsoft 공식 “Remote - SSH” 플러그인을 설치합니다. 설치가 완료되면 F1 키를 누르고 SSH: Connect to Host...를 선택한 뒤 아래 주소 형식을 입력하여 접속합니다.

ssh root@서버IP -p [배정받은포트]

예: 이 인스턴스(<인스턴스 주소>)의 배정 포트가 2221 이라면: ssh root@<인스턴스 주소> -p 2221

💡 매번 포트를 치기 번거롭다면 — 로컬 PC 의 ~/.ssh/config 에 이름을 붙여 두면 짧게 붙을 수 있습니다(파일이 없으면 새로 만듭니다).

Host zio_skills
Port 2221                 # 배정받은 포트
HostName <인스턴스 주소>
User root

이렇게 두면 터미널에서는 ssh zio_skills 로, VS Code 의 SSH: Connect to Host… 목록에서도 그 이름으로 바로 보입니다.

4단계

작업 폴더 열기

접속이 성공하면 좌측의 [폴더 열기(Open Folder)] 버튼을 클릭합니다. 처음에는 기본 탐색기 경로가 빈 폴더 상태인 /root/로 지정되어 있습니다. 아래 순서에 맞게 정확한 경로를 지정해 주세요.

입력창 우측의 [상위 폴더로 이동 (Go to Parent Directory)] 버튼(위쪽 화살표 기호 .. 혹은 ⬆️)을 클릭하여 최상위 경로인 / 로 이동합니다.
알파벳 순서에 따라 목록 맨 처음에 나타나는 agent_skills 폴더를 선택하고 [확인 (OK)]을 누릅니다.

💡 꿀팁: 최초 1회만 /agent_skills 폴더로 열어두면, 다음 원격 접속부터는 VS Code가 해당 경로를 기억하여 자동으로 접속 즉시 열어줍니다.

다른 길

로컬에서 편집하고 저장할 때마다 올리기 (SFTP)

원격에 붙어 편집하는 대신 로컬 파일을 편집하고 저장할 때마다 자동으로 올리는 방식입니다. 로컬에 사본이 남는 것이 편한 사람에게 맞습니다. VS Code 마켓플레이스에서 “SFTP”(liximomo 또는 Natizyskunk) 플러그인을 설치하고, 로컬 프로젝트 뿌리에 .vscode/sftp.json 을 만듭니다.

{
    "name": "zio-skills",
    "host": "<인스턴스 주소>",
    "protocol": "sftp",
    "port": 2221,
    "username": "root",
    "remotePath": "/agent_skills",
    "uploadOnSave": true,
    "ignore": ["**/.git/**", "**/.vscode/**", "**/__pycache__/**"]
}

여럿이 함께 쓸 때는 조심하십시오. 저장할 때마다 올라가므로, 남이 서버에서 고친 파일을 내 로컬 옛 사본이 말없이 덮어씁니다. 협업 중이라면 위의 Remote - SSH 쪽이 안전합니다.

여러 사람이 함께 쓸 때

한 도메인을 담당자 여럿이 함께 쓰는 경우입니다. 예를 들어 한 회사에서 9명이 같은 도메인의 스킬을 만든다면, 9명 모두 같은 주소 · 같은 포트 · 같은 계정(root)으로 접속합니다. 사람마다 다른 것은 공개키와 작업 폴더뿐입니다.

항목	몇 개인가	설명
접속 주소 · 포트	도메인마다 하나	SSH 개발 컨테이너가 도메인마다 하나씩 뜹니다. 그래서 포트도 하나입니다. 사람 수만큼 늘어나지 않습니다.
로그인 계정	도메인마다 하나	`root` 하나를 아홉 명이 함께 씁니다.
공개키	사람마다 하나	`authorized_keys` 에 사람 수만큼 줄이 늘어납니다. 신원은 계정이 아니라 이 키가 가립니다.
작업 폴더	프로젝트마다 하나	`/agent_skills/<프로젝트명>/` 아래에서 각자 작업합니다.
Claude 신원 (로그인·세션)	사람마다 하나	공개키마다 `CLAUDE_CONFIG_DIR` 가 자동으로 갈려, 인증·세션·설정이 사람별로 분리됩니다. 같은 `root`·같은 폴더를 써도 Claude 신원은 안 섞입니다.

아홉 명이 똑같은 한 줄로 붙습니다.

ssh root@[도메인 주소] -p [배정받은포트]

포트는 회사(도메인)마다 하나입니다. 사람마다 다른 포트를 받는 것이 아닙니다.

Claude 신원은 사람별로 분리됩니다 — 최초 1회 로그인

같은 root 계정·같은 폴더를 함께 써도, Claude 로그인·세션·설정은 사람마다 완전히 분리됩니다. 공개키마다 CLAUDE_CONFIG_DIR 가 자동으로 갈리기 때문입니다(내 세션엔 /root/.claude-users/<내이름>). 처음 한 번만 내 신원으로 로그인하면 됩니다:

echo $CLAUDE_CONFIG_DIR      # 내 전용 경로가 보이는지 먼저 확인
claude                       # 실행 후 /login 으로 최초 1회 로그인

⚠️ echo $CLAUDE_CONFIG_DIR 가 비어 있으면, 옛 원격 세션이 남아 있는 것입니다. VS Code 에서 F1 → “Remote-SSH: Kill VS Code Server on Host…” 로 정리한 뒤 다시 접속하면 새 값이 잡힙니다. 파일 탐색기·여는 폴더는 그대로이니(협업 화면 동일) 안심하고 재접속하십시오.

서버에서 직접 고치지 마십시오 — 브랜치로 나눠 작업합니다

아홉 명이 같은 폴더 하나를 봅니다. 서버에서 바로 고치면 누가 언제 무엇을 바꿨는지 남지 않고, 둘이 같은 파일을 만지면 뒤엣것이 이깁니다.

로컬 PC 에서 자기 브랜치(feature/이름)를 만들어 작업하고 올립니다.
공동 저장소에서 PR 로 main 에 합칩니다.
서버에 붙어 받아 옵니다.

cd /agent_skills
git pull origin main

서버는 늘 main 에 머뭅니다. 여기서 브랜치를 만들거나 옮겨 다니지 마십시오 — 받아 오기(git pull)만 합니다. 그래서 서버에서 브랜치를 지울 일도 없습니다. 다 쓴 기능 브랜치는 각자 로컬과 공동 저장소에서 정리합니다.

운영자가 하는 일 — 공개키를 모아 등록하기

담당자 아홉 명에게서 1단계에서 만든 공개키(.pub 파일의 내용) 를 한 줄씩 받아, 해당 도메인의 authorized_keys 에 이어 붙입니다. 줄 끝에 누구 것인지 적어 두는 것을 권합니다.

ssh-ed25519 AAAAC3NzaC1...abcd  kim@company    # 김OO, 생산관리
ssh-ed25519 AAAAC3NzaC1...efgh  lee@company    # 이OO, 품질
ssh-rsa     AAAAB3NzaC1...ijkl  park@company   # 박OO, 설비

줄 하나가 사람 하나입니다. 새 담당자가 오면 한 줄 더하고, 나가면 그 줄만 지웁니다.
받는 것은 .pub 로 끝나는 공개키뿐입니다. 개인키는 어떤 경우에도 주고받지 않습니다.
파일을 고친 뒤에는 SSH 개발 컨테이너를 다시 시작해야 반영됩니다. 컨테이너가 뜰 때 이 파일을 한 번 읽어 들이기 때문입니다.

이렇게 쓰면 좋은 점

서로의 프로젝트 폴더를 그대로 열어 고칠 수 있습니다. 이것이 실질적인 협업의 모습입니다.

권한이 갈리지 않습니다. 아홉 명이 같은 root 신분이라, 누가 만든 파일이든 다른 사람이 바로 열고 고치고 지울 수 있습니다. 계정을 사람마다 따로 두면 A가 만든 파일을 B가 저장하지 못하는 일이 매일 생깁니다.
웹 화면과 SSH 가 같은 신분입니다. 웹 [Artifacts] 편집기로 저장한 파일도 root 소유로 떨어지므로, 그대로 SSH 에서 이어 고칠 수 있습니다. 아래 Q4 의 권한 문제가 팀 안에서는 생기지 않습니다.
Git 저장소가 하나입니다. /agent_skills 전체가 한 저장소라 누가 무엇을 바꿨는지 커밋으로 남고, 되돌리는 것도 여기서 합니다.
스킬 하나를 여럿이 이어받습니다. 스킬을 다시 띄우면 그 폴더 안의 .py 파일이 모두 다시 등록되므로, 어제 동료가 더해 둔 함수가 오늘 내 재시작에서 함께 살아납니다.
운영자 손이 덜 갑니다. 사람이 늘어도 컨테이너 · 포트 · 방화벽은 그대로이고, authorized_keys 에 줄 하나가 늘 뿐입니다.

⚠️ 대신 팀이 지켜야 할 두 가지

남의 폴더는 건드리기 전에 말합니다. 서로 고칠 수 있다는 것은 서로 지울 수도 있다는 뜻입니다. 시스템 권한이 막아 주지 않으므로 폴더 이름 규칙과 Git 이 유일한 안전장치입니다.
루트 바로 밑에 파일을 두지 않습니다. 반드시 /agent_skills/<프로젝트명>/ 폴더를 만들고 그 안에서 작업합니다. 낱개 .py 파일은 스킬로 뜨지 않습니다.

※ 서로의 작업물을 보면 안 되는 관계(외부 협력업체 등)라면, 계정을 나눌 것이 아니라 도메인을 따로 여는 것이 맞습니다. 그래야 포트도 폴더도 데이터도 통째로 갈립니다.

🪟 Windows 사용자 자가 진단

Windows 에서 비밀번호를 자꾸 물어보거나, Permission denied (publickey) 가 나거나, Antigravity·VS Code 가 붙지 않을 때 스스로 원인을 찾는 순서입니다. 아래 명령은 명령 프롬프트(cmd) · PowerShell 어디서나 됩니다. 경로 속 계정명 은 본인 Windows 로그인 이름으로 바꾸십시오.

비밀번호를 계속 묻는다면, 그건 “비밀번호가 틀려서”가 아닙니다. 서버는 root 계정에 비밀번호 로그인을 아예 막아 두었습니다. 공개키 인증이 실패하면 화면이 비밀번호를 묻지만, 어떤 비밀번호를 넣어도 들어가지지 않습니다. 오직 공개키가 맞아야만 접속됩니다 — 그래서 진단은 “내 공개키가 서버에 등록된 것과 맞는가”부터 봅니다.

진단 0

IDE 말고 터미널(PowerShell)에서 먼저 붙어 본다

Antigravity · VS Code 는 자체 설정이 얽혀 원인을 가립니다. 가장 먼저 순수 ssh 로 붙어 보면, “SSH · 키 문제”인지 “IDE 설정 문제”인지 단번에 갈립니다.

ssh -p [포트] root@[주소]

예: 포트 2223 이면 ssh -p 2223 root@[도메인 주소]. 처음 붙을 때 신뢰 확인이 나오면 yes 를 입력합니다.

root@…:~# 프롬프트가 뜨면 → SSH · 키 · 서버가 전부 정상입니다. 문제는 IDE 설정뿐이니 진단 5만 보면 됩니다.
비밀번호를 묻거나 Permission denied (publickey) 면 → 공개키 문제 → 진단 1부터 봅니다.
Connection refused · 시간 초과 → 포트 · 주소가 틀렸거나 컨테이너가 잠깐 재시작 중입니다. 잠시 뒤 다시 시도합니다.

터미널에서는 되는데 IDE 에서만 안 된다면, 키 · 서버는 멀쩡한 것입니다 — 진단 5 만 확인하면 됩니다.

진단 1

내 공개키 “지문”이 등록된 것과 같은가

내 공개키에는 지문(fingerprint) 이라는 고유한 값이 있습니다. 이 값이 서버에 등록된 것과 같아야 접속됩니다. 아래 명령으로 내 지문을 확인합니다.

ssh-keygen -lf C:\Users\계정명\.ssh\id_rsa.pub

이렇게 한 줄이 나옵니다 (예):

4096 SHA256:9Zt4Kq7bXwR2mNpL8vC1sD3fG6hJ0kA5eB7yU2iO4wQ user@company (RSA)

이 줄에서 SHA256: 뒤에 붙은 값(위 예의 9Zt4Kq7b…4wQ 부분)이 내 키 지문입니다. 이 값을 관리 콘솔 [SSH 등록자] 화면의 내 카드에 적힌 지문(또는 운영자가 알려준 값)과 글자까지 똑같은지 비교하십시오.

id_rsa.pub 는 공개키 파일의 이름입니다. 이 매뉴얼 1단계대로 만들었다면 그대로 실행하면 됩니다. 내 파일 이름이 확실치 않으면 dir C:\Users\계정명\.ssh 를 실행해, .pub 로 끝나는 파일 이름을 위 명령에 넣으십시오.

지문이 같다 → 키는 맞습니다. 진단 3(권한) · 진단 5(Antigravity)로 갑니다.
지문이 다르다 → 지금 쓰는 개인키가 서버에 등록된 공개키와 다른 것입니다. 이 .pub 파일 내용을 운영자에게 다시 등록 요청하십시오.

이 예시 키를 그대로 보내지 마십시오. 이 매뉴얼 1단계의 예시(your_email@example.com)를 복사해 보내는 실수가 잦습니다. 코멘트가 your_email@example.com 이면 당신의 키가 아닙니다. 반드시 본인 PC에서 만든 .pub 파일의 실제 내용을 보내야 합니다.

진단 2

상세 로그로 어디서 막히는지 본다

접속을 **상세 로그(-vv)**로 시도하면, 어떤 키를 내밀고 서버가 어떻게 반응하는지 보입니다.

ssh -vv -p [포트] root@[주소]

Offering public key ... SHA256:... — 내 키를 내밀고 있나? 그 지문이 등록값과 같나?
키를 내민 직후 바로 password: 로 넘어감 → 서버에 그 키가 없음(등록 안 됐거나 다른 키).
No such file or directory ... id_rsa → 키 파일 이름·위치가 다름.
bad permissions / UNPROTECTED PRIVATE KEY → 진단 3(권한)으로.

진단 3

키 · 설정 파일 권한 잠그기 (Windows 고질 문제)

Windows 는 개인키나 config 파일이 “너무 열려” 있으면 무시하거나 거부합니다. 내 계정 전용으로 잠급니다. 먼저 내 SID(고유번호)를 확인합니다.

whoami /user

S-1-5-21-…-1001 형태의 값이 나옵니다. 아래 <SID> 자리에 그 값을 넣어 실행합니다(개인키와 config 둘 다).

# 개인키 (config 파일도 아래 세 줄을 똑같이 실행)
icacls "C:\\Users\\계정명\\.ssh\\id_rsa" /reset
icacls "C:\\Users\\계정명\\.ssh\\id_rsa" /setowner "*<SID>"
icacls "C:\\Users\\계정명\\.ssh\\id_rsa" /inheritance:r /grant:r "*<SID>:F"

이름(whoami) 대신 *<SID>(별표+SID)를 쓰는 이유: 일부 PC 에서 계정 이름이 “도메인”으로 잘못 풀려, 이름으로 권한을 줘도 OpenSSH 가 계속 거부합니다. SID 로 주면 확실합니다.

진단 4

`Bad owner or permissions on config` / `lookup_sid: Invalid account type: 3` 가 계속 나올 때

이건 Windows 기본 OpenSSH(9.5p2)의 계정 인식 버그입니다. 진단 3으로 권한을 고쳐도 이 메시지가 계속 나면, 둘 중 하나로 우회합니다.

(가) config 를 직접 지정해 그 검사를 건너뛰기 — 터미널에서:

ssh -F "C:\Users\계정명\.ssh\config" [별칭]

(나) 최신 OpenSSH 설치 — github.com/PowerShell/Win32-OpenSSH/releases 의 OpenSSH-Win64.zip 를 풀고, 그 안의 ssh.exe 로 접속합니다. 버전이 9.5p2 보다 높으면 이 버그가 없습니다.

진단 5

Antigravity / VS Code 가 config · 키를 못 읽을 때

터미널로는 붙는데 Antigravity·VS Code 에서만 안 되면, 그 IDE 가 어떤 ssh 를 쓰는지를 바꿔 줍니다.

진단 4(나)의 최신 ssh.exe 를 쓰도록 설정합니다. Ctrl+, → 설정(JSON)에 추가:

"remote.SSH.path": "C:\\Users\\계정명\\OpenSSH-Win64\\ssh.exe"

설정을 바꾼 뒤에는 창만 닫지 말고 완전히 종료했다가 다시 실행해야 반영됩니다.
그래도 안 되면 Output 패널 → Remote-SSH 로그의 Launching SSH server with command: 줄을 운영자에게 보내십시오.

문제 해결

Q1. 접속 시 “WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED!” 경고가 뜨고 접속이 안 됩니다.

원인: 원격 SSH 서버의 고유 인식표(Host Key)가 로컬 PC 에 저장해 둔 것과 달라지면 보안상의 이유로 접속이 차단됩니다.

이제는 드물게 일어납니다. 예전에는 컨테이너를 다시 세울 때마다 인식표가 바뀌어 담당자 전원이 이 경고를 받았지만, 지금은 인식표를 서버 폴더에 두고 재사용합니다 — 다시 세워도, 이미지를 새로 빌드해도 그대로입니다. 그래도 이 경고가 뜬다면 운영자에게 알려 주십시오. 인식표를 새로 만든 일이 있었거나, 정말로 다른 서버에 붙고 있는 것일 수 있습니다.

해결 방법: 로컬 PC의 터미널(또는 Git Bash/PowerShell)을 열고 아래 키 초기화 명령을 실행한 후 다시 접속을 시도하세요.

ssh-keygen -R "[서버IP]:[배정받은포트]"

예: ssh-keygen -R "[<인스턴스 주소>]:2221" 실행 후 재접속하여 신뢰 확인 프롬프트에 yes를 입력합니다.

함께 겪기 쉬운 두 가지

컨테이너를 다시 만드는 몇 초 동안은 “Connection refused”가 납니다. 키가 바뀐 것이 아니라 아직 안 뜬 것이니, 잠시 뒤 다시 붙으면 됩니다. 이 경고는 키 초기화로 해결되지 않습니다.
VS Code는 한 번 실패하면 그 상태에 매달립니다. 서버가 살아나도 저절로 붙지 않고 Error while creating SOCKS connection만 반복합니다. F1 → **Remote-SSH: Kill VS Code Server on Host…**로 해당 호스트를 한 번 정리한 뒤 다시 접속하세요.

Q2. 터미널에서 “git status” 실행 시 “fatal: detected dubious ownership in repository” 에러가 발생합니다.

원인: 호스트 서버의 물리 폴더와 컨테이너 내부 root 계정 간의 파일 권한 불일치로 인해 발생하는 Git의 자체 보안 검증 경고입니다.

해결 방법: 원격 서버 터미널 내에서 아래 명령을 실행하여 현재 디렉토리를 안전 구역으로 등록해 주시면 정상 동작합니다. (최신 시스템에서는 자동 등록됩니다)

git config --global --add safe.directory /agent_skills

Q3. 접속할 때 “Permission denied (publickey)” 오류가 납니다.

원인 및 점검 사항:

로컬 PC에서 사용 중인 SSH Private Key(id_rsa 등)와 서버에 등록 요청한 Public Key가 다른 키 쌍인지 확인하세요.
접속 명령에 알맞은 포트 번호(-p [포트])가 입력되었는지 재확인하세요.
문제가 지속될 경우 플랫폼 운영자에게 문의하여 authorized_keys 파일의 저장 위치 및 폴더 권한설정(700 / 600)을 점검받으십시오.

Q4. 웹 화면에서 만든 폴더/파일이 호스트 서버에서 수정되지 않습니다. (Permission denied)

증상: 웹 [Artifacts] 탐색기로 만든 스킬 폴더나 파일을, 호스트 서버에 직접 붙어 쓰는 편집기(로컬 IDE, CLI 에디터 등)로 저장하려 하면 권한 거부가 납니다. ※ SSH 개발 컨테이너 안에서는 root 계정으로 작업하므로 이 문제가 나타나지 않습니다.

원인: 웹 화면의 파일 생성은 api 컨테이너가 대신 수행하고, 이 컨테이너는 uid 0(root) 으로 동작합니다. 스킬·에이전트 폴더는 바인드 마운트로 호스트와 같은 실체를 공유하므로, 만들어진 결과물이 호스트에도 root:root 소유로 떨어집니다. 기본 umask 022 때문에 소유자 외에는 읽기만 가능한 상태가 됩니다.

해결 방법: 호스트 쪽에 기본 ACL(Default ACL) 을 한 번 걸어 둡니다. 기본 ACL 은 umask 보다 우선하므로, 앞으로 root 가 만드는 파일에도 자동으로 적용됩니다. 저장소 최상위 폴더에서 실행하십시오.

# 앞으로 만들어질 것 (기본 ACL)
sudo setfacl -R -d -m g:$(id -gn):rwx instances/*/.skills instances/*/.agents

# 이미 만들어져 막혀 있는 것 (접근 ACL)
sudo setfacl -R -m  g:$(id -gn):rwX instances/*/.skills instances/*/.agents

둘째 줄만 rwX(대문자) 입니다. 디렉터리에만 실행 권한을 주고 .py 같은 일반 파일은 건너뜁니다. 소문자로 하면 소스 파일이 전부 실행 파일로 표시되어 Git 이 권한 변경으로 인식합니다.
컨테이너 재시작은 필요 없습니다. ACL 은 호스트 파일시스템의 속성이라 마운트 너머로 즉시 반영됩니다.
대상을 .skills · .agents 로만 좁힌 이유는, instances/ 아래에 Neo4j 데이터처럼 컨테이너가 소유해야 하는 폴더가 섞여 있기 때문입니다.

확인: 아래 출력에 두 줄이 보이면 정상입니다.

getfacl -p instances/<도메인>/.skills/<프로젝트>

group:계정명:rwx
default:group:계정명:rwx

⚠️ 이렇게는 하지 마십시오: docker-compose.yml 의 api 서비스에 user: "1000:1000" 을 넣어 컨테이너를 일반 계정으로 내리는 방법은 권하지 않습니다. 이 컨테이너는 스킬을 배포할 때 이미지 내부에 가상환경을 만들고 pip install 을 수행하는데, 해당 경로가 root 소유라 컨테이너가 자기 자신에게 쓰지 못하게 됩니다.

Q5. 접속할 때 비밀번호를 자꾸 물어봅니다. (아무 비밀번호도 안 통합니다)

원인: 공개키 인증이 실패하면 화면이 비밀번호를 묻지만, root 계정은 비밀번호 로그인이 막혀 있어 어떤 값도 통하지 않습니다. 즉 “비밀번호 문제”가 아니라 공개키가 서버와 안 맞는 문제입니다.

해결: 위 🪟 Windows 사용자 자가 진단 의 진단 1(지문 대조)부터 순서대로 확인하십시오. 대개 (1) 서버에 등록된 것과 다른 키를 쓰고 있거나, (2) Antigravity 가 개인키를 안 물고 있는 경우입니다.