Skip to main content

​
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 installed dependencies. You do not need to log in until you use account-backed commands such as publish or hosted dev runs. Navigate into the project. 
cd agent-name
Your generated agent code looks like this: 
from circuit_sdk import AgentContext

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

​
Step 2: Test Locally

Add a wallet to the local encrypted vault (one-time setup), authorize local signing, then run: 
circuit wallet add         # interactive: pick generate / import
circuit auth login --local # mint a local signing session (no browser/account)
circuit run
circuit wallet add stores the key in ~/.circuit/local/keystore, sealed under a local identity that is auto-created on first use — there is no password. circuit auth login --local mints a purely-local session permit that authorizes signing; circuit run consumes it, picks the matching wallet for your agent’s chain, and invokes the agent in-process. The CLI imports your agent module and invokes its run function directly with local primitives. The agent’s agent.log() output streams to stdout: 
[agent] Hello from my agent!
To test against the hosted execution instead (real wallet selection, sessions, policy), use circuit run --hosted execution — see the Development reference for details.

​
Step 3: Publish

circuit auth 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 --var KEY=VALUE overrides, encrypts those values at rest, and injects them into your agent’s hosted 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.