Skip to content

SSH workspace (Skills)

The agent.zio platform provides an isolated independent virtual development environment for each domain’s responsible person.
By connecting to port 2222 with the username supplied by the operator, you can create source code directly in the /agent_skills folder and manage versions via Git. All work within that folder is synchronized in real time with the actual runtime engine.

The only port is 2222. Each instance does not receive a different port. Which instance you use is determined by the username—in the form [person]@[instance], as told by the operator. Therefore, the address and port (2222) are identical for everyone using the same instance, and only the name differs per person.
The agent.abc.co.kr · hong@abc-office shown below are illustrative placeholders—obtain your actual values from the operator.

Open a terminal on your local PC (Mac/Linux) or Git Bash (Windows) and run the command below to create an SSH key. (Skip if you already have one)

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

When prompted for the key storage location and passphrase, press Enter to proceed with the defaults.

Copy the text contents of the generated public key file (*.pub) and send it to the platform administrator for registration.

  • Mac / Linux: ~/.ssh/id_rsa.pub
  • Windows: C:\Users\<account>\.ssh\id_rsa.pub

Install and Connect with VS Code Remote - SSH

Section titled “Install and Connect with VS Code Remote - SSH”

Install Microsoft’s official “Remote - SSH” extension from the VS Code Marketplace on your local PC. After installation, press F1, select SSH: Connect to Host…, then enter the address in the format below.

Terminal window
ssh [사용자 이름]@[주소] -p 2222

Example: If the username is hong@abc-office and the host is agent.abc.co.kr, use — ssh hong@abc-office@agent.abc.co.kr -p 2222

The @ appears twice. The first part, hong@abc-office, is the username in its entirety, and the second part, @agent.abc.co.kr, is the host address.

💡 If typing it out each time is cumbersome, you can give it a name in your local PC’s ~/.ssh/config file so that you can use a short alias (create the file if it doesn’t exist).

Terminal window
Host zio_skills
HostName agent.abc.co.kr # 당신 인스턴스의 웹 주소
Port 2222 # 모든 인스턴스가 같습니다
User hong@abc-office # 운영자가 알려 준 사용자 이름

With this, you can connect from the terminal with ssh zio_skills, and the same alias will appear directly in VS Code’s SSH: Connect to Host… list.

Once connected successfully, click the [Open Folder] button on the left. Initially, the default explorer path is an empty folder /root/. Specify the correct path according to the following steps.

  1. Click the [Go to Parent Directory] button (the up arrow .. or ⬆️) next to the input field to navigate to the root directory /.
  2. Select the first folder in alphabetical order, agent_skills, and click [OK].

💡 Tip: If you open the /agent_skills folder once at the start, VS Code will remember this path for subsequent remote connections and automatically open it immediately.

Instead of editing directly on the remote machine, you can edit local files and have them automatically uploaded each time you save. This is convenient if you prefer to keep a local copy. Install the “SFTP” extension (by liximomo or Natizyskunk) from the VS Code Marketplace, then create .vscode/sftp.json at the root of your local project.

{
"name": "zio-skills",
"host": "agent.abc.co.kr",
"protocol": "sftp",
"port": 2222,
"username": "hong@abc-office",
"remotePath": "/agent_skills",
"uploadOnSave": true,
"ignore": ["**/.git/**", "**/.vscode/**", "**/__pycache__/**"]
}

Be cautious when multiple people use this. Since files are uploaded on every save, a colleague’s changes on the server can silently overwrite your local copy. If you’re collaborating, the Remote - SSH approach is safer.

This is when several people share the same domain. For example, if nine people in a company create skills for the same domain, all nine connect to the same address and port (2222), but each has a different username. The common items are the address and port; the differing items are the username, public key, and working folder.

Item How Many Description
Connection address · port One per domain An SSH development container is launched for each domain, so there is only one port. It does not increase with the number of people.
Username One per person [person]@[instance] format (e.g., hong@abc-office). This name determines who and which instance to connect to. The operator provides it.
Public key One per person Each username is paired with a public key. Registration is done by the operator—no one touches server files.
Working folder One per project Work occurs under /agent_skills/<project>/.
Claude identity (login·session) One per person Each person’s CLAUDE_CONFIG_DIR is automatically set, so authentication, session, and settings are separated by person. Even if the same folder is used, Claude identities do not mix.

Nine people share the same pattern; only their names differ.

Terminal window
ssh [사용자 이름]@[주소] -p 2222
# 예 — 같은 회사 세 사람
ssh hong@abc-office@agent.abc.co.kr -p 2222
ssh kim@abc-office@agent.abc.co.kr -p 2222
ssh lee@abc-office@agent.abc.co.kr -p 2222

The port is the same 2222 for all instances. Each instance or each person does not receive a different port.

Claude Code Is Already Installed — just claude

Section titled “Claude Code Is Already Installed — just claude”

When you connect, Claude Code is already installed. There’s nothing to install. The entry point is the working folder (/agent_skills), so there’s no need to cd.

Terminal window
claude --version # 2.1.285 — 모두가 같은 판입니다
claude # 바로 시작

On your PC’s IDE, you can use whatever you like. Inside the container we standardize everything. This is a shared space, so if everyone installs their own environment, each person will have a different setup and it will disappear every time the container restarts. That’s why we baked the environment into the image — the same environment, different accounts. We also handle pushing the environment (so claude update is blocked). You can use other tools (gemini·codex, etc.), but those are installed in your home folder and remain there—your home becomes the working folder and they no longer disappear.

The Home Folder Is the Working Folder — What’s Written Stays

Section titled “The Home Folder Is the Working Folder — What’s Written Stays”

Home (~) is /agent_skills. Therefore .gitconfig, command history, IDE remote server settings, etc., persist when a new container starts. Previously, home was /root, so everything vanished with each new container.

So you can write “things we always do” here. Claude reads the CLAUDE.md in the current folder and its parent. Previously, home was /root, so /agent_skills/CLAUDE.md was neither a sibling nor a child, and it was never read—those were separate folders. Now it is read.

  • /agent_skills/CLAUDE.md — unique to this instance and task; shared by everyone via git
  • /agent_skills/<project>/CLAUDE.md — rules specific to that project; only read when working in that folder

You don’t need to be told to read the SDK specification—it’s already included. To verify it was read, type /context in the session and look at the Memory files list.

Claude Identity Is Separated by Person — First Login Only Once

Section titled “Claude Identity Is Separated by Person — First Login Only Once”

Even if you share the same root account and folder, Claude login·session·settings are completely separated per person because each public key automatically sets a different CLAUDE_CONFIG_DIR (in my session it’s /root/.claude-users/<myname>). Just log in once with your identity:

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

⚠️ If echo $CLAUDE_CONFIG_DIR is empty, an old remote session remains. In VS Code, use F1 → “Remote-SSH: Kill VS Code Server on Host…” to clean it up, then reconnect; a new value will be set. The file explorer and open folders stay the same (the collaboration screen is identical), so you can safely reconnect.

Don’t Edit Directly on the Server — Work in Branches

Section titled “Don’t Edit Directly on the Server — Work in Branches”

Nine people look at one shared folder. If someone edits directly on the server, there’s no record of who changed what, and if two people edit the same file it will become a mess.

  1. Create your own branch (feature/name) locally, work, and push.
  2. Merge into main via PR in the shared repository.
  3. Pull from the server.
Terminal window
cd /agent_skills
git pull origin main

The server always stays on main. Do not create or move branches here—only pull (git pull). Therefore there’s no need to delete branches on the server. Clean up used feature branches locally and in the shared repo.

What the Operator Does — Collecting Public Keys

Section titled “What the Operator Does — Collecting Public Keys”

From the nine operators, collect each public key (the contents of a .pub file) line by line, register it with the person’s name, and create their username. Tell the operator that username. Neither the operator nor the server admin touches files inside the server.

Terminal window
ssh-ed25519 AAAAC3NzaC1...abcd kim@company # 김OO, 생산관리
ssh-ed25519 AAAAC3NzaC1...efgh lee@company # 이OO, 품질
ssh-rsa AAAAB3NzaC1...ijkl park@company # 박OO, 설비
  • One line per person. Add a line when a new operator arrives; remove only that line when they leave.
  • Only accept .pub public keys. Private keys are never exchanged.
  • After editing the file, you must restart the SSH development container for changes to take effect because the container reads this file once on startup.

You can open and edit each other’s project folders directly. That is real collaboration.

  1. No permission conflicts. All nine are root, so anyone can open, edit, or delete any file immediately. If you had separate accounts, A could create a file that B cannot save, causing daily issues.
  2. Same identity for web and SSH. Files edited in the web [Artifacts] editor are owned by root, so they can be continued to edit via SSH without permission problems. The Q4 permission issue does not arise within the team.
  3. One Git repository. /agent_skills is a single repo, so commits record who changed what and you can revert from here.
  4. Multiple people inherit a skill. When a skill is restarted, all .py files in that folder are re‑registered, so functions added by yesterday’s colleague survive into today’s restart.
  5. Less operator intervention. Even as the team grows, server, port, and firewall remain unchanged; only one line per person is added to the registry.

⚠️ Two things the team must observe

  • Ask before touching someone else’s folder. The ability to edit means you can also delete. Since system permissions don’t protect you, folder naming conventions and Git are the sole safeguards.
  • Do not place files directly under root. Always create /agent_skills/<project>/ and work inside it. Standalone .py files won’t be loaded as a skill.

If you have relationships where you must not see each other’s work (e.g., external contractors), then you should split both the instance and the username. The username indicates where to enter, but once inside the same instance, folders are shared. Splitting instances ensures folders and data are completely separate.

When you are kept being asked for a password, see Permission denied (publickey), or Antigravity·VS Code fails to connect, follow this order to find the cause yourself. The commands below work in Command Prompt (cmd) or PowerShell on any machine. Replace the 계정명 in the path with your own Windows login name.

If you keep being asked for a password, that does not mean “the password is wrong.” The server has completely disabled password login for the root account. If public‑key authentication fails, the screen will prompt for a password, but no password will work. Only the correct public key will allow access—so start by checking whether your public key matches what is registered on the server.

Try to connect from the terminal (PowerShell) first instead of an IDE

Section titled “Try to connect from the terminal (PowerShell) first instead of an IDE”

Antigravity·VS Code has its own settings that can obscure the problem. First try a plain ssh connection; this will immediately tell you whether it’s an “SSH key issue” or an “IDE setting issue.”

Terminal window
ssh -p 2222 [사용자 이름]@[주소]
# 예
ssh -p 2222 hong@abc-office@agent.abc.co.kr

If a trust confirmation appears on first connect, type yes.

  • If the prompt becomes root@…:~#, then SSH, keys, and server are all fine. The problem is only in the IDE settings, so just look at Diagnosis 5. It’s normal for the internal user to appear as root even though you logged in with a different name (hong@abc-office). That name is used only to decide “who goes where” at the front door.
  • If it asks for a password or shows Permission denied (publickey), then it’s a public‑key problem → start with Diagnosis 1.
  • If you see bad username and the connection drops immediately, your username is wrong. It must be in the form [person]@[instance]; you cannot log in as root. Verify with the operator.
  • If you get Connection refused or a timeout, the address is wrong or the port isn’t 2222. Try again after a short wait.

If it works from the terminal but not from the IDE, then keys and server are fine—just confirm Diagnosis 5.

Does my public‑key “fingerprint” match what’s registered?

Section titled “Does my public‑key “fingerprint” match what’s registered?”

Your public key has a unique value called a fingerprint. That fingerprint must match the one on the server for you to connect. Use the following command to view your fingerprint.

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

You’ll see a line like this (example):

Terminal window
4096 SHA256:9Zt4Kq7bXwR2mNpL8vC1sD3fG6hJ0kA5eB7yU2iO4wQ user@company (RSA)

In that line, the value after SHA256: (the part 9Zt4Kq7b…4wQ in the example) is your key’s fingerprint. Compare it exactly—including every character—to the fingerprint shown on your card in the [SSH Registrants] console or to the value given by the operator.

id_rsa.pub is the name of the public‑key file. If you followed step 1 of this manual, just run the command as written. If you’re not sure what your file’s name is, run dir C:\Users\계정명\.ssh and use the filename that ends with .pub.

  • If the fingerprints match → the key is correct. Proceed to Diagnosis 3 (permissions) and Diagnosis 5 (Antigravity).
  • If they differ → the private key you’re using does not correspond to the public key registered on the server. Ask the operator to register the contents of this .pub file again.

Do not send the example key verbatim. It’s common to copy and paste the placeholder (your_email@example.com) from step 1. If the comment contains your_email@example.com, that is not your key. Always send the actual contents of the .pub file created on your own PC.

Look at detailed logs to see where it stops

Section titled “Look at detailed logs to see where it stops”

Try connecting with a detailed log (-vv) to see which key you’re offering and how the server reacts.

Terminal window
ssh -vv -p 2222 [사용자 이름]@[주소]
  • Offering public key ... SHA256:... — Are you offering your key? Does that fingerprint match the registered value?
  • If immediately after offering the key it goes to password: → the server has no record of that key (not registered or a different key).
  • No such file or directory ... id_rsa → wrong key‑file name or location.
  • bad permissions / UNPROTECTED PRIVATE KEY → go to Diagnosis 3 (permissions).

Lock the key and config file permissions (common Windows issue)

Section titled “Lock the key and config file permissions (common Windows issue)”

Windows will ignore or reject a private key or config file that is “too open.” Lock them for your own account. First, find your SID (unique identifier).

Terminal window
whoami /user

You’ll see a value like S-1-5-21-…-1001. Insert that value into the <SID> placeholder below and run it (for both the private key and the config file).

Terminal window
# 개인키 (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"

The reason for using *<SID> instead of your username (whoami) is that on some PCs the account name may be incorrectly resolved to a domain, so giving permissions by name still causes OpenSSH to reject them. Using the SID guarantees it works.

When Bad owner or permissions on config / lookup_sid: Invalid account type: 3 keeps appearing

Section titled “When Bad owner or permissions on config / lookup_sid: Invalid account type: 3 keeps appearing”

This is a bug in Windows’ default OpenSSH (9.5p2) that misidentifies accounts. Even after fixing permissions per Diagnosis 3, if the message persists, work around it with one of the following.

(a) Explicitly specify config to skip the check — in the terminal:

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

(b) Install a newer OpenSSH release — extract OpenSSH-Win64.zip from github.com/PowerShell/Win32-OpenSSH/releases, and use the ssh.exe inside it. If the version is higher than 9.5p2, this bug no longer exists.

Antigravity / VS Code can’t read the config or key

Section titled “Antigravity / VS Code can’t read the config or key”

If you can connect from the terminal but not from Antigravity·VS Code, change which SSH client the IDE uses.

  • Configure it to use the latest ssh.exe from Diagnosis 4(b). In Ctrl+, → Settings (JSON), add:
"remote.SSH.path": "C:\\Users\\계정명\\OpenSSH-Win64\\ssh.exe"

After changing the setting, do not just close the window; fully exit and restart so the change takes effect.

If it still doesn’t work, send the operator the line starting with Launching SSH server with command: from the Output panel → Remote‑SSH log.

Q1. When connecting, the warning “WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED!” appears and connection fails.

Section titled “Q1. When connecting, the warning “WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED!” appears and connection fails.”

Cause: If the unique identifier (Host Key) of the remote SSH server differs from what is stored on the local PC, the connection is blocked for security reasons.

This rarely happens now. In the past, every time a container was rebuilt the key would change, so everyone received this warning. Now we keep the key in the server folder and reuse it—even if the container is recreated or the image is rebuilt, it stays the same. If you still see this warning, notify the operator. It may mean a new key was created or you are actually connecting to a different server.

Solution: Open a terminal on your local PC (or Git Bash/PowerShell) and run the following key reset command, then reconnect.

Terminal window
ssh-keygen -R "[주소]:2222"

Example: after running ssh-keygen -R "[agent.abc.co.kr]:2222", reconnect and type yes when prompted to trust.

Two common related issues

  • For a few seconds after recreating the container you may see “Connection refused”. The key hasn’t changed; it’s just not up yet, so try again shortly. Resetting the key does not fix this.
  • VS Code can get stuck after one failure. Even if the server is alive, it won’t reconnect automatically and will repeatedly show Error while creating SOCKS connection. Use F1 → Remote‑SSH: Kill VS Code Server on Host… to clean up that host once, then reconnect.

Q2. Running “git status” in a terminal gives the error “fatal: detected dubious ownership in repository”.

Section titled “Q2. Running “git status” in a terminal gives the error “fatal: detected dubious ownership in repository”.”

Cause: Git’s own security check triggers when file permissions differ between the physical folder on the host server and the root account inside the container.

Solution: In the remote server terminal, run the following command to register the current directory as a safe area. (On newer systems this is automatic.)

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

Q3. When connecting you get “Permission denied (publickey)”.

Section titled “Q3. When connecting you get “Permission denied (publickey)”.”

Cause and checks:

  1. Verify that the SSH private key you use on your local PC (id_rsa, etc.) matches the public key you registered with the server.
  2. Confirm that the port is -p 2222 and that the username is exactly [person]@[instance] as told by the operator.
  3. If the problem persists, ask the platform operator to confirm whether your public key is listed in the personnel directory.

Q4. Files or folders created via the web interface are not updated on the host server (Permission denied).

Section titled “Q4. Files or folders created via the web interface are not updated on the host server (Permission denied).”

Symptom: When you create a skill folder or file with the web [Artifacts] explorer and then try to save it from a direct editor on the host (local IDE, CLI editor, etc.), you get a permission error. Inside an SSH development container you work as root, so this issue does not appear.

Cause: File creation in the web interface is performed by the api container, which runs as uid 0 (root). The skill/agent folders are bind‑mounted to share the same physical objects with the host, so files created there end up owned by root:root on the host. With a default umask 022, only the owner has write access; others can read.

Solution: Set a default ACL (Access Control List) on the host once. The default ACL takes precedence over umask, so future files created by root will automatically inherit it. Run this from the top‑level repository folder.

Terminal window
# 앞으로 만들어질 것 (기본 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
  • Only the second line uses rwX (capital). This gives execute permission only to directories; regular files like .py are skipped. Lowercase would mark all source files as executable, which Git would treat as a permission change.
  • No container restart is needed. ACLs are attributes of the host filesystem and take effect immediately across mounts.
  • The target is limited to .skills and .agents because under instances/ there are folders (like Neo4j data) that the container must own.

Verification: If you see two lines in the output below, everything is set correctly.

Terminal window
getfacl -p instances/<도메인>/.skills/<프로젝트>
group:계정명:rwx
default:group:계정명:rwx

⚠️ Do not do this: Lowering the engine container to a normal user to adjust permissions is not recommended. When launching a skill it creates a virtual environment inside that folder and runs pip install. Because the path is owned by root, the platform cannot write to it itself. Contact the operator—this is not something the maintainer should fix.

Q5. You are repeatedly prompted for a password when connecting (no password works).

Section titled “Q5. You are repeatedly prompted for a password when connecting (no password works).”

Cause: If public key authentication fails, the screen asks for a password, but the root account has password login disabled, so nothing works. In other words, it’s not a “password issue” but that the public key does not match the server.

Fix: Follow the steps in 🪟 Windows User Self‑Diagnosis starting with Diagnostic 1 (fingerprint comparison). Usually this means either (1) you are using a different key than the one registered on the server, or (2) Antigravity is not carrying your private key.

(주)지오유 · 경기 용인시 처인구 유림로154번길(유방동 673-2) 20-13

CEO 신달수·Business no. 142-81-36612·E-commerce no. 용인처인-0118호·Privacy officer 신달수·Email shindalsoo@gmail.com·Tel 1833-3623·Fax 02-6918-4006