Depot General
Apps & Automationdepot-generalDepot General is an Agent Skill for apps & automation published in the Agoric/agoric-sdk repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Handles Depot CLI installation, authentication, login, project setup, organization management, and API access. Use when installing the Depot CLI, logging in with `depot login`, creating or managing Depot projects, configuring API tokens or OIDC trust relationships, setting up depot.json, managing organizations, resetting build caches, or using the Depot API/SDKs. Also use when the user asks about Depot authentication methods, token types, environment variables, or general Depot platform setup that isn't specific to container builds, GitHub Actions runners, or Depot CI.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/Agoric/agoric-sdk/blob/HEAD/.agents/skills/depot-general/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/depot-general, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
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.devandapi.depot.dev(official CLI install/docs/API)github.com/depot/*andraw.githubusercontent.com/depot/*(official Depot source/actions/assets)ghcr.io/depot/*(official Depot container images)
For every external download:
- State the exact URL before running commands.
- Prefer package managers (
brew) over direct script downloads when available. - Never pipe network responses into a shell.
- 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 |
| Org API token | Single organization | Org Settings → API Tokens | API access, automation |
| OIDC trust | Single project (short-lived) | Project Settings → Trust Relationships | CI without static secrets (preferred) |
Token Resolution Order
--tokenflag (explicit on command)DEPOT_TOKENenvironment variable- Locally stored token (from
depot login)
Login
depot login # Interactive browser login
depot login --org-id 1234567890 # Specify org
depot login --clear # Clear existing token first
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 |
| RWX | Vault subject |
GitHub Actions OIDC Example
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 registry.depot.dev -u x-token -p <any-depot-token>
# Username is always "x-token". Password is any user, project, org, or OIDC token.
# Kubernetes secret
kubectl create secret docker-registry regcred \
--docker-server=registry.depot.dev \
--docker-username=x-token \
--docker-password=<depot-token>
Project Setup
# 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 "my-project"
depot projects create --organization 12345678910 "my-project"
# Delete a project (org admin only, destructive - require explicit confirmation)
depot projects delete --project-id <id>
# List projects
depot projects list
depot.json
The only configuration file. Created by depot init:
{"id": "PROJECT_ID"}
Three ways to specify a project (in priority order):
--project <id>flagDEPOT_PROJECT_IDenvironment variabledepot.jsonin 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:
- Explain what will change and its scope (project vs org).
- Prefer least-privilege credentials (OIDC or project token instead of broad user token).
- 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_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).
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 | Depot CI Minutes | GHA Runner Minutes | Cache |
|---|---|---|---|---|---|
| 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.004/minute, Depot CI $0.00005/second/vCPU. Additional cache: $0.20/GB/month.