# 내 서버·VM 연결하기

> 내가 관리하는 Linux 서버나 VM 에 endue Computer 를 설치해, 에이전트가 endue 클라우드 대신 그곳에 파일을 두고 프로그램을 실행하게 합니다.

내 Linux 서버나 VM 을 에이전트의 **endue Computer** 로 줄 수 있습니다. 그 기기에서 설치 명령 한 줄을 실행하면, 그때부터 에이전트의 파일과 프로그램이 그곳에 있습니다.

## 언제 쓰는가

그 기기에만 있는 것이 작업에 필요할 때 씁니다. 사내망 접근, 이미 설치해 둔 도구와 데이터, 기본보다 많은 CPU·디스크, 내가 고른 지역의 기기 같은 것입니다. 내가 관리하는 Linux 기기라면 무엇이든 됩니다. Vultr 의 VPS, AWS 의 EC2 인스턴스, 사내 서버 모두 됩니다.

이런 사정이 없다면 이 페이지는 필요 없습니다. 에이전트는 처음 필요할 때 endue 클라우드에 endue Computer 를 자동으로 받습니다. [디바이스](/ko/docs/build/devices/)를 보세요.

## 필요한 것

- x86_64 또는 aarch64 의 Linux. 프로그램이 정적 바이너리 하나라 배포판은 상관없습니다.
- systemd.
- `sudo` 로 얻는 root 권한.
- 밖으로 나가는 인터넷 연결. endue Computer 가 보안 WebSocket 으로 endue 에 먼저 연결하므로 들어오는 포트를 열 필요가 없습니다.

## 설치

<Steps>

1. **좌측 사이드바에서 리소스 › 디바이스를 열고** endue Computer 묶음의 **내 기기·서버에 설치**를 누릅니다.

   [에이전트 빌더](/ko/docs/build/agent-builder/)에서 에이전트 하나를 열었다면 **리소스 › 디바이스 › 내 서버에 연결**이 그 에이전트로 같은 일을 합니다.

2. **에이전트를 고르고**, 필요하면 목록에 보일 기기 이름(예: `build-server-01`)을 적습니다. **설치 명령 만들기**를 누릅니다.

   에이전트에 이미 endue 클라우드의 endue Computer 가 있으면, 그것과 그 안의 파일을 먼저 삭제할지 묻습니다. 취소하면 아무것도 바뀌지 않습니다. [에이전트의 endue 클라우드 Computer 를 내 서버로 바꾸기](/ko/docs/build/devices/#에이전트의-endue-클라우드-computer-를-내-서버로-바꾸기)를 보세요.

3. **명령을 복사해 서버에서 실행합니다.** 모양은 이렇습니다.

   ```sh
   curl -fsSL https://download.endue.ai/computer/install.sh | sudo sh -s -- \
     --endpoint <endpoint> --token <token> --instance <agent-id>
   ```

   명령에는 이 에이전트의 연결 토큰이 들어 있고, 한 번만 보입니다. 복사하기 전에 창을 닫았다면 명령을 새로 만드세요.

4. **연결됨을 기다립니다.** 명령이 끝나고 몇 초 뒤 창과 디바이스 목록이 **연결됨**으로 바뀝니다.

</Steps>

<Aside type="caution" title="명령은 묻지 않고 실행됩니다">
  내 서버에서 에이전트는 파일을 쓰고 프로그램을 실행할 때 매번 승인을 받지 않습니다.
  에이전트를 막는 것은 설치 때 정한 것뿐입니다. 전용 사용자, 실행할 수 있는 프로그램 목록,
  네트워크 허용 여부, 아래의 프로필입니다. 에이전트 전용 서버나 VM 을 쓰고, `--allow-exec` 에는
  필요한 것만 두세요.
</Aside>

## 설치 스크립트가 하는 일

1. 아키텍처를 판별해 endue Computer 를 내려받고 SHA-256 체크섬을 대조합니다. 맞지 않으면 아무것도 설치하지 않습니다.
2. 커널이 어떤 [프로필](#프로필)을 지원하는지 확인합니다.
3. 로그인할 수 없는 시스템 사용자 `endue` 를 만듭니다.
4. 에이전트마다 다음을 만듭니다.

   | 경로 | 소유·권한 | 담는 것 |
   | --- | --- | --- |
   | `/etc/endue-computer/<agent-id>.env` | root, `0600` | 접속 주소, 토큰, 고른 설정 |
   | `/var/lib/endue-computer/<agent-id>/workspace` | `endue` | 에이전트의 [워크스페이스](/ko/docs/build/workspace/). 에이전트가 일하는 폴더 |
   | `/var/lib/endue-computer/<agent-id>/state` | `endue` | 체크포인트와 저장한 파일. 워크스페이스 밖에 둡니다 |

5. 에이전트의 systemd 서비스 `endue-computer@<agent-id>` 를 켜고 시작한 뒤, 연결됐는지 알려 줍니다.

## 에이전트가 할 수 있는 일 정하기

설치 명령 끝에 옵션을 붙입니다.

```sh
curl -fsSL https://download.endue.ai/computer/install.sh | sudo sh -s -- \
  --endpoint <endpoint> --token <token> --instance <agent-id> \
  --allow-exec git,python3 --no-network
```

| 옵션 | 기본값 | 효과 |
| --- | --- | --- |
| `--allow-exec <목록>` | `git,node,npm,npx,python3,pip3,curl` | 에이전트가 실행할 수 있는 프로그램. 쉼표로 구분하고 경로 없이 씁니다. `--allow-exec ""` 는 프로그램 실행을 모두 끕니다. |
| `--no-network` | 네트워크 허용 | 에이전트가 실행한 프로그램이 네트워크를 쓰지 못합니다. |
| `--no-delete` | 삭제 허용 | 에이전트가 워크스페이스의 파일을 지우지 못합니다. git·npm 같은 도구는 잠금·임시 파일을 지우므로 `sandboxed` 프로필에서는 실패합니다. |
| `--profile auto\|sandboxed\|managed` | `auto` | 쓸 [프로필](#프로필). |

목록에 있지만 서버에 설치되지 않은 프로그램은 설치 때 알려 줍니다. 에이전트가 그것을 실행하려 하면 "설치되지 않음" 을 받습니다.

허용한 프로그램이 그 프로그램이 하는 일까지 제한하지는 않습니다. `node` 나 `python3` 를 허용하면, 에이전트는 프로필의 경계 안에서 그것들로 어떤 코드든 실행할 수 있습니다.

## 프로필

| 프로필 | 조건 | 에이전트가 실행한 프로그램이 할 수 없는 것 |
| --- | --- | --- |
| `sandboxed` | Linux 6.12 이상 (Landlock ABI 6) | 워크스페이스 폴더 밖의 파일을 읽거나 쓰지 못합니다. `managed` 의 제한도 모두 받습니다. |
| `managed` | 그 밖의 커널. Ubuntu 22.04(5.15), Ubuntu 24.04 GA 커널(6.8) 등 | root 가 되거나 권한을 얻지 못합니다. systemd 가 `/home`·`/root`·다른 에이전트의 폴더를 숨기고 나머지 시스템을 읽기 전용으로 둡니다. 파일시스템 샌드박스는 없어서 `endue` 사용자가 읽을 수 있는 파일은 읽습니다. |

`auto` 는 커널이 지원하면 `sandboxed` 를, 아니면 안내와 함께 `managed` 를 고릅니다. 지원하지 않는 커널에서 `sandboxed` 를 지정하면 설치하지 않고 끝납니다. `managed` 는 에이전트 전용 서버나 VM 에서만 쓰세요.

## 같은 서버에 에이전트 추가하기

서버 하나에 에이전트를 여럿 붙일 수 있습니다. **리소스 › 디바이스**에서 서버 행의 메뉴를 열어 **에이전트 추가**를 누르고, 에이전트를 고른 뒤 새 명령을 같은 서버에서 실행합니다.

에이전트마다 서비스·설정 파일·폴더가 따로 생기고, 프로그램과 `endue` 사용자는 함께 씁니다. `managed` 프로필에서 에이전트끼리 서로의 폴더를 못 보게 하는 것은 systemd 입니다.

## 켜기·끄기와 로그

`<agent-id>` 는 명령의 `--instance` 뒤에 있는 값으로 바꿉니다.

```sh
sudo systemctl status endue-computer@<agent-id>    # 돌고 있는지
sudo systemctl start endue-computer@<agent-id>     # 켜기
sudo systemctl stop endue-computer@<agent-id>      # 끄기
sudo journalctl -u endue-computer@<agent-id> -f    # 로그 따라 보기
```

서비스가 멈춰 있는 동안 디바이스는 **꺼져 있음**으로 보이고, 에이전트는 켜 달라고 알려 줍니다. endue 가 대신 클라우드 Computer 를 만들지 않습니다.

## 다시 설치

같은 `--instance` 로 설치 명령을 다시 실행하면 토큰을 포함한 설정을 바꾸고 서비스를 다시 시작합니다.

에이전트의 서버가 연결돼 있는 동안에는 새 명령을 만들 수 없습니다. 서버에서 서비스를 먼저 멈춘 뒤 명령을 다시 만드세요.

## 제거

```sh
curl -fsSL https://download.endue.ai/computer/install.sh | sudo sh -s -- \
  --uninstall --instance <agent-id>
```

에이전트의 서비스를 멈추고 끄고, 설정 파일을 지웁니다. 워크스페이스와 state 폴더는 `--purge` 를 붙일 때만 지웁니다. `--instance` 없이 실행하면 서버의 모든 에이전트를 제거합니다. 남은 에이전트가 없으면 프로그램과 서비스 정의도 지웁니다.

서버에서 제거해도 endue 의 디바이스는 지워지지 않고, endue 에서 지워도 서버의 설치는 남습니다. 둘 다 하세요. 여기서 제거하고, 기기 행 메뉴에서 그 에이전트를 **떼기** 합니다. [디바이스 지우기](/ko/docs/build/devices/#디바이스-지우기)를 보세요.

## 한계

- x86_64·aarch64 의 Linux 만 됩니다. macOS·Windows 판은 아직 없습니다.
- 에이전트당 endue Computer 한 대입니다. 내 서버에 있는 에이전트는 endue 클라우드에 따로 가질 수 없고, 이미 다른 서버에 있는 에이전트는 거기서 먼저 떼야 합니다.
- endue 는 내 서버나 서비스를 켤 수 없습니다. 둘 중 하나가 꺼져 있으면 에이전트는 그것 없이 일합니다.
- 에이전트는 서비스가 연결돼 있는 동안만 서버의 도구를 씁니다. 에이전트가 백그라운드로 띄운 프로그램은 서비스가 멈추면 함께 멈춥니다.
- 일부 컨테이너처럼 systemd 가 없으면 `--no-systemd` 를 붙입니다. 설치 스크립트가 파일만 두고 직접 실행할 명령을 출력합니다. 이때는 위의 systemd 보호가 적용되지 않습니다.
- 서비스가 `status=226/NAMESPACE` 로 시작하지 못하면 그 기기가 마운트 네임스페이스를 만들 수 없는 것입니다. 일부 LXC·OpenVZ 컨테이너에서 생깁니다. 온전한 VM 을 쓰거나 `--no-systemd` 를 씁니다.

## 관련 문서

<CardGrid>
  <LinkCard
    title="디바이스"
    href="/ko/docs/build/devices/"
    description="디바이스 제품, 유저·에이전트 기기, 지우는 방법."
  />
  <LinkCard
    title="워크스페이스"
    href="/ko/docs/build/workspace/"
    description="에이전트가 일하는 폴더와, 그 안을 들여다보는 방법."
  />
  <LinkCard
    title="보안과 권한"
    href="/ko/docs/account/security/"
    description="에이전트가 닿을 수 있는 것과 없는 것."
  />
</CardGrid>