IDE와 터미널에서 작업하기

포털 화면은 개발 중입니다. 화면의 낱말과 배치는 바뀔 수 있고, 단추가 실행하는 명령은 이미 만들어져 있습니다.

작업공간이 「실행 중」이면 브라우저의 VS Code 호환 편집기와 터미널, Claude Code로 지금까지 하던 대로 일합니다. 이 페이지는 작업공간 안에서 알아 두면 좋은 것을 모았습니다.

IDE 열기

작업공간이 「실행 중」일 때 [IDE 열기]를 누르면 새 탭에 VS Code 호환 편집기(code-server)가 열립니다. 누를 때마다 새 탭이 열리고, 탭을 여러 개 써도 됩니다. IDE의 메뉴는 영어입니다.

작업공간마다 주소가 따로라서, 한 작업공간에서 연 페이지가 다른 작업공간이나 포털에 닿지 않습니다.

열리지 않으면 까닭을 적은 화면이 나옵니다. 예를 들어 「작업공간이 꺼져 있습니다: ws-0012」가 나오면 포털에서 시작한 다음 다시 여세요.

두 폴더

작업 폴더는 홈 폴더(~) 전체입니다. 설치한 파이썬 패키지와 설정, Claude 대화 기록(~/.claude)도 여기에 남고, 결과를 내보낼 때 함께 저장됩니다. 작업 폴더에는 용량 상한이 있습니다.

/data에는 쓸 수 없습니다. 원본을 고친 파일이 필요하면 ~/project 아래에 새로 만드세요. 원본을 작업 폴더로 통째로 복사해 두지는 마세요. 필요할 때 /data에서 읽으면 됩니다.

IDE에서 파일을 열어 보고 내려받을 수 있습니다. IDE를 거친 파일 전송은 기록됩니다.

Claude Code

IDE의 Claude Code 창을 열거나 터미널에서 claude 명령을 실행합니다. 연결한 토큰으로 이미 로그인되어 있습니다.

모든 작업공간의 Claude는 같은 작업공간 규칙을 받습니다. 연구자도 에이전트도 이 규칙 파일을 고칠 수 없습니다.

• 데이터는 /data에서 읽습니다.
• 코드는 ~/project 아래에, 결과(모델, 그림, 표, 지표)는 ~/project/outputs 아래에 둡니다.
• 랜덤 시드를 고정합니다.
• 결과를 만들면 처음부터 다시 만드는 명령을 ~/project/reproduce.sh 파일에 적습니다.
• 표는 같은 폴더의 설명 파일(table.yaml)부터 읽습니다.
• 막힌 인터넷 주소는 돌아가려 하지 말고 연구자에게 알립니다.
• 데이터 더하기와 결과 내보내기는 요청만 합니다. 연구자가 승인해야 실행됩니다.

규칙을 지키는 것은 모델에 달려 있습니다. Claude가 만든 코드와 재현 명령 파일은 직접 확인하세요.

작업공간 정보 파일(/run/synapse/workspace.json)에 이 작업공간의 데이터 목록과 인터넷 규칙이 있고, Claude도 이 파일을 읽습니다. Claude에게 데이터를 알려 줄 때는 [내 데이터]의 「작업공간 안 경로」를 그대로 쓰면 됩니다.

재현 명령 파일

결과를 내보내려면 재현 명령 파일이 있어야 합니다. 결과를 처음부터 다시 만드는 명령을 차례로 적은 셸 스크립트이고, 보통 ~/project/reproduce.sh 파일입니다.

#!/bin/sh
# 결과를 처음부터 다시 만드는 명령 (예시)
set -e
cd ~/project
pip install --user scikit-learn==1.5.2
python train.py --seed 0 --data /data/images/ct_2024 --out outputs/
python evaluate.py --checkpoint outputs/model.pt --out outputs/roc_curve.png

좋은 재현 명령 파일은 이렇습니다.

• 랜덤 시드를 고정합니다.
• 데이터는 /data에서 읽습니다.
• 필요한 패키지를 버전까지 정해 설치하는 명령도 적습니다.
• 결과는 ~/project/outputs 아래에 씁니다.

지금은 결과를 내보낼 때 이 파일이 있는지만 확인하고, 실행하지는 않습니다.

표 데이터 읽기

표 하나는 /data/tables/<표 이름>/ 폴더에 든 Parquet 파일들입니다. 같은 폴더의 설명 파일(table.yaml)에 열의 뜻, 단위, 코드 체계, 결측값 규칙이 있으니 먼저 읽으세요.

DuckDB로 읽을 수도 있습니다. 작업공간마다 표 이름으로 바로 읽을 수 있게 준비된 DuckDB 파일이 있고, 읽기 전용으로 엽니다.

import duckdb

con = duckdb.connect("/home/researcher/.synapse/data.duckdb", read_only=True)
con.sql("select count(*) from patients").show()

이 파일은 이 작업공간의 데이터가 바뀌면 다시 만들어집니다. 내가 만드는 표는 다른 파일에 두세요.

패키지 설치

파이썬 패키지는 내 작업 폴더에 설치합니다. 작업 환경을 다시 만들어도 남습니다.

시스템 패키지는 Ubuntu 저장소에서 설치합니다.

• sudo apt-get install 명령으로 설치한 패키지는 기록되어, 작업 환경을 다시 만들면 다시 설치됩니다. 결과를 내보낼 때 저장되는 환경에는 설치한 그대로 남습니다.
• 결과가 그 패키지에 기대면 설치 명령을 재현 명령 파일에도 적으세요.
• sudo pip 명령은 쓰지 마세요.
• 패키지 저장소에 닿으려면 이 작업공간의 인터넷 규칙이 열어 줘야 합니다. 기본 규칙인 「패키지 저장소」는 PyPI와 Ubuntu apt, VS Code 확장을 엽니다.
• VS Code 확장은 Open VSX에서 받습니다. Microsoft만 배포하는 확장은 없을 수 있고, 「Claude만」 규칙인 작업공간에서는 확장을 설치할 수 없습니다.

오래 걸리는 작업

IDE 탭을 닫아도 터미널은 끝나지 않습니다. 다시 열면 같은 터미널로 돌아오고, 최근 100줄까지 보입니다. IDE가 다시 시작되어도 tmux와 screen 안의 작업은 계속됩니다. 몇 시간 걸리는 학습은 tmux나 screen 안에서 돌리세요.

Ctrl+B 다음 D를 누르면 빠져나옵니다. 다시 붙으려면 이렇게 합니다.

쓰지 않는다고 작업공간이 저절로 꺼지지는 않습니다. 대신 [정지]를 누르면 tmux와 screen 안의 작업도 모두 끝납니다.

GPU

관리자가 작업공간마다 GPU 메모리 상한을 정합니다. 여러 작업공간이 GPU 하나를 함께 쓸 수 있습니다. 쓰는 양이 상한의 90%에 닿으면 작업공간 안의 알림 파일(/run/synapse/gpu-notice.txt)에 경고 줄이 붙고, Claude도 이 파일을 읽을 수 있습니다. 상한을 넘으면 그 작업공간에서 가장 큰 프로세스를 끝냅니다. 작업공간 화면의 「GPU 메모리」에 쓰는 양과 상한이 나옵니다.

메모리가 모자라 프로세스가 끝나면 작업공간 화면에 「메모리가 모자라 프로세스 하나가 끝났습니다」가 나옵니다. 작업 환경은 계속 켜져 있습니다.

인터넷이 막힐 때

작업공간은 인터넷에 바로 나갈 수 없고, 관리자가 작업공간마다 정한 인터넷 규칙으로만 프록시를 거쳐 나갑니다. 이 작업공간의 규칙은 작업공간 화면의 「인터넷 규칙」에서 볼 수 있습니다.

막힌 요청은 [접속 기록 보기]에서 여는 「인터넷 접속 기록」에 「막힘」으로 남습니다. 「막힌 것만」으로 거를 수 있습니다. 작업에 필요한 곳이면 그 주소를 관리자에게 알려 주세요. 관리자가 규칙을 바꾸면 켜져 있는 작업공간에도 바로 적용됩니다.

at                workspace  method   target                      status  allowed2026-10-22 09:07  ws-0012    CONNECT  huggingface.co:443          403     no2026-10-22 09:31  ws-0012    CONNECT  github.com:443              403     no

git, pip, curl처럼 프록시 설정을 따르는 프로그램은 그대로 씁니다. ssh처럼 따로 프록시 설정이 필요한 프로그램도 있습니다. 작업공간 안에서는 외부 DNS를 직접 조회할 수 없습니다.

작업공간 안의 명령

작업공간 터미널에서 synapse help 명령을 실행하면 이 작업공간에서 쓸 수 있는 명령과 쓰는 법이 나옵니다. 작업공간 인자를 빼면 이 작업공간을 뜻합니다.