Build & Deploy

Project layout

21st-agents/
├── package.json
├── agents/
│   └── my-agent/
│       ├── index.ts          # or index.js
│       └── template/
│           └── ...

Keep each deployable agent in its own folder under agents/ so related files can live next to the entry point. JavaScript and TypeScript projects use the usual package.json.

Project requirements

Part of the deploy pipeline runs locally, so your project and machine need to satisfy a few requirements before the CLI can build the agent.

platform: "node"
target: "node22"

Agent configuration

The agent file is where all your configuration lives — model, runtime, system prompt, tools, and agent behavior.

import { agent, tool } from "@21st-sdk/agent"
import { z } from "zod"

export default agent({
  // Model and runtime
  model: "claude-sonnet-4-6",
  runtime: "claude-code",

  // Instructions
  systemPrompt: "You are a helpful coding assistant.",

  // Execution limits
  permissionMode: "default",
  maxTurns: 50,

  // Custom tools
  tools: {
    greet: tool({
      description: "Greet a user",
      inputSchema: z.object({ name: z.string() }),
      execute: async ({ name }) => ({
        content: [{ type: "text", text: `Hello, ${name}!` }],
      }),
    }),
  },

  // Lifecycle hooks
  onFinish: async ({ result }) => {
    console.log("Done:", result)
  },
})

Entry point

When you run @21st-sdk/cli deploy, the CLI scans the agents/ directory.

The entrypoint must be agents/<slug>/index.ts or agents/<slug>/index.js. It must export a default value returned by agent().

Dependencies

For JavaScript and TypeScript agents, the minimum setup is:

{
  "name": "my-agent",
  "type": "module",
  "dependencies": {
    "@21st-sdk/agent": "latest",
    "zod": "^3.24"
  }
}

CLI reference

The CLI is available as an npm package. Run it with npx or install globally:

# Run directly with npx
npx @21st-sdk/cli login
npx @21st-sdk/cli deploy

# Or install globally
npm install -g @21st-sdk/cli
@21st-sdk/cli login
@21st-sdk/cli deploy

Login

Authenticate with your API key. Get one from the dashboard.

$ @21st-sdk/cli login
  Enter your API key: an_sk_...
  Authenticated as John (team: my-team)

Credentials are saved to ~/.an/credentials. You only need to log in once.

Deploy

# deploy every agent under agents/
npx @21st-sdk/cli deploy

# deploy only one agent
npx @21st-sdk/cli deploy --agent my-agent

Use --agent <slug> when you only want to redeploy one agent from the agents/ directory.

How deploy works

When you run @21st-sdk/cli deploy, four things happen:

Environment variables

Set environment variables from the dashboard. Defined tools can read them via process.env in the runtime process inside the E2B sandbox. They are not exposed to the isolated agent process as ordinary env vars.

Project metadata

Current CLI deploys do not require a local project metadata file. If you still have an old .an/project.json from an older version, you can remove it.

Redeploying

Run @21st-sdk/cli deploy again to update your agent, or use @21st-sdk/cli deploy --agent my-agent to update just one slug. The CLI:

1. Bundles your updated code
2. Kills the old sandbox
3. Creates a fresh sandbox with the new bundle
4. Updates the agent config in the database

The agent URL stays the same. Active chat sessions may be interrupted during redeploy.

What lives where

Agents are code-first. Agent behavior lives entirely in your code. The dashboard is for monitoring and managing environment variables.