Quickstart

The fastest way to create, test, and deploy a Circuit agent. This guide walks you through installing the CLI, setting up a project, writing your first agent, and deploying to production.

Prerequisites

• TypeScript: Bun ≥ 1.0 (npm will not work)

• Python: Python ≥ 3.12

Installation

bun install -g @circuitorg/agent-cli

Verify Installation:

circuit --version

Getting Started

# Authenticate your CLI
# Opens a browser window for you to log in
circuit login

# Create a new agent directory
# Prompts you for a language (TypeScript or Python) and name
circuit init

# Navigate into your agent folder
# This folder contains index.ts (or main.py) and configuration files
cd <agent-name>

# Install dependencies
bun install    # for TypeScript
uv sync        # for Python

# Test your agent locally by running your agent's logic in a local sandbox env
# It creates a temporary session wallet and executes your `run()` function
circuit run

# Publish to production
# This pushes your agent to Circuit Cloud so it can be scheduled or triggered automatically
circuit publish

Project Structure

After circuit init, your agent folder will include:

File	Purpose
.circuit.toml	Agent configuration (network, assets, metadata)
index.ts / main.py	Main agent logic
package.json / pyproject.toml	Dependency definitions

Your agent defines two commands:

• run: executes agent logic

• unwind: handles cleanup when the agent unwinds

Next Steps

• Learn how to use circuit run, circuit unwind, and circuit publish in the CLI Reference

• Explore the TypeScript SDK or Python SDK for deeper API capabilities