diff --git a/content/agents/claude-code/quickstart.mdx b/content/agents/claude-code/quickstart.mdx new file mode 100644 index 0000000..903a5ad --- /dev/null +++ b/content/agents/claude-code/quickstart.mdx @@ -0,0 +1,138 @@ +--- +title: Quickstart for remote Claude Code agents on Depot +ogTitle: Getting started with remote Claude Code agents on Depot +description: Step by step guide on how to get up and running with remote Claude Code agents on Depot. +--- + +import {CheckCircleIcon} from '~/components/icons' +import {DocsCTA} from '~/components/blog/CTA' + +This guide will help you get started with Depot's remote agent sandboxes for running Claude Code agents. With Depot, you can run your coding agents in a secure, isolated environment in the cloud, allowing you to move your coding sessions off of your local machine and into fast remote environments where you can easily launch, resume, and share coding sessions. + +## 1. Install the `depot` CLI + +Before you can start running remote agents, you need to install the Depot CLI. The CLI is available for Mac and Linux. + +**Note:** Remote agent sandboxes are only available on `depot` CLI version 2.96.2 or later. + +For Mac, you can install the CLI with Homebrew: + +```shell +brew install depot/tap/depot +``` + +For Linux, you can install the CLI with [our installation script](https://depot.dev/install-cli.sh): + +```shell +# Install the latest version +curl -L https://depot.dev/install-cli.sh | sh + +# Install a specific version +curl -L https://depot.dev/install-cli.sh | sh -s 2.96.2 +``` + +For all other platforms, you can download the binary directly from [the latest release](https://github.com/depot/cli/releases). + +## 2. Creating a Depot organization + +Claude Code agent sandboxes and sandbox secrets live under a Depot organization. So before you can launch your first agent sandbox, you need to create a Depot organization. + +![Create a Depot organization](/images/docs/depot-create-organization.webp) + +1. Login to your Depot account to get to your [list of organizations](/orgs) +2. Click on the `Create Organization` button +3. Enter an organization name +4. Click `Create organization` + +## 3. Get your Anthropic credentials + +Today Depot only supports bringing your own Anthropic subscription or API key. We do not provide our own Anthropic API key for use with Depot's remote agent sandboxes. + +There are two options for configuring your Anthropic credentials to use with Depot's remote agent sandboxes. + +### Claude Code token for Max plan + +**This is our recommended method for using Claude Code with Depot's remote agent sandboxes.** + +If you're on the **Max plan** from Anthropic, you need to get your Claude Code OAuth token to use with Depot's remote agent sandboxes. + +First, using the `claude` CLI, you can generate a new OAuth token: + +```shell +claude setup-token +``` + +This will output a token that you can copy and use in the next step. + +![Claude Code OAuth token](/images/docs/claude-code-setup-token.webp) + +### Anthropic API key + +Alternatively, you can generate an Anthropic API key by following their [Developer Platform](https://docs.anthropic.com/en/api/overview) documentation. + +## 4. Set your Anthropic credentials + +For Depot to use your Anthropic credentials for remote Claude Code agents, you need to configure a secret in your Depot organization for your Anthropic API key or OAuth token. + +### Max plan subscribers (OAuth token) + +If you generated a Claude Code OAuth token, you can set it as a secret in your Depot organization: + +```shell +depot claude secrets add CLAUDE_CODE_OAUTH_TOKEN --value +``` + +### Anthropic API key + +If you generated an Anthropic API key, you can set it as a secret in your Depot organization: + +```shell +depot claude secrets add ANTHROPIC_API_KEY --value +``` + +## 5. Access your git repositories + +You can work with public and private git repositories in your remote agent sandboxes. If you want to use private git repositories, you need to either install the `Depot Code` app into your GitHub organization, or set your Git credentials as secrets in your Depot organization. + +### Install the Depot Code app into your GitHub organization + +To grant remote agent sandboxes access to your private GitHub repositories, you can install the `Depot Code` app into your GitHub organization. This will allow you to clone and push changes to your private repositories from within your remote agent sandboxes. + +![Install Depot Code app](/images/docs/depot-code-github-app.webp) + +1. Login to your Depot account and [select your organization](/orgs) +2. Click on the `Settings` tab in the sidebar +3. Scroll down to the `GitHub Code Access` section +4. Click `Connect to GitHub` + +### Granting access outside of GitHub + +If you prefer not to use the Depot Code app, you can set your Git credentials as secrets in your Depot organization. This allows you to clone and push changes to your private repositories using your Git credentials. + +To set your Git credentials as secrets, run the following commands: + +```shell +depot claude secrets add GIT_CREDENTIALS --value +``` + +## 6. Launch your first remote agent sandbox + +Once you've configured your Anthropic credentials and Git access, you can launch your first remote agent sandbox using the `depot claude` command. + +```shell +depot claude + --session-id feature-auth \ + --repository https://github.com/foo/bar \ + --branch main \ + "Give me a general summary of this repository" + +✓ Claude sandbox started! + Session ID: 557737f9-6274-4df0-ac78-fda2122b6180 + Link: https://depot.dev/orgs/12293423849/claude/9842347238947 +``` + +This command immediately tells the Depot control plane to start a new agent sandbox for Claude Code. Returning a url to the session inside of Depot where you can follow the output. + +![Remote Claude Code session inside of Depot](/images/docs/remote-claude-code-session-ui.webp) + +And that's it! You now have your Depot organization set up to make use of Depot agent sandboxes for Claude Code. You can pass different git repositories that your git credentials or Depot Code app have access to, you can specify different branches, you can resume a session using the `--resume` flag, and you can fork new sessions from an existing file systems using the `--session-id` flag and `--resume` flag at the same time. diff --git a/content/agents/overview.mdx b/content/agents/overview.mdx new file mode 100644 index 0000000..6dcac50 --- /dev/null +++ b/content/agents/overview.mdx @@ -0,0 +1,100 @@ +--- +title: Remote Agents +ogTitle: Overview of Depot remote agents +description: Learn how to use move your coding agents off of your local machine and onto Depot's remote agents platform +--- + +import {CheckCircleIcon} from '~/components/icons' +import {DocsCTA, DocsCTASecondary} from '~/components/blog/CTA' + +Depot's remote agent sandboxes provide a secure, isolated environment for running AI coding agents like Claude Code in the cloud. Allowing you to move your agent coding sessions off of your local machine and into fast remote environments where you can easily launch, resume, and share sessions. + +Current agent sandboxes support Claude Code, with more agents coming soon. By default, running `depot claude` will start a new session in a remote sandbox. + + + + To dive into using remote agents on Depot, check out our Claude Code quickstart guide → + + + +## Key features + +### Isolated environments + +Each agent session runs in its own isolated container, providing a clean and secure environment for your development work. Sessions are completely isolated from each other, ensuring your work remains private and secure. + +### Persistent file system + +Agent sandboxes work directly with your git repositories and persists files automatically across agents sessions. Allowing you to resume your work exactly where you left off, whether you're picking up a session from last week, sharing with a teammate, or starting a new session from an existing sandbox. + +### Pre-configured development tools + +Agent sandboxes come pre-installed with popular programming languages, package managers, and development tools. + +### Session management + +Every agent sandbox not only persists your filesystem, but also the entire context and conversation you have built up with your coding agent in the remote sandbox. + +### Git integration + +Work directly with Git repositories in your sandbox. Clone public or private repositories (using secrets for authentication), make changes, and push updates - all within the isolated environment. + +### High performance + +Agent sandboxes run on Depot's optimized infrastructure with plans to provide automatic integrations with our existing Depot services like accelerated container builds, Depot Cache, and more. Every sandbox launches with **2 vCPUs and 4 GB RAM** by default, providing ample resources for most development tasks. + +### Web UI for sessions + +Easily manage your agent sessions through the Depot web UI. Start, resume, and share sessions with just a few clicks. The web interface provides a simple way to monitor your active sessions and access session logs. + +## How it works + +To demonstrate how remote agents work in Depot, we will use the `depot claude` command to demonstrate how remote Claude Code agents are launched in Depot. + +**Note:** To run the command below, you should complete the [Quickstart guide for Claude Code](/docs/agents/claude-code/quickstart) first. + +```shell +depot claude \ + --session-id feature-auth \ + --repository https://github.com/user/repo.git \ + --branch main \ + "Implement authentication flow" +``` + +This command will fire a request to the Depot control plane to start a new remote agent sandbox and return a url to the web UI where that Claude Code session can be monitored and managed. + +Behind the scenes, Depot will do all of the following: + +1. **Session creation**: A new isolated container is provisioned for your session, named after the `--session-id` you provided or generate a session ID if not specified +2. **Environment setup**: The sandbox comes pre-configured with development tools, languages, and libraries +3. **Load filesystem**: The sandbox can be prepopulated with a filesystem from a previous session via the `--resume` flag. If no previous session is passed in, a brand new file system is provisioned for the session. +4. **Git repository cloning**: If you specified a `--repository`, Depot will clone the repository into the sandbox and checkout the specified branch (if no branch is specified, it defaults to `main`) +5. **Session saving**: When Claude Code has finished it's work and exits, the session state is preserved for later resumption +6. **Easy resumption**: Use `--resume ` to continue from any environment + +Here is an example workflow where we start a new session with one prompt, then resume it later to continue working: + +```shell +# Start a new session with a custom ID +depot claude \ + --session-id feature-auth \ + --repository https://github.com/user/repo.git \ + "Create a new branch called `feature-auth` and lets implement authentication flow for this new feature. Once you're happy with the initial implementation, commit your changes and push the branch to the remote repository." + +# Later, resume the session to continue working +depot claude --resume feature-auth "This looks good, but we need to add the concept of a user profile now." +``` + +## Pricing + +Depot remote agent sandboxes are available on **all plans** and are billed at a usage rate of **$0.01/minute** with no included usage for remote agents. + + + + Start your 7-day free trial to try remote agents on Depot → + + diff --git a/content/cache/authentication.mdx b/content/cache/authentication.mdx index 7096228..9718287 100644 --- a/content/cache/authentication.mdx +++ b/content/cache/authentication.mdx @@ -4,7 +4,9 @@ ogTitle: Authentication for Depot remote caching description: Learn how to authenticate with Depot remote caching --- -Depot Cache supports authenticating with user tokens and organization tokens. Additionally, [Depot-managed GitHub Actions runners](/docs/github-actions/overview) are pre-configured with single-use job tokens. +Depot Cache supports authenticating with **user** tokens and **organization** tokens. Additionally, [Depot-managed GitHub Actions runners](/docs/github-actions/overview) are pre-configured with single-use job tokens. + +Project tokens are **not** supported for Depot cache. ## Token types diff --git a/content/cli/reference.mdx b/content/cli/reference.mdx index d05d969..c8cf29b 100644 --- a/content/cli/reference.mdx +++ b/content/cli/reference.mdx @@ -274,15 +274,15 @@ depot cache reset --project 12345678910 ### `depot claude` -Run Claude Code with automatic session saving and resuming via Depot. Sessions are stored by Depot and can be resumed by session ID, allowing you to collaborate on any session in your organization across any environment. +Run Claude Code in remote agent sandboxes backed by Depot with automatic session & file system saving and resuming. Sessions are stored by Depot and can be resumed by session ID, allowing you to collaborate on any session in your organization across any environment. -Using the `--resume` flag allows you to resume any session by its ID, which can be useful if you want to continue a session from another environment like in CI or give the session to a teammate to continue working on. +By default, Claude Code runs in a remote sandbox environment. -All flags not recognized by `depot` are passed directly through to the Claude CLI. This includes Claude flags like `-p`, `--model`, etc. +Note: All flags not recognized by `depot` are passed directly through to the Claude CLI. This includes Claude flags like `-p`, `--model`, etc. **Example** -Start a new Claude session with a custom ID: +Start a new Claude Code session with a custom ID: ```shell depot claude --session-id feature-auth-redesign @@ -294,6 +294,29 @@ Resume an existing session: depot claude --resume feature-auth-redesign ``` +Run Claude Code locally instead of in a sandbox: + +Note: This will only persist the Claude Code session information up to Depot, but not execute in a remote sandbox. + +```shell +depot claude --local --session-id local-development +``` + +Work with a Git repository in the sandbox: + +```shell +depot claude --repository https://github.com/user/repo.git --branch main --session-id repo-work +``` + +Use a private repository with authentication: + +Note: You can use the `--git-secret` flag to specify a secret containing your Git credentials, or use the `Depot Code` app installed in your GitHub organization. + +```shell +depot claude secrets add GITHUB_TOKEN +depot claude --repository https://github.com/org/private-repo.git --git-secret GITHUB_TOKEN +``` + Mix Depot flags with Claude flags: ```shell @@ -312,11 +335,16 @@ cat code.py | depot claude -p "review this code" --session-id code-review | Name | Description | | ---- | ----------- | | `help` | Show help for claude command | -| `org` | Organization ID (required when user is a member of multiple organizations) | +| `local` | Run Claude locally instead of in a remote sandbox | +| `org` | Organization ID (optional) | | `output` | Output format (json, csv) | +| `repository` | Git repository URL for remote context (format: https://github.com/user/repo.git) | +| `branch` | Git branch to use (defaults to main) | +| `git-secret` | Secret name containing Git credentials for private repositories if not using Depot Code app | | `resume` | Resume a session by ID | | `session-id` | Custom session ID for saving | | `token` | Depot API token | +| `wait` | Wait for the remote Claude session to complete (by default exits after starting) | {/* */} ### `depot claude list-sessions` @@ -348,6 +376,55 @@ depot claude list-sessions --output json | `token` | Depot API token | {/* */} +### `depot claude secrets` + +Manage secrets that can be used in Claude sandboxes. Secrets are stored securely and scoped to your organization, available as environment variables in sandbox sessions. + +#### `depot claude secrets add` + +Add a new secret to your organization. You'll be prompted to enter the secret value securely. + +**Example** + +```shell +# Add a secret interactively +depot claude secrets add GITHUB_TOKEN + +# Add a secret with value (use with caution) +depot claude secrets add API_KEY --value "secret-value" +``` + +#### `depot claude secrets list` + +List all secrets in your organization. Note that secret values are never displayed. + +**Example** + +```shell +depot claude secrets list +``` + +#### `depot claude secrets remove` + +Remove a secret from your organization. + +**Example** + +```shell +depot claude secrets remove GITHUB_TOKEN +``` + +#### Flags for `claude secrets` + +{/* */} +| Name | Description | +| ---- | ----------- | +| `help` | Show help for secrets command | +| `org` | Organization ID | +| `token` | Depot API token | +| `value` | Secret value (for add command only, prompted if not provided) | +{/* */} + ### `depot gocache` Configure Go tools to use Depot Cache. The Go tools will use the remote cache service to store and retrieve build artifacts. @@ -505,6 +582,36 @@ Additional flags that can be used with this command. | `token` | Depot token | {/* */} +### `depot projects delete` + +Delete a project from your Depot organization. This permanently removes the project and all associated build data. + +**Note: Only organization admins can delete projects.** + +**Example** + +```shell +depot projects delete +``` + +You can also use the `--project-id` flag to specify the project ID: + +```shell +depot projects delete --project-id +``` + +#### Flags for `delete` + +Additional flags that can be used with this command. + +{/* */} +| Name | Description | +| ---- | ----------- | +| `project-id` | Depot project ID | +| `yes` | Confirm deletion, skip the confirmation prompt | +| `token` | Depot token | +{/* */} + ### `depot projects list` Display an interactive listing of current Depot projects. Selecting a specific project will display the latest builds. diff --git a/content/container-builds/quickstart.mdx b/content/container-builds/quickstart.mdx index 8106496..789ee2c 100644 --- a/content/container-builds/quickstart.mdx +++ b/content/container-builds/quickstart.mdx @@ -8,7 +8,7 @@ Below is a guide to leveraging Depot for up to 40x faster container image builds We also offer managed GitHub Actions Runners with 10x faster caching. You can get started with our runners in our [GitHub Actions Overview docs](/docs/github-actions/overview). -## Installing the CLI +## Installing the `depot` CLI For Mac, you can install the CLI with Homebrew: @@ -23,12 +23,12 @@ For Linux, you can install the CLI with [our installation script](https://depot. curl -L https://depot.dev/install-cli.sh | sh # Install a specific version -curl -L https://depot.dev/install-cli.sh | sh -s 2.45.5 +curl -L https://depot.dev/install-cli.sh | sh -s 2.96.2 ``` For all other platforms, you can download the binary directly from [the latest release](https://github.com/depot/cli/releases). -## Creating an organization +## Creating a Depot organization Organizations are the top level entity in Depot. They typically represent a single company or team. Billing details are attached to an organization.