Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.circuit.org/llms.txt

Use this file to discover all available pages before exploring further.

​
Step 1: Create Your Agent

Scaffold a new agent project: 
circuit new
The CLI prompts you for a template, a language (TypeScript or Python), and an agent name, then generates a project directory with your agent code, circuit.toml config, and dependencies. You do not need to log in until you use account-backed commands such as publish or hosted wallet actions. Install dependencies and navigate into the project: 
cd agent-name && bun install
Your generated agent code looks like this: 
from agent_sdk import Agent, AgentContext

def run(agent: AgentContext) -> None:
    agent.log("Hello from my agent!")

agent = Agent(run_function=run)

handler = agent.get_handler()

if __name__ == "__main__":
    agent.run()

​
Step 2: Test Locally

Add a wallet to the local encrypted vault (one-time setup), then run: 
circuit wallet add        # interactive: pick generate / import / hosted
circuit dev run
circuit wallet add stores the key in ~/.config/circuit/keystore.enc, encrypted with a password you choose. The dev run command prompts for the password, picks the matching wallet for your agent’s chain, and invokes the agent in-process. The CLI imports your agent module and invokes its runFunction directly with local primitives. You should see output like: 
ℹ Running agent locally — logs streaming to stderr, dataDir=.circuit
  Hello from my agent!
✓ Run completed.
To test against the hosted runtime instead (real wallet selection, sessions, policy), use circuit dev run --hosted — see the Development reference for details.

​
Step 3: Publish

circuit login
circuit publish
If your agent needs API keys or other secrets, create a local .env file before publishing: 
YOUR_API_KEY=...
circuit publish reads .env from the agent root, then applies any --env KEY=VALUE overrides, encrypts those values at rest, and injects them into your deployed agent runtime as normal environment variables. For more details, see Publishing → Environment Variables. This uploads your agent to Circuit. Once published, users can find and run it through the Circuit app.