조립스페이스 문서

설치와 연결

터미널에서는 CLI를 사용하고, AI 에이전트에는 MCP를 연결할 수 있습니다. PROJECT는 실제 프로젝트 이름으로 바꾸세요.

npm install -g @joripspace/cli@latest
joripspace login
joripspace start PROJECT

codex mcp add joripspace --url https://api.joripspace.com/mcp
codex mcp login joripspace

claude mcp add --transport http joripspace --scope user https://api.joripspace.com/mcp

빠른 시작

터미널과 파일을 사용할 수 있는 AI 코딩 에이전트에서 시작하세요.

1. 프로젝트 준비

   프로젝트에서 사용할 프로젝트를 열거나 생성합니다. start는 이미 존재하는 프로젝트에 연결하는 명령입니다.

2. 작업 폴더 열기

   에이전트에서 프로젝트 코드를 저장할 폴더를 엽니다. 기존 코드가 있다면 해당 작업 폴더에서 시작하세요.

3. 메시지 전달

   아래 PROJECT 두 곳을 실제 프로젝트 이름으로 바꿔 전달하세요. 프로젝트의 시작하기 탭에서는 이름이 포함된 메시지를 바로 복사할 수 있습니다.

JoripSpace 프로젝트 `PROJECT`를 시작해줘.

1. `npm install -g @joripspace/cli@latest`로 공식 CLI를 설치하거나 업데이트해줘.
2. `joripspace start PROJECT --json`을 실행하고, 반환된 온보딩 안내와 에이전트 문서를 읽어 연결을 완료해줘.
3. 기존 프로젝트 상태를 확인하고, 제작·배포를 이어가기 위한 다음 단계를 안내해줘.

연결 승인이 필요하면 에이전트가 안내한 조립스페이스 화면에서 승인하고 일회용 연결 코드를 전달하세요. 연결 후에는 만들 기능을 설명해 제작과 배포를 요청할 수 있습니다.

AI 에이전트 연결

start로 연결하면 에이전트가 프로젝트 상태와 개발에 필요한 안내를 받을 수 있습니다. 연결을 마친 뒤 같은 대화에서 만들 기능을 설명하세요.

AGENTS.md

에이전트가 참고하는 프로젝트 개발 안내입니다. 기존 문서에 조립스페이스 연결 정보가 추가됩니다.

CLAUDE.md

Claude Code에서 AGENTS.md를 참고할 수 있도록 연결하는 파일입니다. 안내가 적용되지 않으면 에이전트에 파일을 읽어 달라고 요청하세요.

연결 정보

연결 결과의 onboarding.invocation에는 에이전트가 다음 명령에 사용할 실행 경로와 작업 폴더가 담깁니다.

CLI로 연결할 때는 별도 플러그인이나 MCP 설정 없이 시작할 수 있습니다. 명령을 실행하고 프로젝트 파일을 편집할 수 있는 코딩 에이전트를 사용하세요.

빈 프로젝트라면 템플릿을 선택해 시작할 수 있습니다. 기존 코드가 있다면 해당 소스와 배포 상태를 확인한 뒤 작업을 이어가세요.

CLI 설치와 실행

Windows, macOS, Linux에서 Node.js 18 이상과 npm이 필요합니다. 새 환경에는 지원 중인 Node.js LTS를 사용하세요. 전역 설치 후 업데이트하려면 npm install -g @joripspace/cli@latest를 다시 실행합니다.

전역 설치 없이 실행

npx -y @joripspace/cli@latest start PROJECT

일반 출력과 에이전트 JSON 출력

터미널에서 직접 작업할 때는 일반 명령을 사용하면 안내에 따라 값을 입력할 수 있습니다. 에이전트나 자동화 스크립트에서는 --json을 붙여 결과를 JSON으로 받으세요. 이 모드에서는 브라우저를 열거나 터미널 입력을 기다리지 않습니다. 권한을 추가하거나 프로젝트 필수 동의에 대신 동의하는 옵션은 아닙니다.

joripspace start PROJECT --json

로그인이 필요하면 응답에 포함된 연결 URL을 브라우저에서 여세요. 연결을 승인한 뒤 받은 일회용 코드를 아래 CONNECTION_CODE에 넣어 로그인하고 start를 다시 실행합니다.

joripspace login --code "CONNECTION_CODE" --json

무료 프로젝트 생성과 기존 프로젝트 연결

joripspace create --name my-new-app
joripspace start my-new-app

create는 로그인 후 웹과 같은 이름 검증과 기존 필수 동의 절차로 무료 프로젝트를 만듭니다. start는 기존 프로젝트에 연결하며 조회에 실패했다고 새 프로젝트를 만들지 않습니다. 에이전트는 create --json으로 전체 동의문을 받아 사용자 언어로 안내하고, 명시적인 동의를 받은 뒤에만 동의 옵션을 전달해야 합니다.

로그인 저장과 로그아웃

로그인 정보는 Windows 자격 증명 관리자, macOS Keychain 또는 Linux Secret Service에 저장되어 같은 OS 계정의 다른 프로젝트 폴더에서도 사용할 수 있습니다. OS 보안 저장소를 사용할 수 없는 환경에서는 현재 폴더의 Git 제외 파일 .env.joripspace를 사용합니다. 보안 저장소에 저장하거나 저장 결과를 확인하는 중 오류가 발생하면 로그인이 중단됩니다.

logout은 현재 계정의 OS 자격 증명과 현재 폴더의 저장된 인증정보를 제거합니다. 다른 기존 폴더나 직접 설정한 환경변수 토큰은 별개이며, 서버 토큰을 폐기하는 명령은 아닙니다. 다른 폴더에는 --cwd를 사용하고 공백이 있는 경로는 따옴표로 감싸세요. 일반 앱 .env 파일은 CLI 로그인에 사용하지 않습니다.

joripspace logout

명령어 확인

joripspace --version
joripspace --help
joripspace start --help

MCP 설정과 인증

조립스페이스는 원격 Streamable HTTP MCP 서버를 제공합니다. 에이전트에 URL을 등록하며 별도 조립스페이스 MCP 서버 패키지는 설치하지 않습니다.

https://api.joripspace.com/mcp

Codex CLI

codex mcp add joripspace --url https://api.joripspace.com/mcp
codex mcp login joripspace

브라우저 인증을 마친 뒤 codex mcp list 또는 Codex의 /mcp에서 연결을 확인하세요. 새 서버가 표시되지 않으면 에이전트를 다시 불러오거나 새 세션을 시작합니다.

Claude Code

claude mcp add --transport http joripspace --scope user https://api.joripspace.com/mcp

Claude Code에서 /mcp를 실행하고 조립스페이스를 선택해 브라우저 인증을 완료하세요. user 범위로 등록한 연결은 여러 프로젝트에서 사용할 수 있습니다.

다른 HTTP MCP 클라이언트

클라이언트의 MCP 설정에서 이름 joripspace와 위 URL로 원격 HTTP 서버를 추가하고 로그인 또는 OAuth 인증을 진행하세요. CLI 로그인과 MCP 클라이언트 인증은 별개이며, CLI 설치만으로 MCP 인증이 완료되지는 않습니다.

연결 후 에이전트에게 조립스페이스 프로젝트 목록을 확인하고 PROJECT에 연결하도록 요청하세요. 무료 프로젝트 생성은 사용자의 명시적인 확인과 기존 필수 동의를 거쳐 진행합니다. MCP에서 비밀 키를 직접 등록·교체할 때는 프로젝트 웹 비밀 키 페이지를 안내합니다.

클라이언트 공식 설정 안내: OpenAI Docs · Claude Code

제작과 배포

조립스페이스의 기본 서버 프레임워크는 Hono입니다. API와 웹페이지를 하나의 프로젝트에서 만들 수 있습니다. Hono 가이드에서 예제 앱을 실행하고 배포해 보세요.

1. 현재 상태 확인

   에이전트가 기존 소스, 프로젝트 실행 스크립트와 start의 다음 작업을 확인합니다.

2. 구현과 로컬 검증

   만들거나 수정할 기능을 전달하세요. 프로젝트에 맞는 빌드·검사를 실행하고 실제 화면과 동작을 확인합니다.

3. 조립스페이스로 배포

   프로젝트의 배포 탭에서 GitHub 연결과 저장소 선택을 진행하세요. 브랜치 push 방식은 에이전트가 연결된 브랜치에 코드를 push하면 기존 GitHub Actions가 자동 배포합니다. 릴리스 방식은 설정된 릴리스 트리거를 따릅니다. 그 외에는 프로젝트에 맞는 CLI 배포 명령을 사용합니다.

4. 공개 주소 확인

   배포 결과와 서비스 URL을 확인하고 요청한 기능이 실제로 동작하는지 검증합니다.

연결을 마쳤다면 만들고 싶은 기능을 설명하세요. 구현 결과를 확인한 뒤 배포를 요청하면 됩니다.

현재 프로젝트의 구조를 확인하고 요청한 기능을 구현해줘. 로컬에서 빌드와 동작을 검증한 뒤 조립스페이스에 배포하고, 실제 서비스 주소와 확인 결과를 알려줘.

DB와 스토리지

DB · env.DB

서비스에서 조회·수정할 구조화된 데이터를 저장합니다. 실제 조회 조건과 인덱스를 함께 설계하고 스키마 변경은 마이그레이션으로 관리하세요.

스토리지 · env.STORAGE

사용자가 업로드한 파일과 운영 중 생성한 파일을 저장합니다. 파일의 메타데이터는 DB에서 관리할 수 있습니다.

배포에 포함할 파일

로고, 고정 디자인 이미지 같은 사이트 자산은 프로젝트 소스에 포함합니다. 업로드 파일과 구분해 관리하세요.

아래 도움말에서 현재 CLI가 지원하는 DB·파일 관리 명령을 확인할 수 있습니다.

joripspace db --help
joripspace storage --help

외부 서비스 비밀 키는 프로젝트 Secret으로 관리하고 브라우저 코드나 공개 저장소에 넣지 마세요.

프로젝트 비밀 키 관리

프로젝트의 비밀 키 탭에서 API 키나 외부 서비스 인증 값을 등록하고 교체할 수 있습니다. CLI와 MCP가 안내하는 비밀 키 관리 링크로도 이동할 수 있으며, 페이지 주소는 /projects/PROJECT/?tab=secrets입니다.

joripspace secret list --project PROJECT
joripspace secret generate --project PROJECT --name SESSION_SECRET

CLI로 값 등록·교체

자동화 환경에서는 표준 입력으로 값을 전달할 수 있습니다. 새 키 등록과 기존 값 교체에 set 또는 update를 사용하세요.

joripspace secret set --project PROJECT --name API_KEY --value-stdin --json
joripspace secret update --project PROJECT --name API_KEY --value-stdin --json

set과 update는 새 키를 등록하거나 기존 키의 값을 교체합니다. 실제 값은 에이전트나 비밀 키 관리자가 표준 입력으로 전달해야 하며, 위 명령은 값 입력 질문을 띄우지 않습니다. 줄바꿈을 포함한 UTF-8 원문이 유지되고 값은 응답에 반환되지 않습니다. 직접 값을 입력하려면 웹 비밀 키 페이지를 사용하세요.

MCP는 비밀 키 메타데이터 조회와 값을 노출하지 않는 생성을 지원합니다. 직접 등록·교체·삭제는 웹 페이지에서 진행하며, CLI의 비밀 키 삭제도 웹에서 처리합니다. 값은 채팅·명령 인자·브라우저 코드·공개 저장소·로그에 넣지 마세요.

문제 해결

공식 자료와 지원

문의: support@cosmosfarm.com