Announcing Depot Managed Agents and Sandboxes

API

Depot SDK Reference

You can interact with the Depot API through Connect RPC clients for Node.js and Go:

Node.js SDK: @depot/sdk-node for TypeScript and JavaScript projects
Go clients: generated Connect and protobuf packages from the depot/api Buf module, plus depot/depot-go helpers for build and BuildKit lifecycles

The clients provide access to project, organization, build, registry, Code, GitHub Actions, BuildKit, and usage services.

API services

The Depot API includes the following services. Access each service through the SDKs using the methods listed below:

Project service

depot.core.v1.ProjectService

ListProjects - List all projects for an organization
GetProject - Get details for a specific project
CreateProject - Create a new project
UpdateProject - Update a project's configuration
DeleteProject - Delete a project
ResetProject - Reset a project (terminates all machines and deletes all cached data)
ListTrustPolicies - List trust policies for a project
AddTrustPolicy - Add a trust policy to a project
UpdateTrustPolicy - Change a trust policy's restrictions
RemoveTrustPolicy - Remove a trust policy from a project
ListTokens - List all tokens for a project
CreateToken - Create a new project token
UpdateToken - Update a project token
DeleteToken - Delete a project token

Build execution service

depot.build.v1.BuildService

CreateBuild - Create a new build
FinishBuild - Mark a build as finished
GetBuildSteps - Get the steps for a build
GetBuildStepLogs - Get logs for a specific build step

Registry service

depot.build.v1.RegistryService

ListImages - List all images in a project's registry
DeleteImage - Delete images from a project's registry

Registry retention service

depot.registry.v1beta1.RegistryService

GetRetentionPolicy - Read the explicit policy for a repository or organization default
UpsertRetentionPolicy - Set a count-based or time-based retention policy
DeleteRetentionPolicy - Remove an explicit policy

See Manage Registry retention policies for Node.js and Go examples.

Build records service

depot.core.v1.BuildService

ShareBuild - Create a public share URL for a build
StopSharingBuild - Disable public sharing for a build
ListBuilds - List builds for a project
GetBuild - Get metadata for a build

Organization service

depot.core.v1.OrganizationService

ListOrganizations - List organizations available to the authenticated user

Code service

depot.code.v1beta1.CodeService

CreateRepository - Create a standalone repository or a GitHub mirror
DeleteRepository - Delete a repository and make its refs unreachable

Use depot.code.v1beta1.CodeService in Node.js or the generated Go CodeServiceClient. See the Code API reference for authentication, examples, and generated client links.

GitHub Actions service

depot.core.v1.GithubActionsService

ListGithubActionsJobs - List jobs, newest first
GetGithubActionsJob - Get a job's details
TerminateGithubActionsJob - Terminate the compute resource for a queued or running job
SearchGithubActionsLogs - Search log lines
CountGithubActionsLogs - Count matching log lines
GetGithubActionsLogContext - Get lines surrounding a search result
ListGithubActionsLogFacets - List available log filter values
GetGithubActionsAnalytics - Get time-bucketed job and usage analytics
GetGithubActionsDurationDistribution - Get the duration distribution of finished jobs
ListGithubActionsJobRuns - List finished jobs, longest duration first
ListGithubActionsJobAnalytics - List aggregate resource usage, duration, and failure metrics by job
ListGithubActionsRecommendations - List runner-size recommendations
ListGithubActionsConnections - List GitHub App connections
CreateGithubActionsInstallationUrl - Create a short-lived GitHub App installation URL
DeleteGithubActionsConnection - Disconnect a GitHub App installation
ListGithubActionsRepositories - List repositories visible through a connection
GetGithubActionsTestResultsSummary - Get a job's test-result summary
GetGithubActionsUsageProjection - Get actual and projected usage for a billing period

Use depot.core.v1.GithubActionsService in Node.js. The GitHub Actions API reference covers authentication and request examples. The generated service reference linked above describes each RPC's request and response fields for Go and other generated clients.

The current generated Go client also exposes GetGithubActionsJobMetrics for a job's CPU, memory, and out-of-memory evidence. This method isn't yet exported by the Node SDK on main; use the generated Go client or Connect JSON.

BuildKit service

depot.buildkit.v1.BuildKitService

GetEndpoint - Get a BuildKit endpoint for a build
ReportHealth - Report the health status of a build
ReleaseEndpoint - Release a BuildKit endpoint

Usage service

depot.core.v1.UsageService

ListProjectUsage - List usage data for projects
GetProjectUsage - Get usage data for a specific project
GetUsage - Get detailed usage data over a specified period

Project service

Docs: depot.core.v1.ProjectService

A project is an isolated cache. Projects belong to a single organization and are never shared. They represent the layer cache associated with the images built inside of it; you can build multiple images for different platforms with a single project. Or you can choose to have one project per image built.

When you want to segregate your customer builds from one another, we recommend one project per customer.

List projects for an organization

You can list all of the projects for your org with an empty request payload.

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

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

console.log(result.projects)

Create a project

To create a project, you need to pass a request that contains the name of the project, the id of your organization, the region you want to create the project in, and the cache volume size you want to use with the project.

In cachePolicy, set keepGb to a value from 25 to 1000 GB per architecture for Depot-hosted projects and keepDays to a value from 1 to 30 days. The API rejects nonzero keepGb values outside that range with an InvalidArgument error. Projects in your own cloud have the same 25 GB minimum but no 1000 GB maximum.

Supported regions:

us-east-1
eu-central-1

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

const result = await depot.core.v1.ProjectService.createProject(
  {
    name: 'my-project',
    organizationId: 'org-id',
    regionId: 'us-east-1',
    cachePolicy: {keepGb: 50, keepDays: 14},
  },
  {headers},
)

console.log(result.project)

Get a project

To get a project, you need to pass the ID of the project you want to get.

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

const result = await depot.core.v1.ProjectService.getProject({projectId: 'project-id'}, {headers})

console.log(result.project)

Update a project

To update a project, you can pass the ID of the project you want to update and the fields you want to update. Omitted fields keep their current values. In Go, optional scalar fields use pointers to distinguish an omitted value from an explicit value.

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

const result = await depot.core.v1.ProjectService.updateProject(
  {
    projectId: 'project-id',
    name: 'my-project',
    regionId: 'us-east-1',
    cachePolicy: {keepGb: 50, keepDays: 14},
  },
  {headers},
)

console.log(result.project)

Delete a project

You can delete a project by ID. This will destroy any underlying volumes associated with the project.

await depot.core.v1.ProjectService.deleteProject({projectId: 'project-id'}, {headers})

Reset a project

Resetting a project terminates its active build machines and permanently deletes its cached build data. The project itself and its configuration remain available.

await depot.core.v1.ProjectService.resetProject({projectId: 'project-id'}, {headers})

List tokens for a project

You can list the tokens for a project by ID.

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

const result = await depot.core.v1.ProjectService.listTokens({projectId: 'project-id'}, {headers})

Create a project token

You can create a token for a given project ID.

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

const result = await depot.core.v1.ProjectService.createToken(
  {
    projectId: 'project-id',
    description: 'my-token',
  },
  {headers},
)

Update a project token

You can update a project token by ID.

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

const result = await depot.core.v1.ProjectService.updateToken(
  {
    tokenId: 'token-id',
    description: 'new-description',
  },
  {headers},
)

Delete a project token

You can delete a project token by ID.

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

const result = await depot.core.v1.ProjectService.deleteToken({tokenId: 'token-id'}, {headers})

List trust policies for a project

const policies = await depot.core.v1.ProjectService.listTrustPolicies({projectId: 'project-id'}, {headers})

Add a trust policy for a project

// GitHub
await depot.core.v1.ProjectService.addTrustPolicy(
  {
    projectId: 'project-id',
    provider: {
      case: 'github',
      value: {
        repositoryOwner: 'org',
        repository: 'repo',
      },
    },
  },
  {headers},
)

// BuildKite
await depot.core.v1.ProjectService.addTrustPolicy(
  {
    projectId: 'project-id',
    provider: {
      case: 'buildkite',
      value: {
        organizationSlug: 'org',
        pipelineSlug: 'pipeline',
      },
    },
  },
  {headers},
)

// CircleCI
await depot.core.v1.ProjectService.addTrustPolicy(
  {
    projectId: 'project-id',
    provider: {
      case: 'circleci',
      value: {
        organizationUuid: 'uuid',
        projectUuid: 'uuid',
      },
    },
  },
  {headers},
)

For GitLab, use the typed provider. The protectedRefsOnly field is available in the Node SDK on main. If your installed SDK lacks this field, use current generated Go clients or Connect JSON.

// GitLab
await depot.core.v1.ProjectService.addTrustPolicy(
  {
    projectId: 'project-id',
    provider: {
      case: 'gitlab',
      value: {
        namespaceId: 'numeric-namespace-id',
        projectId: 'numeric-gitlab-project-id',
        protectedRefsOnly: true,
      },
    },
  },
  {headers},
)

Update a trust policy for a project

Use UpdateTrustPolicy to change restrictions on an existing GitHub or GitLab policy. Authenticate with an organization token. The operation is available in the Node SDK on main and current generated Go clients.

Set protectedRefsOnly for GitLab or allowPublicPullRequests for GitHub. Omitted fields keep their current values; explicit false turns the setting off. Supply only the field for the policy's provider. Provider identities cannot be edited: add a new policy and remove the old one instead.

For example, allow all refs on an existing GitLab policy:

import {createClient} from '@depot/sdk-node'

const client = createClient({token: process.env.DEPOT_TOKEN})
const result = await client.core.v1.ProjectService.updateTrustPolicy({
  projectId: 'project-id',
  trustPolicyId: 'policy-id',
  protectedRefsOnly: false,
})

console.log(result.trustPolicy)

Remove a trust policy for a project

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

await depot.core.v1.ProjectService.removeTrustPolicy({projectId: 'project-id', trustPolicyId: 'policy-id'}, {headers})

Build records service

Docs: depot.core.v1.BuildService

This service reads build metadata and controls public build sharing. It is separate from depot.build.v1.BuildService, which creates and finishes builds.

For the Go examples, create a client once. Each request below adds the authorization header:

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

Create a public URL for a build. Calling the method again returns the existing share URL.

const result = await depot.core.v1.BuildService.shareBuild({buildId: 'build-id'}, {headers})
console.log(result.shareUrl)

Disable the public share URL for a build.

await depot.core.v1.BuildService.stopSharingBuild({buildId: 'build-id'}, {headers})

List builds

List build metadata for a project. Use nextPageToken from a response to request the next page.

const result = await depot.core.v1.BuildService.listBuilds(
  {projectId: 'project-id', pageSize: 100, pageToken: undefined},
  {headers},
)
console.log(result.builds, result.nextPageToken)

Get build metadata

Get the status, timestamps, duration, and cache-step counts for one build.

const result = await depot.core.v1.BuildService.getBuild({buildId: 'build-id'}, {headers})
console.log(result.build)

Organization service

Docs: depot.core.v1.OrganizationService

List organizations

List the organizations available to the authenticated user or token.

const result = await depot.core.v1.OrganizationService.listOrganizations({}, {headers})
console.log(result.organizations)

Build execution service

Docs: depot.build.v1.BuildService

A build is a single image build within a given project. Once you create a build for a project, you get back an ID to reference it and a token for authentication.

Create a build

To create a build, you need to pass a request that contains the ID of the project you want to build in.

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

const result = await depot.build.v1.BuildService.createBuild({projectId: 'project-id'}, {headers})

console.log(result.buildId)
console.log(result.buildToken)

Using the build id & token

If you're not managing the build context yourself in code via buildx, you can use the Depot CLI to build a given Dockerfile as we wrap buildx inside our CLI. With a build created via our API, you pass along the project, build ID, and token as environment variables:

DEPOT_BUILD_ID=<build-id>
DEPOT_TOKEN=<build-token>
DEPOT_PROJECT_ID=<project-id>
depot build -f Dockerfile

Note: Build IDs are unique identifiers generated by Depot when creating a build via the API. When you set the DEPOT_BUILD_ID environment variable, depot build uses the existing build instead of creating a new one. If a build with that ID doesn't exist, the command will error.

Finish a build

Note: You only need to do this if you're managing the build context yourself in code via buildx.

To mark a build as finished and clean up the underlying BuildKit endpoint, you need to pass the ID of the build you want to finish and the error result if there was one.

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

await depot.build.v1.BuildService.finishBuild(
  {buildId: 'build-id', result: {case: 'error', value: {error: 'error message'}}},
  {headers},
)

List the steps for a build

To list the steps for a build, you need to pass the build ID, the project ID, the number of steps to page, and an optional page token returned from a previous API call.

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

const result = await depot.build.v1.BuildService.getBuildSteps(
  {
    buildId: 'build-id',
    projectId: 'project-id',
    pageSize: 100,
    pageToken: 'page-token',
  },
  {headers},
)

Get the logs for a build step

To get the logs for a build step, you need to pass the build ID, the project ID, and the build step's digest. You can also pass the number of lines to page and an optional page token returned from a previous API call.

const headers = {Authorization: `Bearer ${process.env.DEPOT_TOKEN}`}
const result = await depot.build.v1.BuildService.getBuildStepLogs(
  {
    buildId: 'build-id',
    projectId: 'project-id',
    buildStepDigest: 'step-digest',
    pageSize: 100,
    pageToken: 'page-token',
  },
  {headers},
)

Manage Registry retention policies

Use depot.registry.v1beta1.RegistryService to configure image retention during automated repository provisioning. Authenticate with an organization token. The token determines the organization; you don't need an organization ID or x-depot-org header. Project tokens and Registry pull/push tokens don't authorize these management operations.

Set repository to a repository path such as team/app, without a registry host or organization prefix. Use ** for the organization-default policy. Set exactly one positive integer strategy:

keepCount in Node.js or KeepCount in Go: retain the most recent 1 to 1000 images.
keepDays in Node.js or KeepDays in Go: retain images for 1 to 30 days from when they were pushed.

Sending both strategies, neither strategy, or a value outside these ranges returns InvalidArgument. The enabled field isn't a switch for disabling retention. Use DeleteRetentionPolicy to remove an explicit policy.

Set and read a policy

Set DEPOT_TOKEN to an organization token. These examples replace the explicit policy for team/app with a policy that keeps 10 images, then read it back. They print only the retention values.

import {createClient} from '@depot/sdk-node'

const token = process.env.DEPOT_TOKEN
if (!token) throw new Error('Set DEPOT_TOKEN to an organization token')

const registry = createClient({token}).registry.v1beta1.RegistryService

await registry.upsertRetentionPolicy({repository: 'team/app', enabled: true, keepCount: 10})

const {policy} = await registry.getRetentionPolicy({repository: 'team/app'})
console.log(policy ? {keepCount: policy.keepCount, keepDays: policy.keepDays} : 'No explicit policy')

For a time-based organization default, change repository to ** and replace keepCount: 10 with keepDays: 30. In Go, use Repository: "**" and KeepDays: proto.Int32(30), leaving KeepCount unset. Go uses pointers to distinguish an absent strategy from zero.

GetRetentionPolicy reads the explicit policy for the requested scope. An absent policy in Node.js or a nil Policy in Go means that scope has no explicit policy; it doesn't mean an inherited policy is absent.

Remove an explicit policy

Using the client and token above, remove the repository's explicit policy:

await registry.deleteRetentionPolicy({repository: 'team/app'})

An inherited policy may still apply after you remove a repository policy. Use ** to remove the explicit organization-default policy. Deleting a policy doesn't delete the repository or its images, and it doesn't restore images already removed by retention.

Registry service

Docs: depot.build.v1.RegistryService

The Registry service provides access to the underlying registry that stores the images built by Depot. You can use this service to list and delete images.

List the images for a project

To list the images for a project, you need to pass the ID of the project you want to list the images for. When listing more than 100 images, you can use the pageSize and pageToken fields to paginate the results.

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

const result = await depot.build.v1.RegistryService.listImages(
  {
    projectId: 'project-id',
    pageSize: 100,
    pageToken: undefined,
  },
  {headers},
)

console.log(result.images)
console.log(result.nextPageToken)

The images returned will consist of an image tag, digest, a pushedAt timestamp, and the size of the image in bytes.

Delete images

To delete images, you need to pass the ID of the project and the list of image tags you want to remove.

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

await depot.build.v1.RegistryService.deleteImage(
  {
    projectId: 'project-id',
    imageTags: ['image-tag-1', 'image-tag-2'],
  },
  {headers},
)

BuildKit service

Docs: depot.buildkit.v1.BuildKitService

The BuildKit service provides lower level access to the underlying BuildKit endpoints that power the image builds. They give you the ability to interact with the underlying builders without needing the Depot CLI as a dependency. For example, you can use the buildx Go library with the given BuildKit endpoint to build images from your own code via Depot.

Get a BuildKit endpoint

To get a BuildKit endpoint, you need to pass the ID of the build you want to get the endpoint for and the platform you want to build.

Supported platforms:

PLATFORM_AMD64 for linux/amd64 builds
PLATFORM_ARM64 for linux/arm64 builds

Note: The BuildKit service requires the buildx Go library. While the Node.js SDK includes these methods, you can only use buildx with Go.

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

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

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

// Acquire a BuildKit machine
buildkit, err := machine.Acquire(ctx, build.ID, build.Token, "amd64")
if err != nil {
    log.Fatal(err)
}
defer buildkit.Release()

// Connect to BuildKit
buildkitClient, err := buildkit.Connect(ctx)
if err != nil {
    log.Fatal(err)
}

When a connection is active and ready to be used, you can use the buildkitClient to execute builds using the BuildKit API.

Report the health of a build

To report the health of a build, you need to pass the ID of the build you want to report and the platform.

Once you acquire a BuildKit endpoint, you must report the health of the build to Depot or the underlying resources will be removed after 5 minutes of inactivity.

import (
    "net/http"
    buildkitv1 "buf.build/gen/go/depot/api/protocolbuffers/go/depot/buildkit/v1"
    "buf.build/gen/go/depot/api/connectrpc/go/depot/buildkit/v1/buildkitv1connect"
    "connectrpc.com/connect"
)

buildToken := os.Getenv("BUILD_TOKEN")

client := buildkitv1connect.NewBuildKitServiceClient(
    http.DefaultClient,
    "https://api.depot.dev",
)

req := connect.NewRequest(&buildkitv1.ReportHealthRequest{
    BuildId: "build-id",
    Platform: buildkitv1.Platform_PLATFORM_AMD64,
})

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

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

Release the endpoint for a build

To release the endpoint for a build, you need to pass the ID of the build you want to release and the platform.

This endpoint tells Depot you're done using that endpoint and we can schedule it for removal.

import (
    "github.com/depot/depot-go/machine"
)

// The buildkit.Release() method handles releasing the endpoint
defer buildkit.Release()

Usage service

Docs: depot.core.v1.UsageService

The UsageService service enables consuming resource utilization data via API.

List project usage

List usage for all projects over a time range. Use nextPageToken from a response to request the next page.

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

const result = await depot.core.v1.UsageService.listProjectUsage(
  {
    startAt: timestampFromDate(new Date('2025-09-01T00:00:00Z')),
    endAt: timestampFromDate(new Date('2025-09-30T23:59:59Z')),
    pageSize: 100,
  },
  {headers},
)

console.log(result.usage, result.nextPageToken)

Get usage for one project

To get usage for a given project, you need to pass a project id, and the starting and ending timestamp of the desired period. All three parameters are mandatory.

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)

Get usage for a given period

To get usage data for your organization for a specific period of time, you need to pass the starting and ending timestamp of the period. Both startAt and endAt are mandatory parameters.

getUsage returns the same data as the CSV generated via Settings > Usage > Usage History.

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)

API services

Project service

Build execution service

Registry service

Registry retention service

Build records service

Organization service

Code service

GitHub Actions service

BuildKit service

Usage service

Project service

List projects for an organization

Create a project

Get a project

Update a project

Delete a project

Reset a project

List tokens for a project

Create a project token

Update a project token

Delete a project token

List trust policies for a project

Add a trust policy for a project

Update a trust policy for a project

Remove a trust policy for a project

Build records service

Share a build

Stop sharing a build

List builds

Get build metadata

Organization service

List organizations

Build execution service

Create a build

Using the build id & token

Finish a build

List the steps for a build

Get the logs for a build step

Manage Registry retention policies

Set and read a policy

Remove an explicit policy

Registry service

List the images for a project

Delete images

BuildKit service

Get a BuildKit endpoint

Report the health of a build

Release the endpoint for a build

Usage service

List project usage

Get usage for one project

Get usage for a given period