Linux VPS에 Agentlas OS v1.2.0 자가 호스팅 설치 방법

Agentlas OS의 실체

Agentlas OS는 전문 에이전트를 패키지 형태로 디스크에 저장하고, 각 작업마다 임시 오케스트레이터를 구성하는 오픈 소스 에이전트 런타임입니다. 사용자는 Linux VPS의 사용자 계정에 직접 설치하여 이를 자가 호스팅합니다. 이는 서비스가 아닙니다. 데몬, 리스닝 포트, 웹 인터페이스, 컨테이너 이미지가 저장소에 존재하지 않습니다.

마지막 문장이 이 페이지의 모든 내용을 결정합니다. 대부분의 멀티 에이전트 시스템은 에이전트를 유지하고 관리하는 슈퍼바이저 프로세스를 실행합니다. Agentlas는 이를 반대로 수행합니다. 전문 에이전트는 정지된 파일로 존재하며, 오케스트레이터는 작업이 실행되는 동안에만 존재합니다. 실질적인 결과로, 유휴 상태의 허브는 메모리가 아닌 디스크 용량만 차지합니다.

이 프로젝트는 오픈 코어를 Hephaestus라고 부르며, 명령어, 경로, 환경 변수에서 이 이름을 확인할 수 있습니다. 저장소는 agentlas-ai/Agentlas-OS이며, Apache-2.0 라이선스를 따르고 대부분 Python으로 작성되었습니다.

이 프로젝트의 초기 단계 수준에 대하여

이 저장소는 2026년 6월 4일에 생성되었습니다. 2026년 8월 12일 기준으로 약 10주가 되었으며, 대략 1,150개의 별과 112개의 포크를 기록하고 있습니다. 실제 업무 환경에 적용하기에는 다소 이른 시기입니다.

프로젝트의 나이보다 릴리스 주기가 더 중요합니다. 버전 v1.1.103은 2026년 8월 8일에, v1.2.0은 2026년 8월 12일에 배포되었습니다. 이는 1.1 시리즈에서만 100개가 넘는 태그된 릴리스가 자동화 도구를 통해 배포되었음을 의미하며, 어떤 날에는 하루에 여러 번 릴리스되기도 했습니다. 이처럼 빠르게 변화하는 프로젝트는 화요일과 목요일 사이에 동작 방식이 바뀔 수 있습니다.

따라서 릴리스 버전을 고정하십시오. 설치 프로그램은 이를 위해 환경 변수를 읽으며, 아래의 모든 가이드는 이 방식을 사용합니다. 하루에도 여러 번 배포되는 프로젝트를 버전을 고정하지 않고 설치하면, 해당 시간에 main에 존재하는 임의의 상태를 그대로 가져오게 됩니다.

VPS에 필요한 사항

백그라운드에서 실행되는 프로세스가 없으므로 요구 사항은 간단합니다.

• Linux VPS. Ubuntu 24.04가 적절한 기준입니다. 설치 프로그램은 uname -s을 통해 운영 체제를 감지하며 Linux의 경우 비 macOS 브랜치를 선택하므로 헤드리스 서버도 지원합니다.
• 서버에 curl, tar, git이 설치되어 있어야 하며, 정상적으로 작동하는 Python 인터프리터가 필요합니다.
• raw.githubusercontent.com 및 github.com로 향하는 아웃바운드 HTTPS 연결. 설치 프로그램은 릴리스 아카이브를 다운로드하고 SHA-256을 확인하므로, 외부 연결이 불가능한 서버에서는 설치할 수 없습니다.
• 호스트 하니스(host harness). 이는 모델과 실제로 통신하는 코딩 에이전트입니다. Claude Code, Codex, opencode, goose, Hermes 어댑터를 모두 지원합니다.

root 권한은 필요하지 않습니다. 설치 프로그램은 사용자의 홈 디렉터리와 ~/.local/bin에만 파일을 작성하며, 경로에 쓰기 권한이 없으면 중단하는 대신 경고를 표시합니다. 아직 서버를 선택 중이라면 VPS에서 코딩 에이전트 실행하기를 참조하여 이 환경의 기반이 되는 베이스 이미지와 접근 설정 방법을 확인하십시오.

고정된 릴리스 설치하기

업스트림 README에는 main의 스크립트를 bash로 바로 파이프하는 한 줄짜리 명령어가 기재되어 있습니다. 해당 스크립트를 먼저 다운로드하여 내용을 확인하십시오. 이 스크립트는 셸 설정 파일과 발견되는 모든 에이전트 하니스에 내용을 기록하므로, 10초 정도 시간을 들여 검토할 가치가 있습니다.

curl -fsSL -o install-all-runtimes.sh \
  https://raw.githubusercontent.com/agentlas-ai/Agentlas-OS/main/scripts/install-all-runtimes.sh
less install-all-runtimes.sh
HEPHAESTUS_REF=v1.2.0 bash install-all-runtimes.sh

HEPHAESTUS_REF가 고정 버전입니다. 스크립트 내부의 해당 라인은 version="${HEPHAESTUS_REF:-v1.2.0}"으로 되어 있으므로, 이를 설정하지 않으면 현재는 v1.2.0이 설치되지만 다음 주에는 다른 버전이 설치될 수 있습니다. 이를 명시적으로 설정하면 10월에 재빌드할 때 8월에 테스트했던 버전이 그대로 설치됩니다.

한 가지 주의할 점이 있습니다. 위 스크립트 URL은 main을 추적하지만, HEPHAESTUS_REF는 스크립트가 다운로드하는 런타임 페이로드를 고정합니다. 이 둘은 서로 다른 대상입니다. 두 가지 모두를 고정하려면 URL에서 main를 v1.2.0로 변경하여 main 대신 태그에서 스크립트를 가져와야 합니다.

설치가 성공하면 다음과 같은 두 줄을 포함하여 스크립트가 기록한 경로가 출력됩니다.

Installed runner: /home/you/.agentlas/runtime/current/bin/hephaestus
Installed shell commands in /home/you/.local/bin (add ~/.local/bin to PATH to use them)

두 번째 줄은 사람들이 흔히 간과하는 부분입니다. 새로 설치한 Ubuntu 환경에서는 PATH에 ~/.local/bin이 없는 경우가 많아, 설치가 성공했음에도 모든 hep-* 명령이 command not found 오류와 함께 실패합니다. 이를 수정하고 확인하십시오.

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
hep-global status

hep-global status은 글로벌 라우터가 무엇을 설치했는지, 어떤 하니스를 감지했는지 보고합니다. 이 명령이 정상적으로 실행된다면 PATH 설정은 올바른 것입니다.

상태가 저장되는 위치

모든 데이터는 홈 디렉터리 아래에 파일 형태로 존재하므로 백업과 마이그레이션이 간단합니다.

• ~/.agentlas/runtime/v1.2.0/는 런타임 자체를 보관하며, ~/.agentlas/runtime/current/은 활성 버전을 가리키는 심볼릭 링크입니다. 두 개의 고정된 버전을 나란히 유지할 수 있습니다.
• ~/.local/bin/는 셸 래퍼인 hephaestus, hep-build, hep-network, hep-search, hep-storm, hep-cloud, hep-upload을 보관합니다.
• ~/.agentlas/networking/memory/는 영구 메모리인 playbook-registry.json, playbook-candidates.jsonl, memory-events.jsonl를 보관합니다.
• ~/.agentlas/networking/hub-agents/<slug>/memory/experience.sqlite은 소유자별로 범위가 지정된 에이전트별 경험을 보관합니다.
• <project>/.agentlas/ontology-runtime.sqlite은 프로젝트별 상태를 보관하므로, 서버가 아닌 저장소와 함께 이동합니다.
• ~/.cache/agentlas/python은 Linux 환경의 Python 캐시를 보관합니다. macOS는 다른 경로를 사용하며, 이는 설치 프로그램이 uname를 통해 선택하는 분기입니다.

메모리 관련 문서에는 비밀 정보, 원시 자격 증명, 전체 대화 기록을 어떤 메모리 범위에도 포함해서는 안 된다고 명시되어 있습니다. 자격 증명 값은 gitignore 처리된 로컬 파일에 보관해야 하며, 메모리에는 이름과 경로만 기록됩니다. ~/.agentlas 디렉터리와 프로젝트의 .agentlas 디렉터리를 백업하면 새로운 VPS에서 환경을 재구축할 수 있습니다.

연동 가능한 모델 백엔드

전체 구성을 재정의하는 핵심 세부 사항은 다음과 같습니다. Agentlas는 모델 API를 직접 호출하지 않으며, 호스트 하네스(host harness)가 이를 수행합니다.

아키텍처 문서에는 각 하네스로 핵심 기능을 변환하는 런타임 어댑터가 기술되어 있으며, 모델 자격 증명은 호스트 런타임이 소유한다고 명시되어 있습니다. Agentlas는 하네스가 가져갈 수 있는 두 가지 인터페이스를 제공합니다. 바로 AgentSkills 파일과 stdio를 통해 통신하는 MCP(Model Context Protocol) 서버입니다. 따라서 "Agentlas가 어떤 모델을 지원하는가"라는 질문은 사실상 "사용자의 하네스가 어떤 모델을 지원하는가"라는 질문과 같으며, Claude Code, Codex, opencode, goose 또는 Hermes가 접근할 수 있는 모든 모델이 그 답이 됩니다.

Codex 스타일의 TOML 설정에서 MCP 서버를 등록하는 방법은 다음과 같습니다.

[mcp_servers.hephaestus-network]
command = "~/.agentlas/runtime/current/bin/hephaestus"
args = ["mcp", "serve"]

동일한 서버가 설치 과정에서 ~/.cursor/mcp.json, ~/.config/goose/config.yaml 및 기타 하네스 설정에 자동으로 등록됩니다. 여러 서버를 하나의 환경에 연결하는 경우, VPS에서 MCP 서버 실행하기에서 stdio 및 프로세스 모델에 대해 더 자세히 다룹니다.

자체 호스팅된 Ollama 엔드포인트 지정하기

하네스가 모델 연결을 관리하므로, Agentlas를 로컬 모델에 연결하려면 하네스를 Ollama로 지정해야 합니다. Ollama는 v0.15에서 이를 위해 launch 하위 명령을 추가했으며, 2026년 8월 11일 기준 v0.32.9 버전에서도 동일하게 제공됩니다. 이 명령은 환경 변수를 설정할 필요 없이 기존 하네스를 로컬 모델에 맞게 구성합니다.

ollama pull qwen3-coder:30b
ollama launch opencode

설치한 하네스에 따라 opencode 대신 claude, codex 또는 droid을 입력하십시오. 그런 다음 로컬 런타임을 통해 요청을 라우팅합니다.

~/.agentlas/runtime/current/bin/hephaestus route "summarise the failing tests" --runtime ollama

라우팅에 성공하면 선택된 에이전트나 팀의 이름이 포함된 JSON 결정과 함께 receipt_id가 반환됩니다. 유용한 응답이 반환되지 않는다면, 일반적인 원인은 컨텍스트 길이 부족입니다. Agentlas 문서에서는 라우팅이 빈번한 세션을 위해 최소 64k 컨텍스트를 지원하는 모델을 요구하며, 예시로 qwen3-coder, gemma3, deepseek-r1를 언급합니다. 코딩 도구에 대한 Ollama의 자체 가이드라인 또한 동일한 64k 기준을 제시합니다. 라우팅 결정 시 프롬프트에 에이전트 목록이 포함되므로, 8k나 32k 컨텍스트 모델을 사용하면 목록이 잘려 잘못된 선택을 하게 됩니다.

태그라인에서는 알려주지 않는 주의 사항이 하나 있습니다. Ollama, Gemma, DeepSeek에는 자체적인 플러그인이나 명령 시스템이 없으므로, /agentlas 슬래시 명령은 사용할 수 없습니다. 로컬 모델 설정에서는 대신 MCP 서버와 hephaestus route 명령을 통해 시스템을 제어해야 합니다. 이는 공격 표면을 실질적으로 줄여주지만, 모델 가중치를 직접 로컬에 유지하기 위해 감수해야 하는 정직한 대가입니다.

유휴 전문가 허브가 사용하는 RAM 비용

비용은 없습니다. 이것이 전체 답변이며, 이를 믿기보다 직접 증명할 수 있습니다.

가져온 허브 전문가는 프로세스가 아닌 패키지 아티팩트로 도착합니다. 전문가는 agent.md와 JSON으로 구성된 .agentlas/ 디렉터리입니다. routing-card.json은 트리거와 기능을, memory-map.json은 쓰기 경계를, mode-map.json는 단독 실행 여부를 정의합니다. Hephaestus Network는 백그라운드 서비스가 없는 인프로세스 스케줄러로 설명됩니다. 작업 사이사이에 직접 확인해 보십시오.

pgrep -af hephaestus
systemctl --user list-units --type=service | grep -i agentlas
du -sh ~/.agentlas

유휴 상태의 장비에서는 첫 두 명령어가 아무것도 출력하지 않습니다. 상주하는 프로세스가 없기 때문입니다. 세 번째 명령어는 대기 중인 허브가 부과하는 유일한 비용인 디스크 사용량을 출력하며, 이는 보유한 전문가 수와 런타임이 제공하는 번들 임베딩 모델에 따라 증가합니다.

따라서 메모리 문제는 전적으로 버스트(burst)에 관한 것이며, 버스트는 사용자의 하네스와 모델 백엔드로 구성됩니다. 하네스가 호스팅된 API와 통신하는 경우 상주 비용은 수백 MB 규모의 프로세스 하나입니다. 가중치를 직접 호스팅하는 경우 가중치가 곧 비용입니다.

[
  {
    "label": "Hosted API model",
    "weights_gb": 0
  },
  {
    "label": "gemma3:4b",
    "weights_gb": 3.3
  },
  {
    "label": "gemma3:12b",
    "weights_gb": 8.1
  },
  {
    "label": "gemma3:27b",
    "weights_gb": 17
  },
  {
    "label": "qwen3-coder:30b",
    "weights_gb": 19
  }
]

위 수치는 벤치마크 실행 결과가 아니라 Ollama 모델 라이브러리에 게시된 다운로드 크기이며, 64k 컨텍스트를 위한 KV 캐시는 위 수치에 추가로 더해집니다. Agentlas 문서에서 가장 먼저 언급하는 모델인 qwen3-coder:30b은 컨텍스트를 제외하고도 19 GB의 가중치가 필요하며, 27B Gemma 변형 모델조차 17 GB를 요구합니다. 이러한 수치에 비하면 Agentlas 계층 자체는 예산에 영향을 미치지 않습니다.

단일 하네스 실행과 비교

호스팅된 API를 대상으로 하나의 하네스를 실행하면 VPS는 단일 프로세스를 유지합니다. Agentlas를 추가해도 동일한 프로세스 하나와 파일들만 추가될 뿐입니다. 오케스트레이터는 장시간 상주하는 별도의 프로그램이 아니며, 디스크의 패키지들로부터 구성된 더 큰 프롬프트일 뿐이고 작업 후에는 폐기됩니다.

변화하는 비용은 메모리가 아니라 컨텍스트입니다. 여러 전문 카드와 라우팅 메타데이터를 불러오는 오케스트레이터는 단순 하네스보다 작업당 더 많은 토큰을 소비합니다. 호스팅된 API 환경에서는 이것이 RAM이 아닌 비용으로 직결됩니다. 로컬 가중치를 사용하는 경우에는 프롬프트가 길어질수록 CPU의 프리필(prefill) 시간이 길어지거나 GPU 점유율이 높아지므로 시간이 비용이 됩니다.

이러한 이유로 이와 같은 서버의 사이징 권장 사항은 에이전트 프레임워크가 아닌 모델 결정에 따라 달라집니다. 코딩 에이전트 VPS를 위한 RAM 및 CPU 사이징에서 이를 상세히 다루고 있으며, 결론은 동일합니다. 실행하려는 백엔드에 맞는 플랜을 선택한 뒤 하네스를 위해 2GB 정도의 여유 공간을 추가하십시오. 비교를 위해 상시 가동되는 슈퍼바이저 설계를 원한다면, 코디네이터를 상주시키는 Omnigent 멀티 에이전트 하네스를 참고하십시오. 이는 정반대의 트레이드오프를 가지며 유휴 메모리 사용량에서 직접적으로 드러납니다.

실패 유형 및 확인되는 메시지

hep-build: command not found 설치 직후 발생. 설치 프로그램이 ~/.local/bin에 기록을 시도했으나, 기본 Ubuntu 이미지의 PATH에는 해당 경로가 존재하지 않습니다. 설치 마지막 줄에 이 내용이 출력되었으나 화면이 넘어가 확인하지 못했을 수 있습니다. 위에서 설명한 export 설정을 추가하십시오.

서버 재구축 후 동작 변경. HEPHAESTUS_REF를 설정하지 않아 설치 프로그램이 당일 기준 최신 태그를 기본값으로 사용했습니다. 버전을 고정하고, 다른 버전 번호와 함께 기록해 두십시오.

로컬 모델에서 라우팅이 잘못된 전문가를 선택함. 모델의 컨텍스트 윈도우가 에이전트 인벤토리를 담기에 너무 작습니다. 64k 이상의 컨텍스트를 지원하는 모델로 변경하고, Ollama의 컨텍스트 길이를 그에 맞춰 설정하십시오. 기본값은 코딩 도구가 요구하는 값보다 낮습니다.

ollama launch 명령을 인식하지 못함. 해당 하위 명령은 Ollama v0.15 버전에서 추가되었습니다. 배포판 저장소의 이전 패키지는 이보다 낮은 버전이므로, 최신 Ollama를 설치하십시오.

설치 프로그램이 예상치 못한 하네스에 기록함. 스크립트가 발견한 모든 하네스를 감지하고 구성하며, ~/.claude/, ~/.codex/, ~/.gemini/, ~/.cursor/ 등에 기록을 수행합니다. 공유 빌드 서버에서 실행할 경우, 스크립트를 먼저 읽어보고 어떤 디렉터리가 영향을 받는지 확인하십시오.

지금 운영 환경에 도입해야 하는가

프로젝트가 시작된 지 10주밖에 되지 않았고 하루에도 여러 번 자동 릴리스가 이루어지는 소프트웨어를 운영 환경의 작업 부하로 사용하는 것은 권장하지 않습니다. 아키텍처는 확실히 흥미롭고 라이선스는 Apache-2.0이며, 파일 기반 설계 덕분에 삭제 시 디렉터리 두 개만 지우면 되어 제거가 간편합니다. 이러한 점들 때문에 시험 삼아 사용해 보기에는 부담이 없으나, 의존성을 갖기에는 위험 부담이 큽니다.

현재로서는 v1.2.0 버전을 고정(pin)하여 언제든 재구축할 수 있는 서버에서 실행하고, ~/.agentlas을 백업에 포함하며, 버전을 올리기 전에 변경 사항(changelog)을 다시 확인하는 것이 합리적인 대응입니다. 이 분야의 다른 대안들과 각 옵션의 성숙도를 폭넓게 살펴보려면 셀프 호스팅 AI 에이전트 요약을 먼저 확인하는 것이 좋으며, VPS에서 Hermes 에이전트 셀프 호스팅하기 문서는 Agentlas가 채택한 하네스 중 하나를 다루고 있습니다.

FAQ

Agentlas OS는 제 VPS에서 서버로 실행되나요?

아니요. 데몬이나 리스닝 포트, 컨테이너 이미지가 저장소에 존재하지 않습니다. 설치 프로그램은 ~/.agentlas/runtime/ 아래에 런타임 환경을, ~/.local/bin에 명령 래퍼를 작성하며, Hephaestus Network는 백그라운드 서비스가 아닌 프로세스 내 스케줄러로 동작합니다. 유휴 상태인 서버에서 이를 확인할 수 있습니다. pgrep -af hephaestus을 실행해도 아무것도 출력되지 않으며, 활성화할 systemd 유닛도 없습니다. 여기서 자가 호스팅이란 서비스가 리스닝 중이라는 의미가 아니라, 코드와 상태가 귀하의 머신 내에 존재한다는 뜻입니다.

유휴 상태인 전문가 허브는 RAM을 얼마나 사용하나요?

유휴 상태의 전문가는 프로세스가 아니므로 RAM을 사용하지 않습니다. 전문가는 agent.md 파일과 routing-card.json, memory-map.json 및 유사한 메타데이터를 담고 있는 .agentlas/ 디렉터리로 구성되므로, 대기 중인 허브는 디스크 공간만 차지합니다. du -sh ~/.agentlas을 사용하여 이를 측정하십시오. 메모리는 작업이 실행되는 동안에만 소비되며, 이를 소비하는 주체는 Agentlas 계층이 아니라 귀하의 하니스(harness) 프로세스와 모델 백엔드입니다.

어떤 모델을 사용할 수 있으며, 제 Ollama 서버를 지정할 수 있나요?

Agentlas는 모델 API를 직접 호출하지 않습니다. 호스트 하니스가 자격 증명과 연결을 관리하므로, 지원되는 모델은 귀하의 하니스가 지원하는 모델과 같습니다. 로컬 가중치를 사용하려면 ollama launch opencode를 실행하십시오(claude, codex 또는 droid로 대체). 이 명령은 환경 변수 없이 귀하의 Ollama 서버에 맞춰 하니스를 구성합니다. 라우팅 프롬프트는 에이전트 인벤토리를 포함하고 있어 작은 컨텍스트 윈도우에서는 정보가 잘릴 위험이 크므로, qwen3-coder이나 gemma3와 같이 최소 64k 컨텍스트를 지원하는 모델을 사용하십시오.

어떤 버전을 설치해야 하며, 왜 버전을 고정(pinning)하는 것이 중요한가요?

설치 프로그램을 실행하기 전에 HEPHAESTUS_REF=v1.2.0를 설정하여 2026년 8월 12일 기준 최신 태그 릴리스인 v1.2.0을 설치하십시오. 스크립트의 기본값은 version="${HEPHAESTUS_REF:-v1.2.0}"이며, 이는 관리자가 다음에 태그를 지정하는 버전을 추적합니다. 이 프로젝트는 1.1 시리즈에서 백 개 이상의 릴리스를 배포했고, 어떤 날에는 여러 번 릴리스하기도 했으므로 버전을 고정하는 것이 평소보다 더 중요합니다. 고정하지 않고 몇 주 뒤에 다시 빌드하면 테스트했던 시스템과 동일한 환경을 보장할 수 없습니다.