SPACE로 에이전트의 명령 실행 도구를 만들 때는 GET /v1/sessions/{session_id}/events를 읽기 전용 로그 조회로 분류하지 않는 편이 좋습니다. 준비된 명령 세션에 처음 인증된 연결을 붙이면 실제 프로세스가 시작될 수 있기 때문입니다. 작은 팀의 관리 화면이나 에이전트 도구에서는 실행과 스트림 수집을 한 동작으로 묶고, 상태·저장 로그 조회를 따로 제공하는 구성이 이해하기 쉽습니다.
확인일: 2026년 10월 16일. SPACE 소스 기준: b9fc395e, 문서·Cargo 기준 버전 0.8.0. 명령 실행(Process) 세션을 다룹니다. 공식 문서와 소스를 검토해 AI의 도움으로 정리했으며, SPACE 설치·명령 실행·장애 재현은 하지 않았습니다. 아래 서비스와 권한 설계는 가상 예시입니다.
SPACE에서 명령 세션과 프로세스는 다릅니다
SPACE는 Perplexity가 공개한 Firecracker 마이크로VM 기반 코드 실행 플랫폼입니다. 애플리케이션이 HTTP API로 작업 환경을 만들고 명령을 실행하면, SPACE가 샌드박스와 프로세스, 출력 연결을 관리합니다. 저장소는 10월 1일 생성됐고, 공식 블로그 목록에는 소스 공개 발표가 10월 15일로 표시돼 있습니다.
최근 관심을 보여 주는 자료도 있습니다. 10월 16일 10:33 UTC에 확인한 Trendshift의 날짜별 집계는 10월 15일 별 증가를 120개, 16일을 411개로 표시했습니다. 16일 수치는 진행 중인 날짜의 집계이며, 집계 경계와 증가량을 별도로 재측정하지 않았습니다. 관심 신호로 볼 수 있지만 도입 실적이나 안전성의 증거는 아닙니다.
이 글에서 볼 부분은 명령 실행의 경계입니다. 공식 아키텍처 문서는 다음 순서를 설명합니다.
- 명령 세션을 만들면 프로세스 ID와 연결 정보가 할당됩니다.
- 해당 세션의 이벤트 스트림에 연결하면 프로세스가 시작됩니다.
- 클라이언트는 출력과 종료 결과를 수집합니다.
따라서 프로세스 ID가 생겼다는 사실만으로 실행 중이라고 표시하면 안 됩니다. 샌드박스가 실행 가능한 상태인지, 명령이 실제로 시작됐는지, 종료 결과를 확보했는지도 각각 다른 질문입니다.
GET인데 실행이 시작되는 경로를 확인합니다
라우트 정의에서 이벤트 스트림은 GET으로 선언돼 있습니다. 서버 처리 코드는 연결 토큰과 세션을 확인한 뒤 프로세스 스트림을 준비합니다. 토큰 없이 주소만 열어 임의 명령을 실행한다는 뜻은 아닙니다.
핵심은 그 뒤의 시작·연결 분기입니다. 이미 연결된 프로세스 ID가 있으면 기존 프로세스에 연결하고, 없으면 세션에 준비된 명령으로 시작 요청을 만듭니다. 앞선 시작이 성공했지만 연결 기록이 남지 않은 경우에도 기존 프로세스로 연결하는 복구 분기가 있습니다.
모든 GET이나 재연결이 명령을 다시 실행한다는 설명은 틀립니다. 여기서 주의할 것은 아직 시작하지 않은 명령에 대한 첫 연결입니다. 공식 Python 예제도 명령 세션을 만든 뒤, 반환된 연결 토큰으로 이벤트 URL을 여는 순서를 사용합니다. 이 동작을 애플리케이션에서 ‘로그 보기’라고 이름 붙여도 실행 효과는 그대로 남습니다.
가상 예시: 합성 CSV 작업을 보는 도구 네 가지
작은 팀이 합성 CSV를 요약하는 내부 도구를 만든다고 가정하겠습니다. 에이전트가 실행안을 제안하고 사람이 실행 여부를 결정하며, 이후 다른 사람이 상태나 로그를 확인합니다. 이때 도구를 다음 네 가지로 나눌 수 있습니다. 이름은 설계 예시이며 SPACE의 공식 API 이름이 아닙니다.
- 1. 실행안 미리 보기
애플리케이션 안에서 명령 인자, 대상 샌드박스, 작업 디렉터리, 입력 파일, 환경 설정과 제한 시간을 보여 줍니다. 이 단계에서는 SPACE API를 호출하거나 명령 세션을 만들지 않습니다. 사용자가 내용을 살피는 행위가 실행 준비용 원격 변경으로 이어지지 않게 합니다.
- 2. 승인된 명령 실행과 스트림 수집
확인된 실행안을 기준으로 명령 세션을 만들고 첫 스트림 연결을 수행합니다. 명령 실행 효과가 있는 도구로 분류하고, 애플리케이션의 실행 권한을 검사합니다. 반환된 세션·프로세스 ID와 이벤트 기록을 해당 작업에 연결합니다.
- 3. 현재 프로세스 상태 조회
이미 알고 있는 샌드박스·프로세스 ID로 상태를 확인합니다. 조회 과정에서 새 명령 세션을 만들거나 이벤트 스트림에 처음 연결하지 않습니다. 상태를 읽는 도구 안에 실행이나 샌드박스 깨우기를 숨겨 넣지 않는 것이 이 설계의 조건입니다.
- 4. 저장된 로그 조회
수집기가 애플리케이션 쪽에 저장한 이벤트 기록을 읽습니다. 기록이 없거나 불완전하면 그 상태를 보여 줍니다. 로그를 채우기 위해 원래 명령을 실행하는 동작은 넣지 않습니다. 저장 로그 자체의 접근 권한과 민감 정보 처리도 별도로 적용합니다.
흐름으로 정리하면 ‘로컬 실행안 → 실행 승인 → 세션 생성과 첫 연결 → 로그 저장’입니다. 관찰자는 이 흐름의 마지막에 쌓인 상태와 로그를 읽습니다. 이미 세션을 만들어 두는 다른 설계를 쓰더라도, 실제 실행 권한을 확인해야 할 경계는 첫 연결 앞에 남습니다.
승인은 어떤 실행안에 묶였는지도 남깁니다
이 가상 서비스에서는 승인 당시의 명령 인자, 대상 샌드박스, 작업 디렉터리와 입력 파일, 실행에 영향을 주는 환경 설정, 제한 시간을 하나의 실행안으로 고정합니다. 사용자가 합성 CSV 요약을 확인했는데 실행 직전에 다른 디렉터리나 명령으로 바뀐다면 같은 승인으로 처리하지 않는 방식입니다. 이는 SPACE가 대신 제공한다고 확인한 승인 기능이 아니라, 도구를 감싸는 애플리케이션의 설계 제안입니다.
화면이나 일반 작업 로그에 비밀값을 그대로 남길 필요는 없습니다. 환경 설정은 필요한 항목과 비밀 참조를 구분하고, 자격 증명과 연결 토큰은 별도 보호 경로에서 다룹니다. SPACE의 관리 API 토큰과 명령 연결 토큰도 용도가 다릅니다. 공식 예제는 반환된 이벤트 URL의 출처와 세션 경로를 검사한 뒤 연결 토큰을 사용합니다. 편의를 위해 이 검사를 없애는 방향으로 감쌀 이유는 없습니다.
권한 분리의 확인 질문도 구체적으로 만들 수 있습니다. ‘미리 보기와 저장 로그 조회만 호출했을 때 SPACE 명령 세션 생성과 첫 연결 요청이 발생하지 않는가?’, ‘승인 뒤 실행안이 달라지면 실행을 막는가?’입니다. 이는 앞으로 구현에서 검증할 조건이며, 이 글에서 해당 동작을 실행해 확인한 결과는 아닙니다.
결과를 모르면 조회 화면에도 모른다고 표시합니다
관찰 경로를 분리해도 실행 결과를 추측하면 문제가 남습니다. 문제 해결 문서에 따르면 프로세스 조회의 not_found는 첫 연결 전과 프로세스 종료 후 모두 나타날 수 있습니다. HTTP 연결이 닫힌 사실도 성공 증거가 아닙니다. 완료 판단에는 수집한 종료 이벤트와 종료 코드가 필요합니다.
또한 출력은 내구성 있는 과거 로그 저장소가 아니라 실시간 스트림입니다. resync_required가 보고되면 빠진 출력이 다시 재생됐다고 가정하지 않아야 합니다. 이 경우 조회 화면은 ‘결과 확인 필요’처럼 불확실성을 유지하고, 명령을 다시 실행하는 결정은 별도 실행 경로로 보냅니다. 세션 수준의 중복 방지와 명령 내부의 외부 부작용까지 한 번만 일어나는 보장은 같은 것이 아닙니다.
도입 판단: 이 경계를 배운다고 바로 운영할 필요는 없습니다
SPACE 코드는 Apache 2.0 라이선스입니다. 다만 확인한 0.8.0은 문서와 소스의 공개 기준 버전이며, 확인 시점 GitHub Releases 목록은 비어 있었습니다. 1.0 이전에는 마이너 버전에서 호환성을 깨는 변경이 가능하다고 명시돼 있습니다.
로컬 설치 안내는 KVM을 쓸 수 있는 Linux x86_64, 필요한 장치 접근, btrfs, 권한 있는 Docker 컨테이너와 Kind 구성을 요구합니다. macOS에 직접 설치하는 안내가 아니며, 전체 플랫폼이 모든 배포에서 Kubernetes를 필수로 요구한다는 뜻도 아닙니다. 운영 인프라와 관리 부담은 팀이 따로 평가해야 합니다.
이미 코드 실행 서비스를 만들고 있고 VM 단위 환경과 수명주기 관리가 필요하다면 SPACE의 계약을 검토할 이유가 있습니다. 단순히 작업 상태와 로그를 보여 주려는 팀이라면 기존 실행기와 로그 저장소로 요구를 충족할 수 있는지 먼저 판단하는 편이 낫습니다.
이 글의 결론은 도구의 권한을 HTTP 동사나 화면 이름만으로 정하지 말자는 것입니다. SPACE에서는 명령 스트림의 첫 인증 연결이 실행 경계입니다. 그 경계를 실행 도구에 명확히 두면, 사람이 상태를 살피는 행위와 에이전트가 새 일을 시작하는 행위를 분리할 수 있습니다.
댓글
댓글 쓰기