Legacy CLI deploy

Reference for existing Deep Agents CLI deployment users.

deepagents deploy is a legacy beta CLI deployment path for users already using Deep Agents Deploy. It takes your agent configuration and files and deploys them together as a LangSmith Deployment.

For new deployments, use Managed Deep Agents. Managed Deep Agents is in private preview and provides an API-first hosted runtime for creating, running, and operating deep agents. Join the waitlist to request access.

LangSmith Deployments are horizontally scalable servers with 30+ endpoints including MCP, A2A, Agent Protocol, human-in-the-loop, and memory APIs. Built on open standards:

• Open source harness: MIT licensed, available for Python and TypeScript
• AGENTS.md: open standard for agent instructions
• Agent Skills: open standard for agent knowledge and actions
• Any model, any sandbox: no provider lock-in
• Open protocols: MCP, A2A, Agent Protocol
• Self-hostable: LangSmith Deployments can be self-hosted so memory stays in your infrastructure

For multi-tenancy, authentication, memory and sandbox scoping, guardrails, and frontend integration beyond this CLI walkthrough, see Going to production.

Compare to Claude Managed Agents

	Deep Agents Deploy	Claude Managed Agents
Model support	OpenAI, Anthropic, Google, Bedrock, Azure, Fireworks, Baseten, OpenRouter, many more	Anthropic only
Harness	Open source (MIT)	Proprietary, closed source
Sandbox	LangSmith, Daytona, Modal, Runloop, or custom	Built in
MCP support	✅	✅
Skill support	✅	✅
AGENTS.md support	✅	❌
Agent endpoints	MCP, A2A, Agent Protocol	Proprietary
Self hosting	✅	❌

Install

Install the CLI or run directly with uvx:

uv

uv tool install deepagents-cli

uvx deepagents-cli deploy

Usage

deepagents init [name] [--force]                                             # scaffold a new project
deepagents dev  [--config deepagents.toml] [--port 2024] [--allow-blocking]  # bundle and run locally
deepagents deploy [--config deepagents.toml] [--dry-run]                     # bundle and deploy

By default, deepagents deploy looks for deepagents.toml in the current directory. Pass --config to use a different path:

deepagents deploy --config path/to/deepagents.toml

deepagents deploy fully rebuilds and creates a new revision on every invocation. Use deepagents dev for local iteration.

deepagents init

Scaffold a new agent project:

deepagents init my-agent

This creates the following files:

File	Purpose
deepagents.toml	Agent config — name, model, optional sandbox
AGENTS.md	System prompt loaded at session start
.env	API key template (GOOGLE_API_KEY, LANGSMITH_API_KEY, etc.)
mcp.json	MCP server configuration (empty by default)
skills/	Directory for Agent Skills, with an example review skill

After init, edit your project files and run deepagents deploy.

Setup

The deploy command uses the following project layout. Place the following files alongside your deepagents.toml and they are automatically discovered and deployed:

my-agent/
├── deepagents.toml
├── AGENTS.md
├── .env
├── mcp.json
├── skills/
│   ├── code-review/
│   │   └── SKILL.md
│   └── data-analysis/
│       └── SKILL.md
├── subagents/
│   └── researcher/
│       ├── deepagents.toml
│       └── AGENTS.md
└── user/
    └── AGENTS.md

File	Description
deepagents.toml	Required. Configures the agent’s identity, authentication, sandbox environment, and the deployment of a prebuilt frontend Reach chat UI.
AGENTS.md	Required. Memory for the agent. Provides persistent context (project conventions, instructions, preferences) that is always loaded at startup. Read-only at runtime.
skills/	Optional. Directory of skill definitions that provide specialized workflows and domain knowledge. Each subdirectory should contain a SKILL.md file. Read-only at runtime. Dotfiles are skipped when uploading.
user/	Optional. Per-user writable memory. If an AGENTS.md template is present in the user folder, the agents seeds the template per user (if the folder is empty the agents creates an empty AGENTS.md). The agent can read from and write to this file. Preloaded into the agent’s context via the memory middleware.
mcp.json	Optional. MCP tools (HTTP/SSE). If mcp.json exists, it is included in the deployment and langchain-mcp-adapters is added as a dependency. See MCP (LangChain) for more information. mcp.json must only contain servers using http or sse transports. Servers using stdio transport are not supported in deployed environments because there is no local process to spawn. Convert stdio servers to HTTP or SSE before deploying.
subagents/	Optional. Specialized Subagents the main agent can delegate to. Each subdirectory must contain a deepagents.toml, AGENTS.md, and optionally a skills folder. Auto-discovered at bundle time.
.env	Optional. Environment variables (API keys, secrets). Placed alongside deepagents.toml at the project root. See Environment variables.

Configuration file

deepagents.toml configures the agent’s identity and sandbox environment. Only the [agent] section is required. The [sandbox] section is optional and defaults to no sandbox.

Field	Type	Description
[agent]	Object	Required. Core agent identity (name and model).
[sandbox]	Object	Optional. Configure the isolated execution environment where the agent runs code. Defaults to no sandbox.
[auth]	Object	Optional. Configure authentication on the deployed agent. Required when [frontend].enabled = true.
[frontend]	Object	Optional. Enable and configure the built-in chat UI frontend.

[agent]

Configure the core agent identity:

deepagents.toml

[agent]
name = "research-assistant"
description = "Researches market trends, competitors, and target audiences"
model = "google_genai:gemini-3.1-pro-preview"

Field	Type	Description
name	string	Required. Name for the deployed agent. Used as the assistant identifier in LangSmith.
description	string	Optional. Human-readable description of what the agent does.
model	string	Optional. Model identifier in provider:model format. See supported models. The provider: prefix in the model field determines the required langchain-* package (e.g., google_genai -> langchain-google-genai) which is automatically included in the deployment. This includes models specified in subagent configs. Defaults to a credential-based model if omitted (tries openai:gpt-5.2, then anthropic:claude-sonnet-4-6, then google_genai:gemini-3.1-pro-preview, then google_vertexai:gemini-3.1-pro-preview, then nvidia:nvidia/nemotron-3-super-120b-a12b).

[sandbox]

Configure the isolated execution environment where the agent runs code. Sandboxes provide a container with a filesystem and shell access, so untrusted code cannot affect the host. For supported providers and advanced sandbox configuration, see sandboxes. For the production tradeoffs between thread-scoped and assistant-scoped sandboxes, file transfers, and secret management, see Going to production: Sandboxes.

deepagents.toml

[sandbox]
provider = "langsmith"
template = "coding-agent"
image = "python:3.12"

Field	Type	Description
provider	string	Optional. Sandbox provider. Supported values: "none", "daytona", "modal", "runloop", "langsmith" (private beta). The relevant partner package is automatically included in the deployment. See sandbox integrations for provider details. Defaults to "none". When omitted or set to provider = "none", the sandbox is disabled.
template	string	Optional. Provider-specific template name for the sandbox environment. Defaults to "deepagents-deploy".
image	string	Optional. Base Docker image for the sandbox container. Defaults to "python:3".
scope	string	Optional. Sandbox lifecycle scope. Defaults to "thread". "thread" creates one sandbox per conversation. "assistant" shares a single sandbox across all conversations for the same assistant.

Scope behavior:

• "thread" (default): Each conversation gets its own sandbox. Different threads get different sandboxes, but the same thread reuses its sandbox across turns. Use this when each conversation should start with a clean environment.
• "assistant": All conversations share one sandbox. Files, installed packages, and other state persist across conversations. Use this when the agent maintains a long-lived workspace like a cloned repo.

[auth]

Add an [auth] section to configure authentication on the deployed agent. [auth] is required when [frontend].enabled = true; otherwise it is optional (without it, LangSmith Deployment’s default x-api-key requirement applies). For background on multi-tenant authentication patterns—including team-level RBAC and forwarding end-user credentials to external APIs—see Going to production: Multi-tenancy.

deepagents.toml

[agent]
name = "my-agent"
model = "google-genai:gemini-3.1-pro-preview"

[auth]
provider = "supabase"   # supabase | clerk | anonymous

Field	Type	Description
provider	string	Required. Auth provider. Supported values: "supabase", "clerk", "anonymous".

Pick one of three providers:

• Clerk ([auth] provider = "clerk") — per-user real authentication. Each user signs in; threads and memory are scoped per user.
• Supabase ([auth] provider = "supabase") — per-user real authentication. Same per-user scoping as Clerk.
• Anonymous ([auth] provider = "anonymous") — the bundler ships a permissive auth handler that overrides LangSmith Deployment’s default x-api-key requirement so the frontend can reach /threads, which means anyone with the deploy URL can call the API. The frontend assigns each browser a UUID cookie and filters the thread picker by it (UX-only scoping, not security). The CLI requires an interactive y/N confirmation before pushing.

Depending on your provider, add the following credentials to your .env alongside your other credentials:

Provider	Required env vars
supabase	SUPABASE_URL, SUPABASE_PUBLISHABLE_DEFAULT_KEY
clerk	CLERK_SECRET_KEY
anonymous	None

Runtime behavior:

• Unauthenticated requests return 401.
• On success, the authenticated user’s identity is injected into config.configurable.langgraph_auth_user_id.
• All resources (threads, runs, store) are automatically scoped per user via metadata.owner.
• LangSmith Studio bypasses auth for local development.

For information on how to authenticate, see Authentication.

[frontend]

Frontend deployment requires deepagents-cli>=0.0.43.

Optionally enable [frontend] to ship a prebuilt React chat UI alongside your agent on the same deployment. The frontend is mounted at /app on your deployment URL; your LangGraph API stays at the root (/threads, /runs, /assistants). The frontend provides:

• Streaming chat with the agent
• Thread picker with auto-generated titles from the first user message
• Real-time todos, files, and subagent activity panels that reflect your deep agent’s live graph state
• Light/dark theme toggle that follows OS preference on first load and persists after
• (Clerk / Supabase only) Sign-in / sign-up / sign-out flows — Clerk ships its full widget (social logins, password reset); Supabase ships email/password with a built-in password reset flow

Every frontend uses one of three authentication providers — Clerk, Supabase, or anonymous (see [auth]).

deepagents.toml

[agent]
name = "my-agent"
model = "anthropic:claude-sonnet-4-6"

[auth]
provider = "supabase"   # or "clerk"

[frontend]
enabled = true
app_name = "My Agent"
subtitle = "Your AI research assistant"
prompts = [
  "Summarize this paper",
  "Find related work",
  "Draft an outline",
]

Field	Type	Description
enabled	boolean	Optional. If true, bundle the default chat UI into the deployment. Defaults to false.
app_name	string	Optional. Display name shown in the UI header and browser tab. Defaults to [agent].name.
subtitle	string	Optional. Subtitle shown under the app name in the header and on the empty-state hero. Use it to describe what the agent does. Defaults to "Your deep agent, deployed.".
prompts	string[]	Optional. Suggestion chips shown on the empty-state when there are no messages. Defaults to a generic research-themed set; override to tailor the chips to your agent.

Environment variables:

The frontend reuses most of what [auth] already requires. Only Clerk needs one additional browser-facing key.

Provider	Additional var
supabase	None — reuses SUPABASE_URL and SUPABASE_PUBLISHABLE_DEFAULT_KEY from [auth]
clerk	CLERK_PUBLISHABLE_KEY (browser-facing publishable key; distinct from CLERK_SECRET_KEY)

Post-deploy setup:

After deploying, add your deployment URL to your auth provider’s dashboard so auth redirects land back in the app. This is a one-time step per deployment URL.

• Clerk: Dashboard → your application → Domains → add your deployment host (e.g. clerk-abc.us.langgraph.app). Clerk development instances auto-whitelist localhost; production deployment URLs need explicit whitelisting.
• Supabase: Dashboard → Authentication → URL Configuration → add https://<your-deployment>/app/** to Redirect URLs. Without this, password-reset and email-confirmation links won’t route back to your app.

Environment variables

Place a .env file alongside deepagents.toml with your API keys. For sandbox code that needs to call external APIs without leaking credentials, prefer the sandbox auth proxy over baking secrets into .env.

# Required — model provider keys
ANTHROPIC_API_KEY=sk-...
OPENAI_API_KEY=sk-...
# ...etc.

# Required for deploy and LangSmith sandbox
LANGSMITH_API_KEY=lsv2_...

# Optional — sandbox provider keys
DAYTONA_API_KEY=...
MODAL_TOKEN_ID=...
MODAL_TOKEN_SECRET=...
RUNLOOP_API_KEY=...

# Required if [auth] provider = "supabase"
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_PUBLISHABLE_DEFAULT_KEY=eyJhbGc...

# Required if [auth] provider = "clerk"
CLERK_SECRET_KEY=sk_test_...

# Required if [frontend].enabled = true AND [auth] provider = "clerk"
CLERK_PUBLISHABLE_KEY=pk_test_...

Authentication

The runtime auth posture depends on [auth]:

• [auth] provider = "supabase" or "clerk" — per-user real authentication. Pass the user’s auth-provider token in the Authorization header.
• [auth] provider = "anonymous" — the bundler ships a permissive auth handler. The API is open to anyone with the deploy URL. No header required. (Required when shipping [frontend] without real per-user auth.)
• No [auth] section — the deploy falls back to LangSmith Deployment’s default x-api-key requirement. Pass your LangSmith API key in the x-api-key header. Only valid when [frontend].enabled is false or unset.

When [auth] is configured for supabase or clerk, pass the token from your auth provider in the Authorization header:

curl

curl -X POST https://your-deployment-url/threads \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"metadata": {}}'

Python (langgraph-sdk)

from langgraph_sdk import get_client

client = get_client(
    url="https://your-deployment-url",
    headers={"Authorization": "Bearer YOUR_ACCESS_TOKEN"},
)

thread = await client.threads.create()

Provider	Where to get the token
Supabase	Supabase session access_token from supabase.auth.getSession()
Clerk	Clerk session token from getToken()

Each user’s threads and memory are isolated automatically—User B cannot see User A’s threads.

Deployment endpoints

The deployed server exposes:

• MCP: call your agent as a tool from other agents
• A2A: multi-agent orchestration via A2A protocol
• Agent Protocol: standard API for building UIs
• Human-in-the-loop: approval gates for sensitive actions
• Memory: short-term and long-term memory access

User Memory

User memory gives each user their own writable AGENTS.md that persists across conversations. This is the CLI’s built-in equivalent of the user-scoped memory pattern described in Going to production: Memory. To enable it, create a user/ directory at your project root:

user/
└── AGENTS.md          # optional — seeded as empty if not provided

If the user/ directory exists (even if empty), every user gets their own AGENTS.md at /memories/user/AGENTS.md. If you provide user/AGENTS.md, its contents are used as the initial template; otherwise an empty file is seeded.

At runtime, user memory is scoped per user via custom auth (runtime.server_info.user.identity). The first time a user interacts with the agent, their namespace is seeded with the template. Subsequent interactions reuse the existing file — the agent’s edits persist, and redeployments never overwrite user data.

How it works

1. Bundle time — the bundler reads user/AGENTS.md (or uses an empty string) and includes it in the seed payload.
2. Runtime (first access) — when the agent sees a user_id for the first time, it writes the AGENTS.md template to the store under that user’s namespace. Existing entries are never overwritten.
3. Preloaded — the user AGENTS.md is passed to the memory middleware, so the agent sees its contents in context at the start of every conversation.
4. Writable — the agent can update it using the edit_file tool. The shared AGENTS.md file and skills folder are read-only.

Permissions

Path	Writable	Scope
/memories/AGENTS.md	No	Shared (assistant-scoped)
/memories/skills/**	No	Shared (assistant-scoped)
/memories/user/**	Yes	Per-user (user_id-scoped)
/memories/subagents/<name>/**	By subagent only	Per-subagent (isolated)

User identity

The user_id is resolved from custom auth via runtime.user.identity. The platform injects the authenticated user’s identity automatically — no need to pass it through configurable. If no authenticated user is present, user memory features are gracefully skipped for that invocation.

Subagents

Subagents let the main agent delegate specialized tasks to isolated child agents. Each subagent has its own system prompt, optional skills, and optional MCP tools. The main agent receives a task tool that dispatches work to subagents by name.

For background on why subagents are useful and how they work at the SDK level, see Subagents.

Directory structure

Create a subagents/ directory at your project root. Each subdirectory is a subagent:

my-agent/
├── deepagents.toml
├── AGENTS.md
└── subagents/
    ├── researcher/
    │   ├── deepagents.toml       # name, description, optional model override
    │   ├── AGENTS.md             # subagent system prompt
    │   ├── skills/               # optional — subagent-specific skills
    │   │   └── analyze-market/
    │   │       └── SKILL.md
    │   └── mcp.json              # optional — HTTP/SSE MCP tools
    └── writer/
        ├── deepagents.toml
        └── AGENTS.md

Each subagent subdirectory must contain:

File	Purpose
deepagents.toml	Subagent config with [agent].name and [agent].description
AGENTS.md	System prompt for the subagent

Each subagent subdirectory may contain:

File	Purpose
skills/	Subagent-specific skills (with SKILL.md files)
mcp.json	MCP server configuration (HTTP/SSE only; stdio is rejected)

Subagent configuration

subagents/researcher/deepagents.toml

[agent]
name = "researcher"
description = "Researches market trends, competitors, and target audiences"
model = "google_genai:gemini-3.1-pro-preview"

Field	Type	Description
name	string	Required. Unique identifier for the subagent. Must be unique across all subagents.
description	string	Required. What this subagent does. The main agent uses this to decide when to delegate. Must be non-empty.
model	string	Optional. Model override in provider:model format. Omit to inherit the main agent’s model.

Inheritance

Subagents inherit some properties from the main agent by default:

Property	Inherited	Notes
Model	Yes	Override with model in the subagent’s deepagents.toml
Tools	Yes	Override by adding mcp.json to the subagent directory
Skills	No	Declare explicitly in the subagent’s own skills/ directory

Memory isolation

Each subagent gets a dedicated, isolated memory namespace at /memories/subagents/<name>/. The subagent’s AGENTS.md and skills are seeded into this namespace at deploy time.

Path	Main agent	Subagent
/memories/AGENTS.md	Read	No access
/memories/skills/**	Read	No access
/memories/user/**	Read + Write	No access
/memories/subagents/<name>/**	Read	Read + Write

Example

A go-to-market agent that delegates research to a specialized subagent:

deepagents.toml

[agent]
name = "gtm-strategist"
model = "google_genai:gemini-3.1-pro-preview"

subagents/researcher/deepagents.toml

[agent]
name = "researcher"
description = "Researches market trends, competitors, and target audiences to inform GTM strategy"
model = "google_genai:gemini-3.1-pro-preview"

subagents/researcher/AGENTS.md

# Market Researcher

You are a market research specialist. Your job is to gather and synthesize
market data to support go-to-market decisions.

## Focus Areas
- Market sizing: TAM, SAM, SOM estimates
- Competitor analysis: product positioning, pricing, market share
- Audience segmentation: demographics, psychographics, buying behavior

Limitations

• MCP: HTTP/SSE only. Stdio transports are rejected at bundle time.
• No custom Python tools. Use MCP servers to expose custom tool logic.

If your agent needs custom tools, custom middleware (rate limiting, retries, PII redaction), or production patterns the CLI doesn’t expose, deploy directly via LangSmith Deployments and follow Going to production for the underlying patterns (guardrails, durability, scoped memory).

Examples

A content writing agent with per-user preferences that the agent can update:

deepagents.toml

[agent]
name = "deepagents-deploy-content-writer"
model = "google_genai:gemini-3.1-pro-preview"

my-content-writer/
├── deepagents.toml
├── AGENTS.md
├── skills/
│   ├── blog-post/SKILL.md
│   └── social-media/SKILL.md
└── user/
    └── AGENTS.md          # writable — agent learns user preferences

A coding agent with a LangSmith sandbox for running code:

deepagents.toml

[agent]
name = "deepagents-deploy-coding-agent"
model = "google_genai:gemini-3.1-pro-preview"

[sandbox]
provider = "langsmith"
template = "coding-agent"
image = "python:3.12"

A GTM strategy agent that delegates research to a subagent:

my-gtm-agent/
├── deepagents.toml
├── AGENTS.md
├── skills/
│   └── competitor-analysis/
│       └── SKILL.md
└── subagents/
    └── market-researcher/
        ├── deepagents.toml
        ├── AGENTS.md
        └── skills/
            └── analyze-market/
                └── SKILL.md

A lightweight internal-demo agent with the bundled UI in anonymous mode (no signup, no infrastructure):

deepagents.toml

[agent]
name = "internal-demo"
model = "anthropic:claude-sonnet-4-6"

[auth]
provider = "anonymous"   # API open to anyone with the URL — confirm at deploy time

[frontend]
enabled = true

---

Connect these docs to Claude, VSCode, and more via MCP for real-time answers.

Edit this page on GitHub or file an issue.