### Install Go Module Dependencies

Source: https://depot.dev/docs/api/api-container-builds-tutorial

Download the necessary Go module dependencies for the build-api examples. This command should be run from the `go` subdirectory within the cloned examples repository.

```bash
cd go
go mod download
```

--------------------------------

### Install Depot CLI and Build Docker Image

Source: https://depot.dev/docs/container-builds/integrations/bitbucket-pipelines

This snippet shows the basic setup for a Bitbucket Pipeline to install the Depot CLI and build a Docker image.

```yaml
pipelines:
  branches:
    master:
      - step:
          name: Install Depot CLI and build
          script:
            - curl -L https://depot.dev/install-cli.sh | DEPOT_INSTALL_DIR=/usr/local/bin sh
            - depot build .
```

--------------------------------

### Base Image and Dependencies Setup

Source: https://depot.dev/docs/container-builds/optimal-dockerfiles/php-composer-dockerfile

Establishes the base PHP-FPM image and installs essential system packages like Nginx and Supervisor. Cleans up apt cache to reduce image size.

```dockerfile
FROM php:8.4-fpm

RUN apt-get update && apt-get install -y --no-install-recommends \
    libzip-dev \
    nginx \
    supervisor \
    && rm -rf /var/lib/apt/lists/*

WORKDIR /app

```

--------------------------------

### Clone Example Repository

Source: https://depot.dev/docs/api/api-container-builds-tutorial

Clone the example repository to follow along with the tutorial. Navigate into the cloned directory.

```shell
git clone https://github.com/depot/examples.git
cd examples/build-api
```

--------------------------------

### Build and Load Image into CircleCI Job with Depot

Source: https://depot.dev/docs/container-builds/integrations/circleci

This example demonstrates building a container image with Depot and using the `--load` flag to make it available within the CircleCI job for subsequent testing steps. Depot is installed and then used to build the image.

```yaml
version: 2.1

jobs:
  build:
    machine: true
    resource_class: medium
    steps:
      - checkout
      - run:
          name: Install Depot
          command: |
            curl -L https://depot.dev/install-cli.sh | sudo env DEPOT_INSTALL_DIR=/usr/local/bin sh
      - run:
          name: Build and push to Docker Hub with Depot
          command: |
            depot build --load .
workflows:
  run_build:
    jobs:
      - build
```

--------------------------------

### Base Rust Build Stage with Tools

Source: https://depot.dev/docs/container-builds/optimal-dockerfiles/rust-dockerfile

Starts the build stage using a specific Rust version and installs cargo-chef and sccache.

```dockerfile
# syntax=docker/dockerfile:1

FROM rust:1.90 AS build

RUN cargo install cargo-chef sccache --locked
```

--------------------------------

### Install Depot and Build with Docker Executor

Source: https://depot.dev/docs/container-builds/integrations/circleci

Installs the Depot CLI and builds a Docker image using the CircleCI docker executor. Requires `setup_remote_docker` and assumes DEPOT_TOKEN is set.

```yaml
version: 2.1

jobs:
  build:
    docker:
      - image: cimg/node:lts
    resource_class: small
    steps:
      - checkout
      - setup_remote_docker
      - run:
          name: Install Depot
          command: |
            curl -L https://depot.dev/install-cli.sh | sudo env DEPOT_INSTALL_DIR=/usr/local/bin sh
      - run:
          name: Build with Depot
          command: depot build .

workflows:
  run_build:
    jobs:
      - build
```

--------------------------------

### Pip Cache Mount Example

Source: https://depot.dev/docs/container-builds/optimal-dockerfiles/python-pip-dockerfile

Demonstrates how to use a cache mount for pip to persist the package cache across Docker builds, speeding up dependency installation.

```dockerfile
RUN --mount=type=cache,target=/root/.cache/pip \
    pip install -r requirements.txt
```

--------------------------------

### Runtime Stage Base and User Setup

Source: https://depot.dev/docs/container-builds/optimal-dockerfiles/ruby-bundler-dockerfile

Sets up the slim runtime stage and creates a non-root user for enhanced security.

```dockerfile
FROM ruby:3.4-slim AS runtime

RUN groupadd -g 1001 appgroup && \
    useradd -u 1001 -g appgroup -m -d /home/appuser -s /bin/bash appuser
```

--------------------------------

### Install Depot CLI on Linux

Source: https://depot.dev/docs/agents/claude-code/quickstart

Install the Depot CLI on Linux systems using the provided installation script.

```shell
curl -L https://depot.dev/install-cli.sh | sh
```

--------------------------------

### Base Build Stage Configuration

Source: https://depot.dev/docs/container-builds/optimal-dockerfiles/ruby-bundler-dockerfile

Sets up the build environment, configures Bundler for production, and prepares for gem installation.

```dockerfile
# syntax=docker/dockerfile:1

FROM ruby:3.4 AS build

WORKDIR /app

ENV RAILS_ENV=production

COPY Gemfile ./

RUN bundle config set --local without 'development test' && \
    bundle config set --local jobs $(nproc)
```

--------------------------------

### Example tmate SSH Connection Output

Source: https://depot.dev/docs/ci/how-to-guides/debug-with-ssh

This is an example of the output when using `--ssh-after-step`. It shows the repository, job, and organization details, followed by the SSH command to connect to the tmate session.

```text
Repo: depot-demo-org/habits-demo-app
Jobs: lint_typecheck
Inserting tmate step after step 4

Org: <org-id>
Run: hbdc14bcbk

Waiting for tmate session to start...
Waiting for job to be created...
Waiting for tmate session in logs...
Connecting: ssh GPB7Xs4TJj6WEpjNGuuyjUA5R@nyc1.tmate.io
```

--------------------------------

### Install Node.js Dependencies

Source: https://depot.dev/docs/api/api-container-builds-tutorial

Install the necessary Node.js dependencies for the project. This command should be run from the 'nodejs' subdirectory.

```shell
cd nodejs
npm install
```

--------------------------------

### Install Depot CLI

Source: https://depot.dev/docs/container-builds/integrations/fly

Install the Depot CLI for macOS using Homebrew or for Linux using a shell script.

```shell
brew install depot/tap/depot # for Mac
curl -L https://depot.dev/install-cli.sh | sh # for Linux
```

--------------------------------

### Build Stage: Project Installation

Source: https://depot.dev/docs/container-builds/optimal-dockerfiles/python-uv-dockerfile

Copies the application code and installs the project itself using a frozen lock file for reproducible builds.

```dockerfile
COPY . .

RUN --mount=type=cache,target=/root/.cache/uv \
    uv sync --frozen --no-dev

```

--------------------------------

### Base Dockerfile Structure

Source: https://depot.dev/docs/container-builds/optimal-dockerfiles/dotnet-aspnetcore-dockerfile

This snippet shows the initial setup for a multi-stage Docker build, defining the build environment and working directory.

```dockerfile
# syntax=docker/dockerfile:1

FROM mcr.microsoft.com/dotnet/sdk:8.0 AS build

WORKDIR /src
```

--------------------------------

### Install Depot and Build with Machine Executor

Source: https://depot.dev/docs/container-builds/integrations/circleci

Installs the Depot CLI and builds a Docker image using the CircleCI machine executor. Ensure the DEPOT_TOKEN environment variable is set in your CircleCI project settings.

```yaml
version: 2.1
jobs:
  build:
    machine: true
    resource_class: medium
    steps:
      - checkout
      - run:
          name: Install Depot
          command: |
            curl -L https://depot.dev/install-cli.sh | sudo env DEPOT_INSTALL_DIR=/usr/local/bin sh
      - run:
          name: Build with Depot
          command: |
            depot build .
```

--------------------------------

### Example docker-bake.hcl file

Source: https://depot.dev/docs/cli/reference/container-builds

Defines build targets, platforms, and tags for container images using HCL syntax.

```hcl
group "default" {
  targets = ["original", "db"]
}

target "original" {
  dockerfile = "Dockerfile"
  platforms = ["linux/amd64", "linux/arm64"]
  tags = ["example/app:test"]
}

target "db" {
  dockerfile = "Dockerfile.db"
  platforms = ["linux/amd64", "linux/arm64"]
  tags = ["example/db:test"]
}
```

--------------------------------

### Basic Buildkite Pipeline Step

Source: https://depot.dev/docs/container-builds/integrations/buildkite

A basic Buildkite pipeline step to install the Depot CLI and build a Docker image.

```yaml
steps:
  - label: 'Build image with Depot'
    command:
      - 'curl -L https://depot.dev/install-cli.sh | DEPOT_INSTALL_DIR=/usr/local/bin sh'
      - 'depot build .'
```

--------------------------------

### Docker Compose File Example

Source: https://depot.dev/docs/container-builds/how-to-guides/docker-compose

Defines services with build contexts and Dockerfiles for Docker Compose.

```yaml
# docker-compose.yml
services:
  app:
    build:
      context: .
      dockerfile: Dockerfile

  backend:
    build:
      context: ./backend
      dockerfile: Dockerfile
```

--------------------------------

### Example docker-bake.hcl with project_id

Source: https://depot.dev/docs/cli/reference/container-builds

Specifies different Depot projects for individual build targets within the same bake file.

```hcl
group "default" {
  targets = ["original", "db"]
}

target "original" {
  dockerfile = "Dockerfile"
  platforms = ["linux/amd64", "linux/arm64"]
  tags = ["example/app:test"]
  project_id = "project-id-1"
}

target "db" {
  dockerfile = "Dockerfile.db"
  platforms = ["linux/amd64", "linux/arm64"]
  tags = ["example/db:test"]
  project_id = "project-id-2"
}
```

--------------------------------

### Get Build Step Logs (Go)

Source: https://depot.dev/docs/api/sdk-reference

Use this to get the logs for a build step. Pass the build ID, project ID, build step digest, and page size. An optional page token can be used for pagination.

```go
import (
		"net/http"
		buildv1 "buf.build/gen/go/depot/api/protocolbuffers/go/depot/build/v1"
		"buf.build/gen/go/depot/api/connectrpc/go/depot/build/v1/buildv1connect"
		"connectrpc.com/connect"
	)

    token := os.Getenv("DEPOT_TOKEN")

    client := buildv1connect.NewBuildServiceClient(
    	http.DefaultClient,
    	"https://api.depot.dev",
    )

    req := connect.NewRequest(&buildv1.GetBuildStepLogsRequest{
    	BuildId: "build-id",
    	ProjectId: "project-id",
    	BuildStepDigest: "step-digest",
    })

    req.Header().Set("Authorization", fmt.Sprintf("Bearer %s", token))

    resp, err := client.GetBuildStepLogs(ctx, req)
    if err != nil {
    	log.Fatal(err)
    }

    log.Printf("Logs: %v", resp.Msg.Logs)
```

--------------------------------

### Create Project using Depot Go SDK

Source: https://depot.dev/docs/api/api-container-builds-tutorial

Demonstrates the initial setup for creating a project using the Depot Go SDK and Buf Connect API. It shows importing necessary packages and retrieving the organization token from environment variables.

```go
import (
    "net/http"
    corev1 "buf.build/gen/go/depot/api/protocolbuffers/go/depot/core/v1"
    corev1connect "buf.build/gen/go/depot/api/connectrpc/go/depot/core/v1/corev1connect"
    "connectrpc.com/connect"
)

token := os.Getenv("DEPOT_TOKEN")

```

--------------------------------

### Get Workflow Information Response Example

Source: https://depot.dev/docs/api/ci/reference

This is an example of the JSON response you can expect when retrieving workflow information.

```json
{
  "orgId": "org_123",
  "runId": "run_123",
  "repo": "repo_example",
  "ref": "ref_example",
  "sha": "b2f5ff47436671b6e533d8dc3614845d",
  "headSha": "b2f5ff47436671b6e533d8dc3614845d",
  "trigger": "trigger_example",
  "runStatus": "runStatus_example"
}
```

--------------------------------

### Get Job Attempt Logs Response Example

Source: https://depot.dev/docs/api/ci/reference

Example JSON response structure for the GetJobAttemptLogs API call, including log lines and pagination token.

```json
{
  "lines": [
    {
      "stepKey": "stepKey_example",
      "timestampMs": 1,
      "lineNumber": 1,
      "stream": 1,
      "body": "body_example",
      "stepId": "step_123"
    }
  ],
  "nextPageToken": "nextPageToken_example"
}
```

--------------------------------

### Build Stage: Base Image and uv Setup

Source: https://depot.dev/docs/container-builds/optimal-dockerfiles/python-uv-dockerfile

Sets up the build environment using a slim Python image and copies the uv binary. Configures uv for bytecode compilation and file copying.

```dockerfile
FROM python:3.13-slim AS build

COPY --from=ghcr.io/astral-sh/uv:0.8.21 /uv /uvx /bin/

WORKDIR /app

ENV UV_COMPILE_BYTECODE=1 UV_LINK_MODE=copy

```

--------------------------------

### Runtime Stage Setup

Source: https://depot.dev/docs/container-builds/optimal-dockerfiles/go-dockerfile

Sets up the runtime environment using a minimal Ubuntu base image. It creates a non-root user for enhanced security and copies the compiled application binary.

```dockerfile
FROM ubuntu:24.04 AS runtime

RUN groupadd -g 1001 appgroup && \
    useradd -u 1001 -g appgroup -m -d /app -s /bin/false appuser

COPY --from=build --chown=appuser:appgroup /bin/app /usr/local/bin/app

USER appuser

ENV TZ=UTC \
    GOMAXPROCS=0

ENTRYPOINT ["/usr/local/bin/app"]

```

--------------------------------

### Get Job Summary Response

Source: https://depot.dev/docs/api/ci/reference

Example JSON response when successfully retrieving a job summary.

```JSON
{
  "orgId": "org_123",
  "runId": "run_123",
  "workflowId": "workflow_123",
  "jobId": "job_123",
  "attemptId": "attempt_123",
  "attempt": 1,
  "jobStatus": "jobStatus_example",
  "attemptStatus": "attemptStatus_example"
}
```

--------------------------------

### Get Failure Diagnosis Response

Source: https://depot.dev/docs/api/ci/reference

Example JSON response from the GetFailureDiagnosis endpoint, detailing failure information, context, and representative attempts.

```json
{
  "orgId": "org_123",
  "target": {
    "targetId": "target_123",
    "targetType": "FAILURE_DIAGNOSIS_TARGET_TYPE_UNSPECIFIED",
    "status": "FAILURE_DIAGNOSIS_RESOURCE_STATUS_UNSPECIFIED"
  },
  "context": {
    "runId": "run_123",
    "repo": "repo_example",
    "ref": "ref_example",
    "sha": "b2f5ff47436671b6e533d8dc3614845d",
    "headSha": "b2f5ff47436671b6e533d8dc3614845d",
    "trigger": "trigger_example"
  },
  "state": "FAILURE_DIAGNOSIS_STATE_UNSPECIFIED",
  "emptyReason": "FAILURE_DIAGNOSIS_EMPTY_REASON_UNSPECIFIED",
  "failureGroups": [
    {
      "fingerprint": "fingerprint_example",
      "source": "source_example",
      "count": 1,
      "errorMessage": "errorMessage_example",
      "errorMessageTruncated": false,
      "errorMessageOriginalLength": 1
    }
  ],
  "representativeAttempts": [
    {
      "runId": "run_123",
      "workflowId": "workflow_123",
      "workflowName": "workflowName_example",
      "workflowPath": "workflowPath_example",
      "jobId": "job_123",
      "jobKey": "jobKey_example"
    }
  ],
  "bounds": {
    "failedProblemCandidateCount": 1,
    "failedProblemCandidateCap": 1,
    "totalProblemJobCount": 1,
    "skippedDependentCount": 1,
    "totalFailureGroupCount": 1,
    "omittedFailureGroupCount": 1
  }
}
```

--------------------------------

### Runtime Stage: Base Image and User Setup

Source: https://depot.dev/docs/container-builds/optimal-dockerfiles/python-uv-dockerfile

Sets up the runtime environment with a clean slim image, creates a non-root user for security, and copies the built application.

```dockerfile
FROM python:3.13-slim AS runtime

ENV PATH="/app/.venv/bin:$PATH"

RUN groupadd -g 1001 appgroup && \
    useradd -u 1001 -g appgroup -m -d /app -s /bin/false appuser

WORKDIR /app

COPY --from=build --chown=appuser:appgroup /app .

USER appuser

ENTRYPOINT ["python", "-m", "uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]

```

--------------------------------

### Set up Build Environment

Source: https://depot.dev/docs/container-builds/optimal-dockerfiles/dotnet-worker-dockerfile

Initializes the build stage using the .NET 8 SDK image, sets the working directory, and copies project files for dependency restoration.

```dockerfile
FROM mcr.microsoft.com/dotnet/sdk:8.0 AS build

WORKDIR /src

COPY src/WorkerService/WorkerService.csproj src/WorkerService/
COPY *.sln ./
```

--------------------------------

### Get Failure Diagnosis Request (cURL)

Source: https://depot.dev/docs/api/ci/reference

Example cURL command to call the GetFailureDiagnosis endpoint. Ensure you set the DEPOT_TOKEN environment variable.

```bash
curl -X POST https://api.depot.dev/depot.ci.v1.CIService/GetFailureDiagnosis \
  -H "Authorization: Bearer $DEPOT_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Connect-Protocol-Version: 1" \
  --json @- <<'JSON'
{
  "targetId": "target_123",
  "targetType": "FAILURE_DIAGNOSIS_TARGET_TYPE_UNSPECIFIED"
}
JSON
```

--------------------------------

### Go Build Stage Setup

Source: https://depot.dev/docs/container-builds/optimal-dockerfiles/go-dockerfile

Sets up the build environment by defining the working directory and copying Go module files. This helps in optimizing layer caching for dependencies.

```dockerfile
FROM golang:1.25 AS build

WORKDIR /src

COPY go.mod go.sum ./

COPY vendor* ./vendor/

```

--------------------------------

### Get Artifact Download URL Response

Source: https://depot.dev/docs/api/ci/reference

Example JSON response containing artifact metadata and a short-lived signed URL for downloading the artifact.

```json
{
  "artifact": {
    "artifactId": "artifact_123",
    "runId": "run_123",
    "workflowId": "workflow_123",
    "workflowPath": "workflowPath_example",
    "jobId": "job_123",
    "jobKey": "jobKey_example"
  },
  "url": "https://example.com",
  "expiresAt": "expiresAt_example"
}
```

--------------------------------

### Runtime Stage Setup

Source: https://depot.dev/docs/container-builds/optimal-dockerfiles/dotnet-aspnetcore-dockerfile

Sets up the runtime stage using a smaller ASP.NET Core image, creates a non-root user, and copies the published application artifacts.

```dockerfile
FROM mcr.microsoft.com/dotnet/aspnet:8.0 AS runtime

RUN groupadd -g 1001 appgroup && \
    useradd -u 1001 -g appgroup -m -d /app -s /bin/false appuser

WORKDIR /app

COPY --from=build --chown=appuser:appgroup /app/publish .
```

--------------------------------

### Get Artifact Download URL Request

Source: https://depot.dev/docs/api/ci/reference

Example cURL request to obtain a signed download URL for a specific artifact using its artifactId.

```bash
curl -X POST https://api.depot.dev/depot.ci.v1.CIService/GetArtifactDownloadURL \
  -H "Authorization: Bearer $DEPOT_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Connect-Protocol-Version: 1" \
  --json @- <<'JSON'
{
  "artifactId": "artifact_123"
}
JSON
```

--------------------------------

### Get Job Metrics Response

Source: https://depot.dev/docs/api/ci/reference

Example response structure for the GetJobMetrics endpoint, detailing job, workflow, attempt statistics, and capping metadata.

```json
{
  "run": {
    "runId": "run_123",
    "repo": "repo_example",
    "ref": "ref_example",
    "sha": "b2f5ff47436671b6e533d8dc3614845d",
    "headSha": "b2f5ff47436671b6e533d8dc3614845d",
    "trigger": "trigger_example"
  },
  "workflow": {
    "workflowId": "workflow_123",
    "workflowPath": "workflowPath_example",
    "name": "name_example",
    "status": "status_example",
    "createdAt": "createdAt_example",
    "startedAt": "startedAt_example"
  },
  "job": {
    "jobId": "job_123",
    "jobKey": "jobKey_example",
    "status": "status_example",
    "conclusion": "conclusion_example",
    "currentAttempt": 1,
    "createdAt": "createdAt_example"
  },
  "attempts": [
    {
      "attempt": {
        "attemptId": "attempt_123",
        "attempt": 1,
        "status": "status_example",
        "conclusion": "conclusion_example",
        "sandboxId": "sandbox_123",
        "sessionId": "session_123"
      },
      "availability": {
        "code": "CI_METRICS_AVAILABILITY_CODE_UNSPECIFIED",
        "reason": "reason_example"
      },
      "stats": {
        "sampleCount": 1,
        "cpuSampleCount": 1,
        "memorySampleCount": 1,
        "peakCpuUtilization": 1,
        "averageCpuUtilization": 1,
        "peakMemoryUtilization": 1
      },
      "cap": {
        "rawSampleCount": 1,
        "returnedSampleCount": 1,
        "maxReturnedSampleCount": 1,
        "downsampled": false,
        "downsampleStrategy": "downsampleStrategy_example"
      }
    }
  ],
  "snapshotAt": "snapshotAt_example"
}
```

--------------------------------

### Runtime Stage with User Setup

Source: https://depot.dev/docs/container-builds/optimal-dockerfiles/java-gradle-dockerfile

Sets up the runtime environment by creating a non-root user and group. It then copies the built application JAR file to the runtime stage, ensuring it's owned by the new user.

```dockerfile
FROM eclipse-temurin:21-jre AS runtime

RUN groupadd -g 1001 appgroup && \
    useradd -u 1001 -g appgroup -m -d /app -s /bin/false appuser

WORKDIR /app

COPY --from=build --chown=appuser:appgroup /app/build/libs/*.jar app.jar

```

--------------------------------

### Get Organization Usage

Source: https://depot.dev/docs/api/sdk-reference

Retrieves overall usage data for the organization within a specified time period. Requires start and end timestamps.

```APIDOC
## Get Organization Usage

### Description
Retrieves overall usage data for the organization within a specified time period. Requires start and end timestamps. This data mirrors the CSV generated from the Depot UI.

### Method
`depot.core.v1.UsageService.getUsage` (Node.js SDK)
`client.GetUsage` (Go SDK)

### Parameters
#### Request Body (Node.js SDK)
- **startAt** (Timestamp) - Required - The starting timestamp of the period.
- **endAt** (Timestamp) - Required - The ending timestamp of the period.

#### Request Body (Go SDK)
- **StartAt** (Timestamp) - Required - The starting timestamp of the period.
- **EndAt** (Timestamp) - Required - The ending timestamp of the period.

### Request Example (Node.js)
```typescript
const request = {
  startAt: timestampFromDate(new Date('2025-09-01T00:00:00Z')),
  endAt: timestampFromDate(new Date('2025-09-30T23:59:59Z'))
}
```

### Response
#### Success Response
- **containerBuild** (object) - Usage data for container builds.
- **githubActionsJobs** (object) - Usage data for GitHub Actions jobs.
- **storage** (object) - Usage data for storage.
- **agentSandbox** (object) - Usage data for agent sandbox.

### Response Example (Node.js)
```json
{
  "containerBuild": { ... },
  "githubActionsJobs": { ... },
  "storage": { ... },
  "agentSandbox": { ... }
}
```
```

--------------------------------

### Get Job Attempt Metrics (Node.js)

Source: https://depot.dev/docs/api/ci/reference

Example of how to retrieve job attempt metrics using Node.js. This demonstrates making a POST request to the GetJobAttemptMetrics endpoint.

```javascript
const depot = require("@depot/api");

async function getMetrics(attemptId) {
  const client = new depot.ci.v1.CIServiceClient({
    // Optional: configure your client here, e.g., with credentials.
  });

  const request = new depot.ci.v1.GetJobAttemptMetricsRequest({
    attemptId: attemptId,
  });

  const response = await client.getJobAttemptMetrics(request);
  console.log(response);
}

getMetrics("attempt_123");
```

--------------------------------

### List Build Steps (Go)

Source: https://depot.dev/docs/api/sdk-reference

Use this to list the steps for a build. Pass the build ID, project ID, and page size. An optional page token can be used for pagination.

```go
import (
		"net/http"
		buildv1 "buf.build/gen/go/depot/api/protocolbuffers/go/depot/build/v1"
		"buf.build/gen/go/depot/api/connectrpc/go/depot/build/v1/buildv1connect"
		"connectrpc.com/connect"
	)

    token := os.Getenv("DEPOT_TOKEN")

    client := buildv1connect.NewBuildServiceClient(
    	http.DefaultClient,
    	"https://api.depot.dev",
    )

    req := connect.NewRequest(&buildv1.GetBuildStepsRequest{
    	BuildId: "build-id",
    	ProjectId: "project-id",
    })

    req.Header().Set("Authorization", fmt.Sprintf("Bearer %s", token))

    resp, err := client.GetBuildSteps(ctx, req)
    if err != nil {
    	log.Fatal(err)
    }

    log.Printf("Steps: %v", resp.Msg.BuildSteps)
```

--------------------------------

### Get Organization Usage (Node.js)

Source: https://depot.dev/docs/api/sdk-reference

Retrieve organization-wide usage data for a specified period. Requires start and end timestamps. Ensure DEPOT_TOKEN is set in your environment.

```typescript
import {depot, wkt} from '@depot/sdk-node'
const {timestampFromDate} = wkt

const headers = {
  Authorization: `Bearer ${process.env.DEPOT_TOKEN}`,
}

const request = {
  startAt: timestampFromDate(new Date('2025-09-01T00:00:00Z')),
  endAt: timestampFromDate(new Date('2025-09-30T23:59:59Z')),
}

const result = await depot.core.v1.UsageService.getUsage(request, {headers})

console.log(result.containerBuild)
console.log(result.githubActionsJobs)
console.log(result.storage)
console.log(result.agentSandbox)
```

--------------------------------

### Create a Project (Go)

Source: https://depot.dev/docs/api/sdk-reference

Use this snippet to create a new project in Depot using Go. Ensure your DEPOT_TOKEN environment variable is set.

```go
import (
	"net/http"
	corev1 "buf.build/gen/go/depot/api/protocolbuffers/go/depot/core/v1"
	"buf.build/gen/go/depot/api/connectrpc/go/depot/core/v1/corev1connect"
	"connectrpc.com/connect"
)

token := os.Getenv("DEPOT_TOKEN")

client := corev1connect.NewProjectServiceClient(
	http.DefaultClient,
	"https://api.depot.dev",
)

req := connect.NewRequest(&corev1.CreateProjectRequest{
	Name:     "my-project",
	RegionId: "us-east-1",
	CachePolicy: &corev1.CachePolicy{
		KeepBytes: 50 * 1024 * 1024 * 1024, // 50GB
		KeepDays:  14,
	},
})

req.Header().Set("Authorization", fmt.Sprintf("Bearer %s", token))

resp, err := client.CreateProject(ctx, req)
if err != nil {
	log.Fatal(err)
}

log.Printf("Project ID: %s", resp.Msg.Project.ProjectId)
```

--------------------------------

### Get Job Metrics Request

Source: https://depot.dev/docs/api/ci/reference

Example cURL command to retrieve job metrics. Ensure you replace $DEPOT_TOKEN with your actual bearer token and provide the correct jobId.

```bash
curl -X POST https://api.depot.dev/depot.ci.v1.CIService/GetJobMetrics \
  -H "Authorization: Bearer $DEPOT_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Connect-Protocol-Version: 1" \
  --json @- <<'JSON'
{
  "jobId": "job_123"
}
JSON
```

--------------------------------

### Create a new Depot Project

Source: https://depot.dev/docs/api/api-container-builds-tutorial

This snippet shows how to create a new project in Depot using the Go client. It includes setting cache policies and authentication.

```go
import (
	"fmt"
	"log"
	"net/http"

	"connectrpc.com/connect"
	"github.com/depot/depot-go/api/core/v1"
	"github.com/depot/depot-go/api/core/v1/corev1connect"
)

// Create the Project Service client
client := corev1connect.NewProjectServiceClient(
	http.DefaultClient,
	"https://api.depot.dev",
)

// Create a new project
req := connect.NewRequest(&corev1.CreateProjectRequest{
	Name:     "my-project",
	RegionId: "us-east-1",
	CachePolicy: &corev1.CachePolicy{
		KeepGb:   50, // 50GB
		KeepDays: 14, // 14 days
	},
})

// Add authentication header
req.Header().Set("Authorization", fmt.Sprintf("Bearer %s", token))

resp, err := client.CreateProject(ctx, req)
if err != nil {
	log.Fatal(err)
}

log.Printf("Project ID: %s", resp.Msg.Project.ProjectId)
```

--------------------------------

### Get Project Usage

Source: https://depot.dev/docs/api/sdk-reference

Retrieves usage data for a specific project within a given time range. Requires project ID, start timestamp, and end timestamp.

```APIDOC
## Get Project Usage

### Description
Retrieves usage data for a specific project within a given time range. Requires project ID, start timestamp, and end timestamp.

### Method
`depot.core.v1.UsageService.getProjectUsage` (Node.js SDK)
`client.GetProjectUsage` (Go SDK)

### Parameters
#### Request Body (Node.js SDK)
- **projectId** (string) - Required - The ID of the project.
- **startAt** (Timestamp) - Required - The starting timestamp of the period.
- **endAt** (Timestamp) - Required - The ending timestamp of the period.

#### Request Body (Go SDK)
- **ProjectId** (string) - Required - The ID of the project.
- **StartAt** (Timestamp) - Required - The starting timestamp of the period.
- **EndAt** (Timestamp) - Required - The ending timestamp of the period.

### Request Example (Node.js)
```typescript
const request = {
  projectId: 'myprojectid',
  startAt: timestampFromDate(new Date('2025-09-01T00:00:00Z')),
  endAt: timestampFromDate(new Date('2025-09-30T23:59:59Z'))
}
```

### Response
#### Success Response
- **usage** (object) - Contains the usage data for the project.

### Response Example (Node.js)
```json
{
  "usage": { ... }
}
```
```

--------------------------------

### Use Depot CLI directly in GitHub Actions

Source: https://depot.dev/docs/container-builds/integrations/github-actions

Install the Depot CLI using depot/setup-action and then execute build commands directly. This method requires the project ID and build context.

```yaml
jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      id-token: write
    steps:
      - uses: actions/checkout@v4
      - uses: depot/setup-action@v1
      - run: depot build --project <your-project-id> --push --tag repo/image:tag .

```

--------------------------------

### Get Project Usage (Node.js)

Source: https://depot.dev/docs/api/sdk-reference

Retrieve usage data for a specific project. Requires project ID, start, and end timestamps. Ensure DEPOT_TOKEN is set in your environment.

```typescript
import {depot, wkt} from '@depot/sdk-node'
const {timestampFromDate} = wkt

const headers = {
  Authorization: `Bearer ${process.env.DEPOT_TOKEN}`,
}

const request = {
  projectId: 'myprojectid',
  startAt: timestampFromDate(new Date('2025-09-01T00:00:00Z')),
  endAt: timestampFromDate(new Date('2025-09-30T23:59:59Z')),
}

const result = await depot.core.v1.UsageService.getProjectUsage(request, {headers})
console.log(result.usage)
```

--------------------------------

### Runtime Stage Setup and User Creation

Source: https://depot.dev/docs/container-builds/optimal-dockerfiles/python-poetry-dockerfile

Sets up the runtime stage with a clean Python image, defines the virtual environment path, and creates a non-root user ('appuser') for enhanced security. This stage prepares the environment for running the application.

```dockerfile
FROM python:3.13-slim AS runtime

ENV VENV_PATH="/opt/pysetup/.venv" \
    PATH="/opt/pysetup/.venv/bin:$PATH"

RUN groupadd -g 1001 appgroup && \
    useradd -u 1001 -g appgroup -m -d /home/appuser -s /bin/bash appuser

WORKDIR /app
```

--------------------------------

### Runtime Stage Dockerfile Setup

Source: https://depot.dev/docs/container-builds/optimal-dockerfiles/node-pnpm-dockerfile

Sets up the runtime stage, creating a non-root user and group for security, and copying the built application artifacts from the build stage.

```dockerfile
FROM node:lts AS runtime

RUN groupadd -g 1001 appgroup && \
    useradd -u 1001 -g appgroup -m -d /app -s /bin/false appuser

WORKDIR /app

COPY --from=build --chown=appuser:appgroup /app ./

ENV NODE_ENV=production \
    NODE_OPTIONS="--enable-source-maps"

USER appuser

ENTRYPOINT ["node", "server.js"]
```

--------------------------------

### Maven Build Job in GitHub Actions

Source: https://depot.dev/docs/cache/integrations/maven

Example GitHub Actions job configuration for running Maven builds on a Depot runner. Includes checkout, Java setup, and the build command.

```yaml
jobs:
  build:
    runs-on: depot-ubuntu-24.04
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-java@v4
        with:
          distribution: 'temurin'
          java-version: '17'
      - run: mvn clean install
```

--------------------------------

### Get Organization Usage (Go)

Source: https://depot.dev/docs/api/sdk-reference

Retrieve organization-wide usage data for a specified period using the Go SDK. Requires start and end timestamps. Ensure DEPOT_TOKEN is set in your environment.

```go
import (
	"net/http"
	"time"
	corev1 "buf.build/gen/go/depot/api/protocolbuffers/go/depot/core/v1"
	"buf.build/gen/go/depot/api/connectrpc/go/depot/core/v1/corev1connect"
	"connectrpc.com/connect"
	"google.golang.org/protobuf/types/known/timestamppb"
)

token := os.Getenv("DEPOT_TOKEN")

client := corev1connect.NewUsageServiceClient(
	http.DefaultClient,
	"https://api.depot.dev",
)

startAt, _ := time.Parse(time.RFC3339, "2025-09-01T00:00:00Z")
endAt, _ := time.Parse(time.RFC3339, "2025-09-30T23:59:59Z")

req := connect.NewRequest(&corev1.GetUsageRequest{
	StartAt: timestamppb.New(startAt),
	EndAt: timestamppb.New(endAt),
})

req.Header().Set("Authorization", fmt.Sprintf("Bearer %s", token))

resp, err := client.GetUsage(ctx, req)
if err != nil {
	log.Fatal(err)
}

log.Printf("Container build usage: %v", resp.Msg.ContainerBuild)
log.Printf("GitHub Actions jobs: %v", resp.Msg.GithubActionsJobs)
log.Printf("Storage: %v", resp.Msg.Storage)
log.Printf("Agent sandbox: %v", resp.Msg.AgentSandbox)
```

--------------------------------

### Get Project Usage (Go)

Source: https://depot.dev/docs/api/sdk-reference

Retrieve usage data for a specific project using the Go SDK. Requires project ID, start, and end timestamps. Ensure DEPOT_TOKEN is set in your environment.

```go
import (
	"net/http"
	"time"
	corev1 "buf.build/gen/go/depot/api/protocolbuffers/go/depot/core/v1"
	"buf.build/gen/go/depot/api/connectrpc/go/depot/core/v1/corev1connect"
	"connectrpc.com/connect"
	"google.golang.org/protobuf/types/known/timestamppb"
)

token := os.Getenv("DEPOT_TOKEN")

client := corev1connect.NewUsageServiceClient(
	http.DefaultClient,
	"https://api.depot.dev",
)

startAt, _ := time.Parse(time.RFC3339, "2025-09-01T00:00:00Z")
endAt, _ := time.Parse(time.RFC3339, "2025-09-30T23:59:59Z")

req := connect.NewRequest(&corev1.GetProjectUsageRequest{
	ProjectId: "myprojectid",
	StartAt: timestamppb.New(startAt),
	EndAt: timestamppb.New(endAt),
})

req.Header().Set("Authorization", fmt.Sprintf("Bearer %s", token))

resp, err := client.GetProjectUsage(ctx, req)
if err != nil {
	log.Fatal(err)
}

log.Printf("Usage: %v", resp.Msg.Usage)
```

--------------------------------

### Configure Runtime and Entrypoint

Source: https://depot.dev/docs/container-builds/optimal-dockerfiles/dotnet-worker-dockerfile

Copies the published application, switches to the non-root user, sets environment variables for containerized .NET execution, and defines the entrypoint.

```dockerfile
COPY --from=build --chown=appuser:appgroup /app/publish/WorkerService .

USER appuser

ENV DOTNET_RUNNING_IN_CONTAINER=true \
    DOTNET_EnableDiagnostics=0

ENTRYPOINT ["./WorkerService"]
```

--------------------------------

### Register a new build with Depot

Source: https://depot.dev/docs/api/api-container-builds-tutorial

This Go snippet demonstrates how to register a new build with Depot, obtaining a build ID and a one-time build token. It also shows how to defer reporting the build result.

```go
import (
	"github.com/depot/depot-go/build"
	cliv1 "github.com/depot/depot-go/proto/depot/cli/v1"
)

token := os.Getenv("DEPOT_TOKEN")
projectID := os.Getenv("DEPOT_PROJECT_ID")

build, err := build.NewBuild(ctx, &cliv1.CreateBuildRequest{
	ProjectId: projectID,
}, token)
if err != nil {
	log.Fatal(err)
}

// Report build result when finished
var buildErr error
deferr build.Finish(buildErr)
```

--------------------------------

### Initialize Depot in Repository

Source: https://depot.dev/docs/container-builds/how-to-guides/local-development

Configure your git repository to use Depot by creating a depot.json file.

```bash
depot init
```

--------------------------------

### Install Poetry with Cache Mount

Source: https://depot.dev/docs/container-builds/optimal-dockerfiles/python-poetry-dockerfile

Installs the specified version of Poetry using pip. It includes a cache mount for the pip cache directory to speed up subsequent installations.

```dockerfile
RUN --mount=type=cache,target=/root/.cache \
    pip install "poetry==$POETRY_VERSION"
```

--------------------------------

### Using Depot CLI directly in GitHub Actions

Source: https://depot.dev/docs/container-builds/integrations/depot-ci

Install the `depot` CLI with `depot/setup-action` and run builds directly using `depot build` commands.

```yaml
jobs:
  build:
    runs-on: depot-ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: depot/setup-action@v1
      - run: depot build --project <your-project-id> --push --tag repo/image:tag .
```

--------------------------------

### Travis CI Configuration for Depot CLI Installation

Source: https://depot.dev/docs/container-builds/integrations/travis-ci

Configure your .travis.yml file to install the Depot CLI before running build commands. This includes setting the installation directory and downloading the script.

```yaml
sudo: required
env:
  - DEPOT_INSTALL_DIR=/usr/local/bin

before_install:
  - curl -L https://depot.dev/install-cli.sh | sudo sh

script:
  - depot build .
```

--------------------------------

### Basic GitLab CI Configuration with Depot CLI

Source: https://depot.dev/docs/container-builds/integrations/gitlab-ci

Installs the Depot CLI and builds a Docker image. Ensure DEPOT_TOKEN is set as a CI/CD variable.

```yaml
build-image:
  before_script:
    - curl https://depot.dev/install-cli.sh | DEPOT_INSTALL_DIR=/usr/local/bin sh
  script:
    - depot build .
  variables:
    # Pass project token or user access token
    DEPOT_TOKEN: $DEPOT_TOKEN
```

--------------------------------

### Install Depot CLI on macOS

Source: https://depot.dev/docs/agents/claude-code/quickstart

Install the Depot CLI using Homebrew on macOS systems.

```shell
brew install depot/tap/depot
```

--------------------------------

### Install Project Dependencies with Poetry Cache Mount

Source: https://depot.dev/docs/container-builds/optimal-dockerfiles/python-poetry-dockerfile

Installs project dependencies using Poetry. This snippet uses a cache mount for Poetry's cache directory to persist downloaded dependencies, accelerating future installs.

```dockerfile
RUN --mount=type=cache,target=/root/.cache/pypoetry \
    poetry install --no-root
```

--------------------------------

### Build Stage Dockerfile Setup

Source: https://depot.dev/docs/container-builds/optimal-dockerfiles/node-pnpm-dockerfile

Initializes the build stage using the Node.js LTS image, enables corepack for pnpm, and sets up environment variables for pnpm.

```dockerfile
FROM node:lts AS build

RUN corepack enable

ENV PNPM_HOME="/pnpm"
ENV PATH="$PNPM_HOME:$PATH"

WORKDIR /app
```

--------------------------------

### Build and Push Container Image (Go)

Source: https://depot.dev/docs/api/api-container-builds-tutorial

Builds and pushes a container image to a specified registry. This example uses Go and the Depot Build API.

```go
Attrs: map[string]string{
    "name":           "docker.io/myuser/myapp:latest",  // or ghcr.io, ECR, etc.
    "oci-mediatypes": "true",
    "push":           "true",
},
},
```

--------------------------------

### Gem Installation with Caching

Source: https://depot.dev/docs/container-builds/optimal-dockerfiles/ruby-bundler-dockerfile

Installs gems using Bundler with dual cache mounts for efficient dependency management and cleanup.

```dockerfile
RUN --mount=type=cache,target=/usr/local/bundle/cache \
    --mount=type=cache,target=/app/vendor/cache \
    bundle cache && \
    bundle install && \
    bundle clean --force
```

--------------------------------

### BuildKit Cache Mount Example

Source: https://depot.dev/docs/container-builds/optimal-dockerfiles/python-uv-dockerfile

Demonstrates how to use BuildKit cache mounts to persist the uv package manager cache across builds, speeding up subsequent builds.

```dockerfile
RUN --mount=type=cache,target=/root/.cache/uv \
    uv sync --no-install-project --no-dev

```

--------------------------------

### Install All Dependencies Dockerfile

Source: https://depot.dev/docs/container-builds/optimal-dockerfiles/node-npm-dockerfile

Installs all dependencies, including dev dependencies, for building the application. Leverages the same cache mount for efficiency.

```dockerfile
RUN --mount=type=cache,target=/root/.npm \
    npm ci --no-audit --no-fund

```

--------------------------------

### Using depot/build-push-action in GitHub Actions

Source: https://depot.dev/docs/container-builds/integrations/depot-ci

Use the `depot/build-push-action` to build and push container images. Ensure `depot/setup-action` is used first to install the Depot CLI.

```yaml
jobs:
  build:
    runs-on: depot-ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: depot/setup-action@v1
      - uses: depot/build-push-action@v1
        with:
          project: <your-depot-project-id>
          context: .
```

--------------------------------

### Configure BuildKit Solve Options

Source: https://depot.dev/docs/api/api-container-builds-tutorial

Sets up the BuildKit solver options, specifying the frontend, build context, platform, and export settings for an image build.

```go
import (
	"github.com/docker/cli/cli/config"
	"github.com/moby/buildkit/session"
	"github.com/moby/buildkit/session/auth/authprovider"
	"github.com/moby/buildkit/client"
)

solverOptions := client.SolveOpt{
	Frontend: "dockerfile.v0",
	FrontendAttrs: map[string]string{
		"filename": "Dockerfile",
		"platform": "linux/arm64",
	},
	LocalDirs: map[string]string{
		"dockerfile": ".",
		"context":    ".",
	},
	Exports: []client.ExportEntry{
		{
			Type: "image",
			Attrs: map[string]string{
				"name":           "myuser/myapp:latest",
				"oci-mediatypes": "true",
				"push":           "true",
			},
		},
	},
	Session: []session.Attachable{
		authprovider.NewDockerAuthProvider(config.LoadDefaultConfigFile(os.Stderr), nil),
	},
}
```