첫 명령 실행하기

첫 명령 실행하기 (Run your first command)

기존 샌드박스에서 명령을 실행하고 출력을 수집하는 방법을 알아볼게요.

출처: 문서

본문

기존 샌드박스에서 명령을 실행하고 출력을 수집해요. 인증된 클라이언트와 첫 실행에서 반환된 샌드박스 이름으로 시작해요.

대부분의 명령에는 프로세스 컬렉션의 run 헬퍼를 사용해요. 이 헬퍼는 프로세스를 시작하고 그 결과를 기다려요.

샌드박스 열기 (Open the sandbox)

리소스 이름으로 샌드박스를 가져와요. 반환된 핸들은 프로세스와 파일을 노출하고, 인증된 연결을 관리해요. 샌드박스 주소나 Docker 토큰을 두 번째 클라이언트에 복사할 필요가 없어요.

TypeScript

return client.get(name);

전체 TypeScript 예시: exec/endpoint.ts

import type { Sandboxes } from '@docker/sandboxes';

export async function processesAt(client: Sandboxes, name: string) {
  return client.get(name);
}

프로세스 run 헬퍼 사용하기 (Use the process run helper)

프로그램과 그 인자로 이뤄진 인자 배열을 전달해요. 예를 들어 ['echo', 'Hello from Docker Sandboxes']. 인자는 셸 문법이 아니에요. 파이프, 리다이렉션, 변수 확장이 필요하면 스크립트를 다음 인자로 하는 sh -c를 실행해요.

run 헬퍼는 출력을 수집한 뒤 프로세스 결과를 반환해요. SDK 호출이 성공했다고 명령이 성공한 건 아니에요 — 종료 코드를 확인해야 해요. 표준 오류는 진단 출력이고, 종료 코드가 0이어도 비어 있지 않을 수 있어요.

SDK 오류는 요청, 대기, 연결이 실패했다는 뜻이에요. 오류가 실어 나른 프로세스 핸들이 있으면 그것을 보관해 중복 작업을 시작하는 대신 검사할 수 있어요. Error handling 문서가 그 차이를 설명해요.

TypeScript

return sandbox.processes.run({ args }, { timeoutMs: 300_000 });

전체 TypeScript 예시: exec/outcome.ts

import type { Sandbox } from '@docker/sandboxes';

export async function classifyOutcome(sandbox: Sandbox, args: string[]) {
  return sandbox.processes.run({ args }, { timeoutMs: 300_000 });
}

선택 사항: 명령을 직접 실행하기 (Optional: execute a command directly)

종료 후에만 출력이 필요한 짧은 명령이라면 직접 실행이 더 단순해요. 하나의 요청이 명령을 기다리고 캡처된 출력과 종료 코드를 반환하며, 별도의 프로세스 생성·출력 읽기 절차가 없어요.

캡처된 출력을 완전하다고 다루기 전에 incomplete 플래그를 확인해요. 명령 실행 중에 출력이 필요하면 스트리밍 출력을 선택해요.

TypeScript

const result = await endpoint.api.exec({ body: { cmd: args } });

전체 TypeScript 예시: exec/exec.ts

import type { Sandbox } from '@docker/sandboxes';

export async function runCommand(sandbox: Sandbox, args: string[]) {
  const endpoint = await sandbox.endpointClient(['sandboxesExec'], 'exec');
  try {
    const result = await endpoint.api.exec({ body: { cmd: args } });
    return {
      exitCode: result.exitCode ?? 0,
      stdout: new TextDecoder().decode(result.stdout),
      stderr: new TextDecoder().decode(result.stderr),
      incomplete: result.incomplete ?? false,
    };
  } finally {
    await endpoint.close();
  }
}

더 알아보기 (Learn more)

전체 레시피 목록은 Browse all recipes 에서 확인할 수 있어요.