명령 실행하기

alpacon login으로 로그인했다면 아래 절차를 따르세요. 서비스 토큰을 쓰는 자동화 작업은 서비스 토큰을 참고하세요.

작업 세션 요청

대상 서버와 명령 실행 기능(command)을 포함해 작업 세션을 요청하세요. 세션이 활성 상태가 될 때까지 기다리세요.

작업 세션 연결

CLI 워크스페이스에서 쓸 세션을 지정하세요.

bash
alpacon work-session use WORK_SESSION_ID

각 명령어에 --work-session WORK_SESSION_ID를 전달해도 됩니다. AI 에이전트는 에이전트 작업 세션을 쓰고, 세션 ID를 명시적으로 전달해야 합니다.

명령어 실행

bash
alpacon exec --purpose "Check disk space before deployment" my-server -- df -h

exec 플래그는 서버 이름 앞에 놓으세요. CLI는 서버 이름 뒤의 모든 인수를 원격 명령어로 해석합니다. --로 경계를 명확히 표시할 수 있습니다. 결과는 CLI 또는 명령 기록에서 확인하세요.

실행 계정 선택

USER@SERVER 또는 -u USER로 서버 계정을 지정하세요.

bash
alpacon exec admin@my-server -- whoami
alpacon exec -u admin my-server -- whoami

세션에서 허용하는 계정을 쓰세요. 에이전트 세션은 승인받은 계정으로만 실행할 수 있으며, 다른 계정을 선택하면 거부됩니다. 계정 선택을 참고하세요.

실행 목적 전달

--purpose는 명령어와 함께 실행 맥락을 전달합니다. 이 서버에서 해당 작업이 필요한 이유를 적으세요. 최대 2000자이며, 이를 넘으면 거부됩니다. 감사 기록의 상세 패널에서 요청자가 밝힌 목적 항목으로 확인할 수 있습니다.

워크스페이스에서 목적을 요청하는 경우, 명령어가 목적 확인 중 상태로 대기하고 CLI는 종료 코드 7로 끝날 수 있습니다. 같은 작업에 목적을 전달하세요.

bash
alpacon exec purpose JOB_ID "Check disk space before deployment"

응답할 수 있는 시간과 이후 동작은 exec purpose를 참고하세요.

시크릿을 환경 변수로 전달

자격 증명을 명령줄에 넣지 마세요. 로컬 셸에 PGPASSWORD가 설정되어 있다면 변수 이름만 전달하세요.

bash
alpacon exec --env="PGPASSWORD" db-server -- psql -h localhost -U app -c 'SELECT 1'

CLI가 로컬 환경에서 값을 읽습니다. 원격 명령어에서 이 변수를 출력하지 마세요. 자격 증명이 명령줄에 포함되면 실행이 거부됩니다. --env는 명령줄 실행에 쓰는 옵션이며 --file과 함께 쓸 수 없습니다.

오래 걸리는 명령어

약 10분을 넘길 수 있는 작업은 --detach로 제출하세요.

bash
alpacon exec --detach --purpose "Refresh package metadata" my-server -- apt-get update
alpacon exec logs JOB_ID

제출하면 Job submitted: <JOB_ID>가 출력됩니다. 결과를 조회할 때는 JOB_ID를 출력된 UUID로 바꾸세요. 포그라운드 alpacon exec는 수신 확인 또는 전달 후 10분 동안 결과가 없으면 응답 없음으로 판단하고 종료 코드 1로 끝납니다. 서버에서는 명령어가 최대 30분까지 계속 실행되므로, CLI가 대기를 끝냈다는 이유로 같은 작업을 다시 제출하지 마세요.

exec logs 조회 결과종료 코드다음 조치
실행 중 또는 실행 대기 중0나중에 같은 작업을 다시 조회. 코드 0만으로 완료를 판단하지 않음
워크스페이스에서 목적을 요청해 대기 중7alpacon exec purpose JOB_ID PURPOSE로 목적 전달
승인 대기4승인자에게 콘솔에서 결정을 요청
반려됨6다른 명령어를 제출하기 전에 사유 확인
응답 없음, 오류 또는 취소됨1명령 기록에서 상태와 상세 정보 확인
실행 완료원격 명령어의 종료 코드출력과 종료 코드 확인

서버에서 명령어를 실행할 수 있는 시간은 최대 30분입니다. 제한에 도달하면 종료 코드 124와 Command timed out after 30m0s가 반환됩니다. 더 긴 작업은 각각 제한 안에 끝나도록 나누세요.

ALPACON_EXEC_TIMEOUT

ALPACON_EXEC_TIMEOUT은 CLI가 실행 중 상태를 받지 못할 때 기다리는 시간을 정합니다. 기본값은 30m이며 1h 같은 기간을 지정할 수 있습니다. 진행 중 상태를 받을 때마다 대기 시간이 다시 시작됩니다. 이 값으로 서버의 실행 시간 제한을 늘리거나 포그라운드 실행의 응답 없음 판정을 막을 수는 없습니다.

대기 시간이 지나면 CLI는 Error: [client_timeout] CLI gave up waiting for the server to report a result를 출력하고 종료 코드 1로 끝납니다. 명령어는 취소되지 않습니다. 다시 실행할지 결정하기 전에 alpacon exec logs JOB_ID로 확인하세요.

승인 대기

승인 대기 상태의 명령어는 콘솔에서 사람의 결정을 기다립니다. --wait 또는 --wait-approval 30m으로 기다리지 않으면 CLI는 종료 코드 4로 끝납니다. 기본 승인 대기 시간은 5분입니다. 보류된 명령어는 승인되면 자동으로 실행되므로, 기다리는 동안 다시 제출하지 마세요.

sudo 승인과 터미널 인증은 sudo와 MFA를 참고하세요. 명령어가 반려되면 재시도 전에 명령 기록의 거절 이유 항목을 확인하세요.

최종 수정: