depot-general

Depot General: CLI, Auth, and Project Setup

Depot is a build acceleration platform. This skill covers CLI installation, authentication, project configuration, and organization management. For product-specific guidance, see the depot-container-builds, depot-github-runners, or depot-ci skills.

CLI Installation

Security default: never execute downloaded scripts directly (curl ... | sh). Download, inspect, and then run.

# macOS (Homebrew)
brew install depot/tap/depot

# Linux: see https://depot.dev/docs/cli/installation for all methods

# Proto version manager
proto plugin add depot "https://raw.githubusercontent.com/depot/cli/refs/heads/main/proto.yaml"
proto install depot

# GitHub Actions
- uses: depot/setup-action@v1

# Container image for CI
ghcr.io/depot/cli:latest

Trusted External Sources

Only reference these domains for external downloads/docs in this skill. If a link is outside this list, ask for confirmation before using it.

• depot.dev and api.depot.dev (official CLI install/docs/API)
• github.com/depot/* and raw.githubusercontent.com/depot/* (official Depot source/actions/assets)
• ghcr.io/depot/* (official Depot container images)

For every external download:

1. State the exact URL before running commands.
2. Prefer package managers (brew) over direct script downloads when available.
3. Never pipe network responses into a shell.
4. Ask for confirmation before executing downloaded artifacts in privileged/system locations.

Authentication

Token Types

Type	Scope	Created Via	Use Case
User token	All projects in all user's orgs	depot login or Account Settings → API Tokens	Local development
Project token	Single project	Project Settings	CI environments
Organization token	Single organization	Org Settings → API Tokens	API access, automation
Pull token	Project registry paths (read-only)	depot pull-token --project <id> (expires after 1 hour)	Pulling saved project images
Registry access token	Selected registry repositories, Pull or Push	Registry Settings → Registry access tokens	Registry automation, including custom repository names
OIDC trust	Single project (short-lived)	Project Settings → Trust Relationships	CI without static secrets (preferred)

Token Resolution Order

1. --token flag (explicit on command)
2. DEPOT_TOKEN environment variable
3. Locally stored token (from depot login)
4. OIDC token (if available)

Login

depot login                           # Interactive browser login
depot login --org-id 1234567890       # Specify org
depot login --clear                   # Clear existing token first
depot login --quiet                   # Silent exit-0 no-op if already logged in (for defensive scripts)
depot login token                     # Print the stored API token to stdout; errors if not logged in
depot logout                          # Remove saved token

OIDC Trust Relationships (Preferred for CI)

Configure in Project Settings → Trust Relationships. No static secrets, just short-lived credentials.

CI Provider	Configuration
GitHub Actions	GitHub org/user name + repository name. Requires permissions: { id-token: write } in workflow.
CircleCI	Organization UUID + Project UUID (must use UUIDs, not friendly names)
Buildkite	Organization slug + Pipeline slug
GitLab CI	GitLab namespace ID + project ID. Requires a DEPOT_OIDC_TOKEN id_token with aud: https://depot.dev in .gitlab-ci.yml.
RWX	Vault subject

GitHub Actions OIDC Example

After the first successful use, a GitHub trust relationship follows the repository through renames and transfers. A different repository created under the old name cannot use the original trust relationship.

jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      id-token: write    # Required for OIDC
    steps:
      - uses: actions/checkout@v4
      - uses: depot/setup-action@v1
      - uses: depot/build-push-action@v1
        with:
          project: <project-id>
          push: true
          tags: myrepo/app:latest

Token-Based CI Auth (When OIDC Not Available)

steps:
  - uses: depot/setup-action@v1
  - uses: depot/build-push-action@v1
    with:
      project: <project-id>
      token: ${{ secrets.DEPOT_TOKEN }}

Depot Registry Auth

docker login {orgId}.registry.depot.dev -u x-token
# Enter an appropriately scoped token at the password prompt.

# Kubernetes secret
kubectl create secret docker-registry regcred \
  --docker-server={orgId}.registry.depot.dev \
  --docker-username=x-token \
  --docker-password=<depot-token>

Use {orgId}.registry.depot.dev for new repositories and custom image names. The legacy registry.depot.dev/<project-id>:<build-id> format remains available for existing saved-build usage.

Prefer a registry access token limited to the required repositories and permission. Organization owners create tokens in Registry Settings → Registry access tokens. Pull grants read access; Push includes pull access. Scope patterns exclude the registry hostname and image tag:

• frontend: one repository.
• team/*: one level below team.
• team/**: any depth below team.
• **: all repositories in the organization.

CLI pull tokens expire after one hour. Pull and project tokens cover only <project-id> and its descendant paths. For other custom or pull-through names, use a registry access token with Pull permission. User and organization tokens can grant broader organization access.

OIDC registry access requires a matching project trust relationship in the organization. The resulting registry access covers the organization; build access remains project-scoped. GitHub OIDC uses audience https://depot.dev.

Project Setup

depot projects get and depot projects update require an organization API token through --token or DEPOT_TOKEN. Stored login tokens and project OIDC credentials do not authorize those commands.

# Create depot.json in current directory (interactive project selection)
depot init

# Create a new project
depot projects create "my-project"
depot projects create --region eu-central-1 --cache-storage-policy 100 --cache-policy-keep-days 30 "my-project"
depot projects create --organization 12345678910 "my-project"

# Inspect a project; omit the ID to use DEPOT_PROJECT_ID or depot.json
depot projects get
depot projects get <project-id> --output json

# Update selected project fields
depot projects update <project-id> --name "New name"
depot projects update <project-id> --region eu-central-1 --cache-storage-policy 100 --output json

# Delete a project (org admin only, destructive - require explicit confirmation)
depot projects delete --project-id <id>

# List projects
depot projects list

New projects keep 50 GB of build cache per architecture and retain cache data for 14 days by default. Set --cache-policy-keep-days 0 during creation for no retention limit. depot projects update changes only supplied fields.

Set --max-concurrent-builds <positive-integer> on depot projects create or depot projects update to enable autoscaling at that concurrent-build limit per builder instance. Use depot projects update <project-id> --disable-autoscaling to disable autoscaling. The update flags are mutually exclusive; omitting both preserves the current setting. New projects default to autoscaling disabled.

depot.json

The only configuration file. Created by depot init:

{"id": "PROJECT_ID"}

Three ways to specify a project (in priority order):

1. --project <id> flag
2. DEPOT_PROJECT_ID environment variable
3. depot.json in current or parent directory

Organization Management

depot org show              # Current org ID
depot org list              # Orgs the user belongs to
depot org switch <org-id>   # Set default org

Roles: User (view projects, run builds) · Owner (create/delete projects, edit settings)

Billing is per-organization. Configure usage caps, OIDC trust relationships, GitHub App connections, and cloud connections from org settings.

Command Triage for Multi-Org Users

If a user belongs to multiple organizations and reports "missing" projects, workflows, or runs, verify Depot org context first:

# 1) Confirm current org
depot org show

# 2) See all orgs user can access
depot org list

# 3) Either switch default org...
depot org switch <org-id>

# ...or keep current default and target commands explicitly, for example:
depot ci run --org <org-id> --workflow .depot/workflows/ci.yml

Prefer explicit --org <org-id> for scripted/automated commands to avoid accidental cross-org confusion.

Command Safety Guardrails

Treat these as high-impact operations and require explicit user intent before execution:

• Project deletion (depot projects delete)
• Any command using auth tokens in shell arguments or logs
• Registry login steps that write long-lived credentials
• Organization-level mutations (project creation/deletion, org switching in automation)

Before running high-impact commands:

1. Explain what will change and its scope (project vs org).
2. Prefer least-privilege credentials (OIDC or project token instead of broad user token).
3. Avoid --yes/force flags unless the user explicitly requests non-interactive behavior.

Environment Variables

Variable	Description
DEPOT_TOKEN	Auth token (user, project, or org)
DEPOT_PROJECT_ID	Project ID (alternative to --project or depot.json)
DEPOT_NO_SUMMARY_LINK=1	Suppress build links and update notices (useful in CI)
DEPOT_IN_AUTOMATION=1	Suppress build summary URLs, saved-image pull/push hints, and update notices; any non-empty value enables suppression, while progress and errors remain
DEPOT_DISABLE_OTEL=1	Disable OpenTelemetry tracing

Build and Cache Management

# List builds
depot list builds
depot list builds --project <id> --output json

# Reset project cache
depot cache reset .                         # Uses depot.json
depot cache reset --project <id>

# Docker integration
depot configure-docker              # Install Depot as Docker plugin + default builder
depot configure-docker --uninstall  # Remove

GitHub Actions: Depot Actions Reference

Action	Purpose
depot/setup-action@v1	Install depot CLI
depot/build-push-action@v1	Drop-in for docker/build-push-action (same inputs/outputs)
depot/bake-action@v1	Drop-in for docker/bake-action
depot/use-action@v1	Set Depot as default Docker Buildx builder
depot/pull-action@v1	Pull from Depot Registry

API Access

Protocol: Connect framework (gRPC + HTTP JSON). SDKs: @depot/sdk-node (Node.js), depot/depot-go (Go).

Core ProjectService.listProjects, getProject, and updateProject require an organization API token. depot projects list uses a different endpoint that also accepts user tokens.

import {depot} from '@depot/sdk-node'
const headers = { Authorization: `Bearer ${process.env.DEPOT_TOKEN}` }

// List projects
const result = await depot.core.v1.ProjectService.listProjects({}, {headers})

// Create a build
const build = await depot.build.v1.BuildService.createBuild(
  {projectId: '<id>'}, {headers}
)

Pricing Plans

Plan	Cost	Docker Build Minutes	Shared Sandbox Minutes	GHA Runner Minutes	Cache and Registry Storage
Developer	$20/mo	500/mo	2,000/mo	2,000/mo	25 GB
Startup	$200/mo	5,000/mo	20,000/mo	20,000/mo	250 GB
Business	Custom	Custom	Custom	Custom	Custom

Per-second billing, no minimums. Overage rates: Docker builds $0.04/minute, GitHub Actions runners $0.006/minute, Depot CI $0.00005/second/vCPU. Additional cache: $0.20/GB/month.

Depot CI, Depot Sandboxes, and Depot Managed Agents share the sandbox allowance. Included minutes use a 2-vCPU baseline; a 4-vCPU sandbox consumes two included minutes per elapsed minute. Container build and GitHub Actions runner allowances remain separate.

Developer and Startup plans include 1,000,000 passing test results each month. Additional passing results cost $1 per 1,000,000. Failed, errored, and skipped results are free.