Get to know Astera.

프로젝트 하나와 계정 하나면 시작할 수 있습니다. 첫 대화를 시작한 뒤 자동화 기능을 살펴보세요.

1. Astera와 에이전트 설치하기

   Download 버튼을 눌러 운영체제에 맞는 설치 파일을 받으세요. Astera가 실행할 수 있도록 Claude Code나 Codex CLI를 설치하고 PATH에서 찾을 수 있게 해야 합니다. 둘 다 설치해도 됩니다.

   Astera는 기존 도구를 실행합니다. 각 서비스의 계정과 이용 요금은 별도입니다.

   운영체제별 설치 방법

2. 계정 연결하기

   계정에서 자동 감지로 기존 계정을 찾고 원하는 계정을 등록하세요. 계정 추가로 별도의 계정을 만든 뒤 안내에 따라 로그인할 수도 있습니다.

3. 폴더와 세션 방식 선택하기

   새 세션을 열고 프로젝트 폴더와 계정을 선택하세요. 터미널 또는 대화를 고른 뒤 시작을 누릅니다. 선택한 폴더를 기준으로 에이전트가 코드 작업을 진행합니다.

4. 첫 작업을 구체적으로 요청하기

   원하는 결과와 확인 방법을 함께 적으세요. 처음 보는 프로젝트라면 이렇게 시작해 보세요.

   이 프로젝트의 구조와 로컬에서 실행하는 방법을 설명해 줘. 아직 파일은 수정하지 마.

   답변을 읽고 필요한 질문에 답하면서 같은 세션에서 이어가세요.

어느 쪽이든 에이전트와 작업하는 세션입니다. 하려는 일에 맞는 인터페이스를 선택하세요.

실제 앱 화면 살펴보기

터미널 화면채팅 화면

크게 보기

탭은 이름의 절반 정도가 보일 때까지 줄어든 뒤 마우스 휠로도 스크롤할 수 있습니다. 앱이 바쁠 때 터미널 한글 입력이 중복·누락되던 문제를 수정했습니다. CLI·브라우저 패널·Slack으로 보낸 글은 세션에 표시된 뒤 Enter를 보냅니다.

계정 자동 전환은 사용량 한도에 도달한 세션을 같은 서비스의 다음 사용 가능한 계정으로 옮깁니다. 기본 재개 방식에서는 같은 대화를 이어갑니다.

1. 사용할 계정들을 등록하고 각각 로그인하세요.
2. 새 세션에서 첫 계정을 선택하세요. + 계정 추가로 다음에 사용할 계정과 전환 순서를 정합니다.
3. 세션을 시작하세요. Astera가 사용량 한도를 감지하고 다른 계정을 사용할 수 있으면 전환합니다.

계정 추가 시 기본 계정에서 설정 가져오기로 설정을 가져옵니다. Codex의 config.toml은 주석과 관련 없는 항목을 유지하며 병합합니다. MCP & Skills에 항목을 등록한 뒤에는 해당 화면에서 관리하고 다시 복사하지 않습니다. 변경은 새 세션부터 적용됩니다.

전체 데모 보기

설정 → MCP & Skills에서 등록을 누르고 계정을 골라 공유할 MCP 서버·스킬·명령·에이전트를 선택하세요. 새 세션과 계정 전환 후 세션에도 적용됩니다. 제공자별 지원 범위는 그대로이며 Codex에는 슬래시 명령과 하위 에이전트가 없습니다.

각 계정의 파일 사본을 동기화합니다. 관리 중인 사본을 지우면 복원하고 수정하면 먼저 백업한 뒤 복원합니다. 계정에 원래 있던 다른 버전은 공유 버전으로 바꾸기를 선택할 때까지 유지합니다. 항목을 펼쳐 상태를 확인하거나 끄고 제거할 수 있습니다.

공유 로컬 MCP 서버는 Host의 Gateway를 통해 프로젝트 폴더마다 하나씩 실행합니다. 5분간 사용하지 않으면 멈추고 비정상 종료 뒤 다시 필요해지면 시작합니다. 세션마다 상태를 분리하려면 세션마다 실행을 켜세요. Playwright·chrome-devtools 같은 브라우저 서버는 기본으로 이 방식을 쓰며 세션별 브라우저 프로필을 사용합니다.

astera ext list
astera ext sync

앱과 Host가 꺼져 있어도 ext list로 공유 항목을 보고 ext sync로 파일 사본을 동기화할 수 있습니다. Astera 기본 스킬은 별도의 skills list·skills install로 관리합니다. 세션에 도구를 공유하는 기능과 MCP로 클라이언트를 Astera에 연결하는 기능은 별개입니다.

설정 → 에이전트 프로필 → 새 프로필에서 이름을 정하고 같은 제공자의 계정을 전환 순서대로 추가하세요. 제외할 공유 MCP 서버를 고르고 권한 확인을 앱 설정 따름·권한 확인함·권한 확인 없이 실행 중에서 선택합니다. 스킬과 명령은 모든 프로필이 같이 씁니다.

새 세션, Job 생성, Task 추가 창에서 프로필을 선택하세요. Task는 따로 고르지 않으면 Job 프로필을 따르며 코디네이터 계정은 별도로 고릅니다. 계정 전환 시에도 프로필이 유지되고 히스토리 이어하기 창에는 이전 대화의 프로필이 표시됩니다.

astera agent-profiles list
astera agent-profiles show --id PROFILE_ID

목록의 ID나 이름을 사용하세요. 일반 셸에서는 생성·수정·보관·복원도 할 수 있습니다. MCP는 list_agent_profiles로 읽고 작업 생성 시 agentProfileId를 지정합니다. 클라이언트 SDK 0.5.0에는 agentProfiles.list·agentProfiles.get이 추가됐습니다. 에이전트는 프로필을 편집할 수 없습니다. 에이전트·MCP 클라이언트·플러그인은 앱이 허용할 때만 권한 확인 없는 프로필을 사용할 수 있습니다.

설정 → Security & Access의 에이전트의 도구 호출 기록은 기본으로 꺼져 있습니다. Observe를 고르고 새 세션을 시작하면 차단 없이 호출을 기록합니다. Audit Logs에서 날짜별 호출을, Policies에서 허용·거부를 판단할 순서 있는 Rules를 확인하세요. 기록 범위 표에 제공자·세션 방식별 지원 범위가 나옵니다.

동작·짧은 대상·읽기와 쓰기 여부·접근한 로그인 폴더 이름을 기록합니다. 전체 명령·출력·파일 내용은 저장하지 않으며 용량 한도 안에서 30일 보관합니다. Run 상세에서 해당 Run의 Audit Logs로 이동할 수 있습니다.

Enforce를 고르면 Rules가 거부한 호출을 실행하지 않고 차단으로 기록합니다. 켜기 전에 지난 7일간 차단됐을 호출을 확인하세요. 호출마다 약 0.1초가 추가되며 Claude Code 2.1.306 이상 또는 Codex 0.160.0 이상이 필요합니다. 보호할 수 없는 세션은 시작하지 않습니다. Enforce는 Astera 설정 폴더 쓰기와 설정 변경 명령을 항상 막습니다.

Credentials에는 공유 MCP 키가 자동으로 나옵니다. 환경 변수 이름이나 CLI 로그인 프리셋(gh·AWS·Google Cloud·npm·Docker·kubectl)을 추가하고 전체 또는 특정 프로젝트에 적용하세요. 이후 시작하는 세션과 완료 검사에 숨긴 자격 증명을 전달하지 않으며 검사 결과에는 숨긴 변수 이름을 표시합니다. Astera의 GitHub·Gateway 사용 내역은 Audit Logs에 남습니다. 같은 사용자 권한의 프로그램이 로그인 파일이나 OS 저장소를 직접 읽는 것까지 막지는 못합니다.

astera policies show
astera audit list --run RUN_ID
astera credentials list
astera credentials doctor

RUN_ID를 실제 값으로 바꾸거나 --run RUN_ID를 빼고 전체 호출을 확인하세요. 실행 중인 Host가 필요합니다. 감사 이력은 사용자 전용이며 에이전트는 정책·자격 증명 설명을 읽을 수 있지만 감사 이력을 읽거나 자신의 보호 설정을 바꿀 수 없습니다. Credentials는 앱에서 편집하세요.

에이전트 프로필에서 기본으로 꺼진 Sandbox에서 실행을 켜고 새 터미널·채팅 세션을 시작하세요. Codex는 0.160.0 이상이 필요합니다. Windows는 계정마다 설정하기를 한 번 실행해야 하며 관리자 권한 요청이 표시됩니다. config.toml이 elevated sandbox를 기본값으로 정해 두었다면 설정과 Sandbox 세션 시작 시 계정을 알리고 그 설정을 지우는 버튼을 제공합니다.

Codex와 macOS·Linux의 Claude Code는 자체 Sandbox로 쓰기를 작업·임시 폴더에 제한하고 로그인 폴더·OS 비밀 저장소 접근을 제한합니다. 네트워크는 사용할 수 있습니다. Windows의 Claude Code에는 Sandbox가 없습니다. 파일 도구만 로그인 폴더 접근을 제한하며 셸은 제한하지 않습니다. Linux의 Codex는 파일 경로 기반 세션 버스만 막고 추상 소켓은 막지 않으며 Claude의 OS 저장소 보호는 Sandbox 런타임에서 측정한 범위입니다. Security & Access의 Sandbox가 막는 범위에서 플랫폼별 차이를 확인하세요.

표시가 붙은 Sandbox 세션은 격리 밖의 세션·Jobs·Tasks로 일을 넘기거나 Host를 직접 호출하고 Astera 프로필·설치 코드를 쓸 수 없습니다. 에이전트 브라우저도 자체 빈 페이지 저장소를 사용합니다. 작업 폴더가 홈 폴더를 포함하거나 Ubuntu에서 Claude 셸이 실행되지 않으면 경고가 표시됩니다.

설정 → Security & Access → Findings에서 미사용·중복 프로필, 삭제된 계정·서버 참조, 반복 실패, 미사용 도구·자격 증명, 기록된 사용보다 넓은 접근 권한, 일부만 적용되는 Rules, 오래 연결하지 않은 Runtime, 평소보다 토큰을 많이 쓴 Run을 확인하세요. 각 항목은 조치할 곳을 안내합니다. 자동으로 바꾸지 않으며 무시로 따로 둘 수 있습니다.

미사용 프로필은 90일을 기준으로 합니다. 미사용 MCP 서버·스킬·명령·에이전트와 과도한 프로필 권한 판단에는 30일간의 Observe 이력이 필요합니다. 실패·토큰 급증 항목은 별도 기록을 쓰므로 Observe를 기다리지 않습니다. 읽지 못한 자료는 문제없음으로 처리하지 않고 별도로 알립니다. 프로필에도 열린 Findings를 표시합니다. 프로필 보관 시 시각·이유를 남기고 해당 예약 Job은 복원할 때까지 기다리며 이미 프로필을 사용 중인 작업은 계속됩니다.

astera agent-profiles audit

CLI도 실행 중인 Host에서 같은 Findings를 조회합니다. 에이전트는 읽을 수 있지만 무시할 수 없습니다. Remote Runtime에 기대한 확장이 없거나 다르고 Astera가 구버전인 경우도 마지막 보고서 시각과 함께 표시됩니다.

계정을 전환할 때 다음 세션에 작업의 핵심 맥락을 전달하고 싶다면 Smart Resume를 선택하세요. 기본 재개는 기존 대화를 이어갑니다. Smart Resume는 지금까지의 작업을 체크포인트로 정리해 새 대화에 전달합니다.

1. 설정 → 일반 → 세션 재개 방식에서 스마트 재개를 선택하세요. 기본값은 꺼짐입니다.
2. 계정 자동 전환 순서를 설정하세요. 한도에 도달해 같은 서비스의 사용 가능한 계정으로 전환할 때 체크포인트를 사용합니다.
3. 세션에서 작업을 이어가세요. 다음 에이전트는 첫 메시지로 체크포인트를 받고, 작업 파일을 확인하면서 이어서 진행할 수 있습니다.

매일 아침 테스트를 실행하거나 정기적으로 프로젝트 상황을 정리하는 등 반복되는 일에 스케줄러를 사용하세요.

1. 새 세션에서 스케쥴러를 켜세요.
2. 실행 간격 또는 매일·매주·매월 일정을 선택하세요.
3. 터미널 세션은 명령을, 채팅 세션은 프롬프트를 입력하세요. 세션을 시작하면 예약이 활성화됩니다.

예약한 작업이 실행될 때 Astera가 켜져 있고 컴퓨터가 깨어 있어야 합니다. 세션 예약은 하나의 대화에 요청을 보냅니다. 서로 의존하는 여러 작업을 순서대로 실행하려면 Jobs를 사용하세요.

전체 데모 보기

응답이 끝나거나, 계정 한도에 도달하거나, 사용자 입력이 필요할 때 알림을 받습니다. 봇 모드를 설정하면 세션마다 스레드가 하나씩 만들어집니다. 해당 스레드에 답장하면 세션으로 메시지가 전달됩니다.

1. Slack 앱을 만들고 알림을 받을 채널에 봇을 초대하세요.
2. Astera의 Slack 설정에 봇 토큰과 채널 ID를 입력하세요. 답장 기능을 쓰려면 Socket Mode, 앱 토큰, 본인의 Slack 멤버 ID도 설정합니다.
3. 세션의 Slack 진행상황 알림을 켜세요.

Job은 하나의 목표를 작업 그래프로 보여 줍니다. 연결선을 보면 병렬로 진행할 일과 앞선 결과를 기다려야 할 일을 알 수 있습니다. 같은 실행 내역에서 Claude·Codex 워커, 질문과 완료 검사까지 따라가세요.

Run 상세와 각 Task에 Claude·Codex 세션 기록의 토큰 합계가 표시됩니다. Observe를 켠 뒤 Audit Logs 링크에서 도구 호출을 확인하세요.

1. 커밋이 하나 이상 있고 브랜치가 체크아웃된 git 저장소를 사용하세요.
2. Jobs → 새 작업을 여세요. 목표를 입력하고 코디네이터 계정과 동시 실행 수를 정합니다.
3. 작업과 워커 계정, 의존 관계를 추가하세요. 빌드·테스트·다른 제공자의 에이전트 리뷰를 완료 검사로 연결합니다. 한도 내에서 수정을 반복하려면 통과할 때까지 자동 수정을 켜세요.
4. 실행을 누르세요. 그래프에서 진행 상황을 확인하고 질문에 답한 뒤 결과를 검토합니다. 일반 Job은 프로젝트에 반영할 준비가 됐을 때 병합을 누릅니다.

전체 데모 보기

열린 GitHub 이슈나 작업 소스 플러그인이 제공하는 티켓에서 Job을 만드세요. Astera가 원문을 목표에 담고 티켓 제목으로 Job을 표시하며, 원문으로 돌아가는 링크도 보관합니다.

1. Jobs에서 로컬 git 프로젝트를 선택하고 + 소스에서를 누르세요. 다른 Job처럼 커밋이 하나 이상 있고 브랜치가 체크아웃된 저장소여야 합니다.
2. 소스를 고르고 항목을 검색한 뒤 선택해 설명과 상세 정보를 읽으세요. 더 보기로 다음 페이지를 불러옵니다. 작업 있음을 누르면 해당 항목에서 이미 만든 Job이 열리며, 같은 항목으로 Job을 하나 더 만들 수도 있습니다.
3. 코디네이터 계정을 선택하고 필요하면 자동 수정을 켜세요. 작업 만들기를 눌러 저장된 Job을 검토한 뒤 준비가 되면 실행을 누릅니다. 만드는 것만으로 실행을 시작하지는 않습니다.

astera projects list --human
astera sources list --human
astera sources items --source github --project PROJECT_ID --human
astera sources show --source github --item 12 --project PROJECT_ID --human
astera jobs create-from-source --source github --item 12 --project PROJECT_ID --coordinator-account ACCOUNT_ID
astera jobs run --id JOB_ID

Job의 작업을 풀 리퀘스트, GitHub CI, 수정과 두 번째 에이전트의 리뷰까지 이어갈 수 있습니다. GitHub까지 진행할 Job에서 이 옵션을 켜세요. Astera가 병합 준비 완료를 알리면 사용자가 GitHub에서 직접 병합합니다.

Job에서 켜기

1. Jobs → 새 작업 또는 + 소스에서 창에서 GitHub 까지 진행을 켜세요. 기본값은 꺼짐이며, 켜면 자동 수정도 함께 켜집니다.
2. Host가 origin이 GitHub 저장소인지, gh에 로그인했는지, 저장소 권한이 WRITE·MAINTAIN·ADMIN인지 확인합니다. 통과하지 못하면 이유를 표시하고 생성을 막습니다.
3. 설정 → GitHub에서 코드 밖의 이유로 실패한 CI의 재실행 여부, 재실행 한도(1~10회), CI 대기 한도(10~1440분)를 정하세요. 새 Job이 이 기본값을 복사하며, 설정을 바꿔도 기존 Job에는 적용되지 않습니다.

Task가 모두 끝나면

1. Astera가 워커 없는 GitHub 전달 Task를 추가합니다. Task 결과를 Run의 브랜치에 모으고 로컬 검사를 다시 실행한 뒤 푸시합니다. 초안 PR을 열거나 기존 열린 PR에 연결합니다. 같은 저장소의 이슈에서 만든 Job은 PR 본문에 Refs #N을 넣습니다.
2. 푸시한 head의 CI를 기다립니다. 브랜치 규칙의 필수 검사와 --github-checks로 추가 선택한 검사를 함께 판정합니다. 둘 다 없으면 보고된 검사 전부로 판정합니다.
3. 테스트·빌드·lint·타입 검사 실패는 실패한 작업의 로그와 함께 에이전트에게 전달해 Run의 브랜치에서 수정합니다. 자동 수정 예산 안에서 로컬 검사를 다시 실행하고 수정 결과를 푸시한 뒤 CI를 다시 확인합니다. 네트워크·러너 장애는 GitHub 설정의 한도 안에서 다시 실행할 수 있습니다.
4. CI가 통과하면 마지막 구현자와 다른 제공자의 리뷰어가 PR 전체를 검토하며 CI를 약화한 변경인지도 확인합니다. 리뷰가 통과하면 검토한 커밋에 대해 병합 준비 완료로 판정합니다.

진행 상황과 질문 확인하기

Job 카드에는 CI 대기, CI 수리 중, 병합 준비가 표시됩니다. Run 상세의 GitHub에서 PR, head, 검사, 실패 이유, 수정 내역, Astera 리뷰, GitHub 자체 상태와 병합 준비 판정 시각을 확인하세요. 타임라인은 각 단계를 기록하고 How It Works는 이슈·PR과 GitHub의 검증 근거를 남깁니다.

CI가 나타나지 않음, 대기 한도 초과, 다른 사람이 푸시한 커밋, 여러 열린 PR, PR 닫힘·병합, 코드 밖의 실패, GitHub 전달 불가 상황에서는 Astera가 질문합니다. 질문을 읽고 다시 기다리기, CI 없이 진행, 받아서 이어 가기, 다시 시도, 다시 돌리기, PR 연결, Task를 실패로 처리 중에서 선택하세요. Host가 답을 처리하므로 꺼져 있다면 먼저 시작하세요.

CLI·MCP·SDK에서 사용하기

CLI로 Job을 만들 때 --github-lifecycle을 추가하세요. GitHub 전달 Task가 성공 또는 실패로 끝난 뒤에는 runs reconverge로 다시 GitHub까지 진행할 수 있습니다. PR이 닫혔거나 병합됐거나 Run 워크트리가 없으면 거절합니다. 예시의 계정, 저장소 경로, Job ID와 Run ID는 실제 값으로 바꾸세요.

astera jobs create --objective "Improve the sign-in flow" --cwd "REPO_PATH" --coordinator-account ACCOUNT_ID --github-lifecycle
astera jobs run --id JOB_ID
astera runs follow --id RUN_ID --human
astera runs reconverge --id RUN_ID

MCP는 create_job의 githubLifecycle과 reconverge_run을 사용합니다. 생성에는 설정 → CLI의 읽기와 제어와 MCP 클라이언트가 GitHub 에서 작업하게 하기가 필요합니다. 추가 검사 선택은 CLI와 MCP에서 지원합니다. @astera-app/client 0.4.0에서도 이 진행 상태를 읽고 답할 수 있습니다.

전체 흐름, 질문과 복구 조건은 GitHub 진행 문서에서 확인하세요.

completion-check 플러그인으로 Task의 변경 사항을 검사하고 요약, 파일·줄 번호가 있는 지적, 보고서 링크를 받을 수 있습니다. 예를 들어 debug-leftovers 예제는 새로 추가한 콘솔 로그, debugger, TODO와 FIXME를 찾습니다.

1. 설정 → 플러그인에서 신뢰하는 검사 플러그인을 설치하고 사용하도록 켜세요. 설치만으로 Task에 검사가 연결되지는 않습니다.
2. 로컬 Task를 추가할 때 실행 구성 옆에서 플러그인 검사를 고르세요. CLI에서는 astera plugins list의 ID를 사용해 --validate에 plugin:PLUGIN_ID를 지정합니다. 여러 검사는 나열한 순서로 실행하며 첫 실패에서 멈춥니다.
3. 워커의 완료 보고 뒤 Task의 완료 상세에서 요약, 지적과 보고서 링크를 확인하세요. 자동 수정을 켰다면 실패한 검사의 지적을 워커에게 전달하고 Job에 정한 수정 횟수 안에서 다시 확인합니다.

astera plugins list --human
astera tasks add --job JOB_ID --account ACCOUNT_ID --spec "Implement the change and verify it" --validate plugin:PLUGIN_ID
astera runs checks --id RUN_ID --human

Job을 실행하기 전에 Task를 추가하고, 실행 후 받은 RUN_ID로 검사를 조회하세요. --validate에는 실행 구성 ID와 플러그인 ID를 쉼표로 구분해 함께 넣을 수 있습니다. 플러그인이 없거나 꺼져 있거나 완료 검사를 제공하지 않으면 PLUGIN_CAPABILITY_MISSING으로 거부합니다.

Astera는 플러그인 검사의 처음 20개 지적을 보관하고, 전체 개수가 있으면 나머지가 몇 개인지도 표시합니다. 플러그인이 보고서 링크를 제공했다면 전체 내용은 그곳에서 확인하세요. 통과한 검사는 요약과 링크만 남기며 지적은 보관하지 않습니다. 플러그인 작성자는 diagnostics에 처음 20개를, diagnosticsTotal에 전체 개수를 반환할 수 있습니다.

검사 자체를 할 수 없을 때

토큰 누락, 외부 서비스 장애, 플러그인 중단은 코드에 대한 지적이 아니라 검사를 수행하지 못한 오류입니다. Astera가 즉시 한 번 더 시도하고, 그래도 실행할 수 없으면 수정 횟수를 쓰지 않고 사용자 답변을 기다립니다. 질문을 열어 다음 중 하나를 고르세요.

셸에서는 astera questions answer --id QUESTION_ID --answer retry로 답하거나 나머지 두 답변 중 하나로 바꾸세요. check-unavailable 질문은 이 세 값만 받습니다. MCP의 get_completion과 SDK의 completion.get에서 지적을 읽을 수 있으며, 플러그인 검사에는 get_check_output으로 읽을 터미널 출력이 없습니다.

/astera-orchestration 스킬로 Astera 세션이 Claude와 Codex의 여러 단계 작업을 감독하게 할 수 있습니다. 코디네이터가 작업을 만들고 워커에게 배분한 뒤 보고를 기다리며, 필요한 판단은 사용자에게 돌려줍니다. 실행 과정은 Jobs에서 볼 수 있습니다.

1. 프로젝트에서 새 코디네이터 세션을 여세요. Astera가 시작하는 모든 세션에 오케스트레이션 스킬이 제공되며, 세션 시작 시 불러옵니다.
2. 목표와 각 에이전트의 역할, 작업 순서, 결과 확인 방법을 적으세요. 요청한 제공자마다 사용할 수 있는 계정을 등록해야 합니다.
3. 프로젝트의 Jobs 사이드바에서 그래프를 확인하세요. 코디네이터의 판단 요청은 질문과 Gate에서 읽고 답합니다. 프로젝트에 변경을 반영하기 전에 결과를 검토하세요.

/astera-orchestration

Claude가 로그인 흐름을 리팩터링하고, 그다음 Codex가 회귀 테스트를 추가하게 해 줘. 프로젝트 테스트와 다른 제공자의 에이전트 리뷰까지 진행해 줘. 검사 실패 시 3회 한도에서 수정하고 다시 확인해 줘. 결정이 필요하면 나에게 물어봐.

astera 명령으로 터미널과 스크립트에서 세션과 Jobs를 다루세요. 지원되는 Host가 실행 중이면 앱을 닫아도 워커 실행, 워크트리 관리, 설정한 검사·리뷰·계정 자동 전환을 이어갑니다. Astera를 다시 열어 같은 작업을 탭과 Jobs 그래프에서 확인할 수 있습니다.

1. 터미널에서 사용할 준비

1. Astera를 설치하고 계정을 추가해 로그인하세요. 사용할 Claude Code 또는 Codex CLI도 설치한 뒤, 설정 → CLI → 명령줄 도구 (astera)에서 astera 명령 설치를 누르세요.
2. Windows에서는 이 폴더를 사용자 PATH 에 추가를 켜 두면 %LOCALAPPDATA%\astera\bin이 자동으로 등록됩니다. macOS·Linux에서는 ~/.local/bin에 설치되며, PATH 설정이 필요하면 패널에 표시된 명령을 실행하세요. 설치 후 새 터미널을 여세요. Astera에서 시작한 세션에는 이미 명령이 제공됩니다.
3. Host를 시작하고 지원 기능을 확인하세요. host status의 data.features에서 spawn은 워커 실행, worktrees는 독립 브랜치 관리, dispatch는 Job 자동 실행·검사, rolling은 계정 전환을 뜻합니다.

astera version
astera host start
astera host status
astera accounts list --human

아래 예시의 ACCOUNT_ID는 계정 목록의 ID로, REPO_PATH는 프로젝트의 절대 경로로 바꾸세요. SESSION_ID, JOB_ID, RUN_ID는 각각 생성·실행 명령의 data.id 값을 사용하며 서로 다른 대상을 가리킵니다. 준비가 끝나면 Astera를 닫고 일반 터미널에서 명령을 실행해도 됩니다.

2. 창을 열지 않고 에이전트 실행

계정, 작업 폴더, 요청을 지정하세요. 기존 세션은 sessions list로 찾고, 추가 요청을 보내기 전에 sessions read로 화면을 확인하세요. 터미널 입력은 현재 화면에 전달되므로 열린 질문에도 입력될 수 있습니다. 계정 자동 전환은 --roll-accounts에 같은 제공자의 사용 가능한 계정 ID를 쉼표로 구분해 지정합니다.

astera sessions create --account ACCOUNT_ID --cwd "REPO_PATH" --kind terminal --prompt "Inspect the project and summarize its test setup."
astera sessions list --human
astera sessions read --id SESSION_ID --human
astera sessions send --id SESSION_ID --text "Run the existing tests and report the results."

astera sessions create --account ACCOUNT_ID --cwd "REPO_PATH" --kind chat --unattended hold --prompt "Inspect the project and summarize its test setup."
astera chats pending --session SESSION_ID --human

3. Job 실행과 검사 결과 확인

/astera-orchestration으로 에이전트에게 작업 계획을 맡기세요. 실행할 준비가 된 Job의 ID를 찾아 터미널에서 실행 회차를 시작할 수 있습니다. jobs run은 실행 회차의 ID를 data.id로 반환합니다. 이미 실행 중인 회차가 있다면 새로 시작하지 말고 해당 회차를 추적하세요.

astera jobs list --human
astera jobs run --id JOB_ID
astera runs follow --id RUN_ID --human
astera runs checks --id RUN_ID --human

Host는 선행 작업이 끝나면 다음 워커를 배분하고, 설정한 검증과 다른 제공자의 리뷰를 실행하며, Job의 수렴 설정에 정한 횟수 안에서 수정을 재시도합니다. runs follow는 진행 상황을 계속 보여 줍니다. Ctrl+C는 조회만 끝내며 작업을 취소하지 않습니다. 실행을 멈추려면 runs stop --id RUN_ID, 다시 진행할 준비가 됐다면 runs resume --id RUN_ID를 사용하세요.

astera skills list --account ACCOUNT_ID --human
astera skills install --account ACCOUNT_ID --human

astera jobs create --objective "Improve the sign-in flow" --cwd "REPO_PATH"
astera tasks add --job JOB_ID --spec "Implement the sign-in changes and add regression tests" --account ACCOUNT_ID
astera jobs run --id JOB_ID

4. 질문에 답하고 스크립트에서 완료 대기

사용자의 결정이 필요하면 열린 질문을 확인하고 터미널에서 답하세요. QUESTION_ID는 질문 ID로, 예시 답변은 실제 결정으로 바꾸세요. 답변을 기다리는 동안 Host가 종료됐다면 먼저 다시 시작하세요.

astera questions list --run RUN_ID --status open --human
astera questions get --id QUESTION_ID --human
astera host start
astera questions answer --id QUESTION_ID --answer "Use the existing authentication library."
astera runs wait --id RUN_ID --timeout-ms 3600000

대부분의 명령은 기본으로 JSON을 반환합니다. 읽기 쉬운 출력은 --human, ID만 받으려면 --quiet를 사용하세요. runs follow는 기본으로 줄마다 JSON 이벤트를 출력합니다. 스크립트나 설정을 마친 로컬 CI 실행 환경에서는 runs wait로 기다리고 종료 코드에 따라 처리하세요.

그 밖에 Host에 연결할 수 없으면 3, 현재 상태에서 명령을 실행할 수 없으면 6, CLI와 Host 빌드가 호환되지 않으면 9가 반환될 수 있습니다. error.code, error.details, error.nextSteps를 확인하세요. 작업을 변경하는 명령의 종료 코드 7은 응답만 유실된 경우도 있으므로, 재시도 전에 응답에 제시된 요청 상태 확인 절차를 따르세요.

페어링한 컴퓨터를 대상으로 실행하려면 명령 앞에 --runtime RUNTIME_ID를 넣으세요. 페어링·권한·경로는 Remote Runtime 설정에서 확인할 수 있습니다.

astera --help 또는 astera jobs --help처럼 명령별 도움말을 확인하세요. 전체 옵션, Chat 승인, 예약, 문제 해결은 CLI 문서에서 볼 수 있습니다.

Astera의 MCP 서버로 Claude Code·Codex·Cursor 클라이언트가 앱과 CLI와 같은 로컬 Host를 사용할 수 있습니다. Job 생성·실행·진행 확인, 실패한 검사 조회, How It Works 기록 읽기를 지원합니다. MCP로 만든 Job은 앱과 CLI에 표시되고 클라이언트 연결이 끊겨도 실행을 이어갑니다.

이 컴퓨터의 클라이언트 연결하기

1. CLI 설치 안내에 따라 설정 → CLI에서 astera 명령을 설치하세요. MCP 클라이언트는 이 명령으로 Host에 연결하며 앱 창을 열어 둘 필요는 없습니다.
2. MCP 접근에서 조회만 허용하려면 읽기 전용, Job 생성과 실행도 허용하려면 읽기와 제어를 선택하세요. 기본값은 읽기와 제어이며, 꺼짐은 모든 도구 호출을 거부합니다.
3. Claude Code·Codex·Cursor 항목에서 운영체제에 맞게 표시된 설정 명령을 사용하세요. Claude Code와 Codex에는 등록 버튼도 있습니다. Cursor는 복사한 설정을 적용합니다. Claude Code·Codex의 등록은 기본 사용자 설정에 적용되므로 별도 설정을 사용하는 Astera 계정에는 MCP 항목을 추가해야 할 수 있습니다.
4. 연결된 에이전트에게 Astera 프로젝트 목록을 조회하고 원하는 프로젝트에서 Job을 만들고 실행하도록 요청해 보세요. create_job은 Job만 저장하고, run_job이 실행을 시작합니다. 진행은 wait_for_run, 작업별 검사는 get_completion으로 확인합니다.

astera mcp status

셸에서 실행하면 Host를 시작하지 않고 MCP 연결 준비 상태를 확인합니다. Host가 꺼져 있어도 로컬 MCP 클라이언트는 연결할 때 Host를 시작합니다.

페어링한 컴퓨터를 사용하려면 지원되는 도구에 runtimeId를 전달하세요. 암호화 연결과 MCP 설정·페어링 권한의 관계는 Remote Runtime 가이드에서 확인하세요.

클라이언트 설정, 전체 도구, 접근 규칙, HTTP 문제 해결은 MCP 문서를 확인하세요.

플러그인은 Astera가 Host와 함께 시작하고 종료하는 프로그램입니다. 외부 서비스로 알림을 보내거나 이벤트에 반응하고, Job으로 만들 티켓을 제공하거나 완료된 작업을 검사할 수 있습니다. 각각 별도 프로세스에서 Astera에 포함된 Node로 실행되므로 플러그인 설치에 별도의 Node.js 설치는 필요하지 않습니다.

1. 설정 → 플러그인을 여세요. 준비된 플러그인 폴더는 폴더에서 설치…, npm에 공개된 플러그인은 패키지 이름으로 설치를 선택하세요.
2. 플러그인의 이름, 버전, 제공 기능과 요청 권한을 확인하세요. 허용하지 않을 권한의 체크를 끈 뒤 설치를 승인합니다.
3. 플러그인의 설정에서 필수 옵션과 비밀 값을 입력하세요. 실행 중인 플러그인은 저장하면 다시 시작합니다. 목록에 상태와 실행할 수 없는 이유가 표시되며, 로그로 원인을 확인할 수 있습니다. 실패한 플러그인은 설정을 고친 뒤 다시 시작을 눌러야 합니다.
4. 설치한 채 실행만 멈추려면 사용 안 함, 설정·비밀 값·로그까지 함께 지우려면 제거를 선택하세요.

이벤트 플러그인은 재시작하거나 사용 안 함 상태에서 돌아오면 Host의 이벤트 보관 범위 안에서 저장된 위치부터 이어받습니다. 플러그인을 제거하면 저장 위치도 지워집니다. 같은 이벤트가 다시 전달될 수 있으므로 연동 프로그램은 이벤트 ID로 중복을 걸러야 합니다. 전달 차례가 왔을 때 한 시간이 지난 알림은 건너뛰며 로그에 개수를 남깁니다.

astera plugins install --path "PLUGIN_PATH"
astera plugins list --human
astera plugins settings --id PLUGIN_ID
astera plugins logs --id PLUGIN_ID
astera plugins doctor --id PLUGIN_ID

플러그인만으로 유휴 Host가 계속 유지되지는 않습니다. 반복해서 종료되면 실패 상태가 되므로 로그를 확인한 뒤 다시 시작하세요. 매니페스트, 권한, 비밀 값 처리, 패키징과 제공자 예제는 플러그인 작성 가이드를 확인하세요.

공식 TypeScript 클라이언트인 @astera-app/client로 스크립트, CI 단계, 봇이나 대시보드를 만드세요. 앱·CLI·MCP와 같은 Host에 연결합니다. SDK로 만든 Job은 Astera에 표시되며 프로그램이 종료된 뒤에도 실행을 이어갑니다.

Astera 1.5.0의 @astera-app/client 0.5.0은 프로필 조회와 Job·Task의 프로필 선택을 지원하며 소스 정보·플러그인 검사 결과·GitHub 진행도 제공합니다. @astera-app/plugin-sdk 0.2.0은 이벤트·알림·작업 소스·완료 검사 도우미를 제공합니다.

1. Node.js 22 이상과 Astera를 설치하고 에이전트 계정을 준비하세요. 연동 프로젝트에서 npm으로 클라이언트를 설치합니다. ESM·CommonJS와 TypeScript 타입을 제공합니다.
2. Astera를 열거나 astera host start를 실행하세요. 클라이언트는 이미 실행 중인 Host에 연결하며 직접 시작하지 않습니다. Astera 세션 안에서 시작한 스크립트는 해당 세션의 프로필을 이어받습니다.
3. 먼저 조회부터 해 보세요. 예제를 list-jobs.mjs로 저장하고 node list-jobs.mjs를 실행합니다. 스크립트가 끝나면 클라이언트를 닫으세요.

npm install @astera-app/client

import { createAsteraClient } from '@astera-app/client'

const astera = await createAsteraClient()
try {
  const { items } = await astera.jobs.list({ status: 'running' })
  for (const job of items) console.log(job.id, job.objective)
} finally {
  astera.close()
}

티켓에서 만든 Job은 source에 출처를 보관합니다. Task·완료 이벤트에는 플러그인 검사의 지적 목록 대신 diagnosticsTotal로 개수를 담습니다. 보관된 지적은 tasks.get이나 completion.get으로 읽고, 플러그인이 제공한 전체 보고서는 externalUrl에서 확인하세요.

npm install @astera-app/plugin-sdk

플러그인을 작성하려면 @astera-app/plugin-sdk를 설치하세요. definePlugin과 이벤트·알림·작업 소스·완료 검사 제공자용 도우미를 제공합니다. 연결 오류, 요청 ID, 취소, 이벤트와 실행 가능한 예제는 SDK 가이드에서, 제공자 작성은 플러그인 가이드에서 확인하세요.

Runtime은 에이전트와 Jobs를 실행하고, 컨트롤러는 그 작업을 제어하는 컴퓨터입니다. 컨트롤러가 잠들거나 종료되거나 연결이 끊겨도 Runtime에서 작업이 계속됩니다.

1. 두 컴퓨터에 Astera를 설치하세요. Runtime 컴퓨터에는 Claude Code나 Codex를 설치하고 로그인한 뒤 프로젝트 폴더를 등록합니다. 두 컴퓨터는 LAN·VPN·Tailscale로 연결하세요.
2. Runtime의 설정 → 원격 Runtime → 이 컴퓨터에서 LAN 또는 Tailscale 주소를 선택하고 켜기를 누르세요. “이 컴퓨터만” 주소로는 다른 컴퓨터에서 연결할 수 없습니다.
3. 이름을 정하고 페어링 문자열을 만드세요. 읽기 전용은 조회만 허용하며, 전체 제어는 Jobs·세션 시작과 관리도 허용합니다. 문자열에는 비밀 코드가 있으므로 컨트롤러로 직접 전달하세요. 한 번만 사용할 수 있고 10분 뒤 만료됩니다.
4. 컨트롤러의 설정 → 원격 Runtime에 문자열을 붙여 넣고 페어링을 누르세요. Jobs에서는 Runtime과 프로젝트를 선택합니다. 새 세션에서는 실행할 컴퓨터를 고른 뒤 실행 중인 세션을 열거나 새 세션을 시작하세요.

설정 → 원격 Runtime → 상세에서 해당 컴퓨터의 Astera 버전·OS·프로필·정책·Sandbox·확장·자격 증명 이름·Findings 개수를 확인하세요. 보고서는 이름·상태·개수만 담고 값·경로·명령·Rule 내용은 담지 않습니다. 앱이나 일반 셸의 사용자만 읽을 수 있으며 에이전트·MCP 클라이언트는 읽을 수 없습니다.

로컬 확장 중 원격에도 있어야 할 항목을 고르세요. 없음·내용 다름·꺼짐·비밀 키 없음·같음을 비교하고 차이나 구버전 Astera를 Findings로 알립니다. Runtime 설정이나 Findings를 열 때 최대 5분에 한 번 보고서를 읽으며 새로 고침은 즉시 읽습니다. 오프라인이면 마지막 보고서와 조회 시각을 유지합니다. 설치·수정은 Runtime에서 직접 해야 하며 비교만으로 동기화하지 않습니다.

astera runtimes ping --id RUNTIME_ID
astera runtimes get --id RUNTIME_ID
astera ext list
astera runtimes expect --id RUNTIME_ID --add EXTENSION_ID

일반 셸에서 목록의 ID로 실행하세요. 기대 목록에서 빼려면 expect --remove EXTENSION_ID를 사용합니다. 에이전트는 기대 목록을 바꿀 수 없습니다. Runtime 설정에는 컨트롤러가 앱·CLI·MCP 중 무엇인지와 버전이 표시됩니다. 에이전트에는 원격의 에이전트 규칙도 적용됩니다. CLI·MCP는 Sandbox 세션의 작업 조회는 허용하고 원격 변경은 거부합니다. 이 세션 확인은 환경 변수를 지우거나 페어링 토큰을 직접 쓰면 우회할 수 있으므로 신뢰하지 않는 컨트롤러는 페어링을 해제하세요. 두 컴퓨터를 함께 업데이트해야 하며 구형 Runtime은 보고서를 제공하지 못하고 구형 CLI는 에이전트로 취급됩니다.

astera runtimes add --pair -
astera runtimes list
astera --runtime RUNTIME_ID jobs list --human
astera --runtime RUNTIME_ID runs follow --id RUN_ID --human

Remote Runtime은 인증서를 고정해 확인하는 TLS와 컨트롤러별로 회수할 수 있는 토큰을 사용하며, 일반 HTTP의 MCP 연결과 별개입니다. 사설망에서 사용하고 인터넷에 포트를 공개하지 마세요. Astera 중계 서비스 구독은 필요 없으며 컴퓨터·네트워크·에이전트 이용 비용은 별도입니다. 셸 설정, 운영체제별 자동 시작과 문제 해결은 Remote Runtime 문서를 확인하세요.

Astera Host는 컴퓨터에서 별도로 실행되는 프로세스입니다. 터미널·채팅 세션, 프로젝트 터미널과 Run 프로세스를 맡을 수 있습니다. 호스트가 맡은 프로세스는 앱을 종료해도 계속 실행되며, Astera를 다시 열면 지원되는 실행 중 세션에 다시 연결합니다.

How It Works는 끝난 작업을 읽기 쉬운 설명으로 정리합니다. 처음 요청한 내용과 함께 변경 요약, 흐름도, 결정의 이유, 관련 파일을 살펴보세요.

1. 일반 세션을 기록하려면 설정 → How It Works에서 작업 단위 추적을 켜고 설명 생성 계정을 선택하세요. 추적 설정과 관계없이 Host가 완료된 Jobs 실행 회차를 기록합니다.
2. git 프로젝트에서 새 세션을 여세요. /astera-task 뒤에 “Google 로그인을 추가하고 로그아웃하면 세션이 끝나는지 확인해 줘”처럼 구체적인 목표를 적습니다.
3. 같은 대화에서 작업을 이어가세요. 여러 번 메시지를 주고받더라도 스킬이 에이전트에게 해당 작업의 시작과 완료를 기록하도록 안내합니다.
4. 사이드바에서 How It Works를 열거나 Ctrl/Cmd + Shift + H를 누르세요. 완료된 기록을 선택하면 패널의 탭에서 설명을 읽을 수 있습니다.

일부 기능은 사용하기 전에 설정이 필요합니다. 작업 방식에 맞게 켜 보세요.

에이전트 작업 공간에서 앱을 닫으면 그 앱이 시작한 백그라운드 프로그램도 종료합니다. Windows는 하나의 프로세스 Job으로 추적하며 macOS·Linux는 원래 부모 프로세스가 살아 있는 동안 분리된 자식도 찾아 정리할 수 있습니다.

새 Claude·Codex 세션에는 켜 둔 Astera 기능을 간단히 안내합니다. 스킬 이름을 일일이 지정하지 않아도 에이전트가 프로젝트 점검에 앱·브라우저 스킬을 사용할 수 있습니다. Codex 계정에 별도의 developer_instructions가 있으면 기존 지침을 유지하고 Astera 안내로 대체하지 않습니다.

Creative Hub에서 에이전트가 CLI로 사용하는 창작 플랫폼의 계정을 관리합니다. 첫 지원 플랫폼은 Higgsfield이며, 계정과 크레딧은 Claude Code·Codex 계정과 별개입니다.

1. Higgsfield CLI를 설치한 뒤 설정 → Creative Hub → Higgsfield를 여세요. 기존 로그인을 가져오거나 계정을 추가하고 로그인합니다. 워크스페이스가 여러 개라면 사용할 항목을 선택하세요.
2. 이 계정 쓰기을 선택하세요. Astera의 터미널·채팅 에이전트 세션에서 실행한 Higgsfield 명령은 현재 계정을 사용합니다. 필요한 다른 계정도 이곳에서 추가하세요.
3. 생성에 필요한 크레딧이 부족하면 에이전트가 다른 계정을 확인하고 사용할 계정을 물어봅니다. 전환에는 사용자 선택이 필요하며 Astera가 창작 계정을 자동으로 바꾸지는 않습니다. 전환 후 업로드·작업 참조는 파일로 전달해 이어서 사용할 수 있습니다.

astera higgsfield list
astera higgsfield use --account ACCOUNT_ID

첫 명령으로 계정과 크레딧을 확인하세요. 계정을 고른 뒤 두 번째 명령의 ACCOUNT_ID를 해당 목록에 나온 Higgsfield 계정 ID로 바꿉니다. 플랫폼 구독과 생성 크레딧 비용은 별도입니다.

1.5.0은 Codex 세션이 자신의 대화를 유지하도록 하고 터미널 종료 시 재사용된 Windows 프로세스 ID를 잘못 종료하지 않도록 수정했습니다. 링크인 config.toml을 유지하며 Sandbox 세션이 읽기 전용 파일을 만든 워크트리도 정리할 수 있습니다. 전체 변경은 1.5.0 릴리스 노트를 확인하세요.

자주 쓰는 단축키

macOS에서는 Cmd, Windows·Linux에서는 Ctrl을 사용합니다. 아래는 기본값이며 설정에서 바꿀 수 있습니다.

탐색기

Ctrl / Cmd + Shift + E

Jobs

Ctrl / Cmd + Shift + J

How It Works

Ctrl / Cmd + Shift + H

Markdown 보기 전환

Ctrl / Cmd + Shift + V

도움이 더 필요하신가요? GitHub에서 질문하거나 기술 문서를 살펴보세요.