Skip to main content

​
Step 1: Create Your Agent

Scaffold a new agent project:
The CLI generates a TypeScript project directory with your agent code, circuit.toml config, a .gitignore, and installed dependencies. You do not need to log in until you use account-backed commands such as upload or hosted dev runs. Navigate into the project.
Your generated agent code looks like this:

​
Step 2: Test Locally

The fastest loop needs no Circuit account, backend, wallet, or funding:
Dry run executes your agent without signing or broadcasting transactions. Provider-backed reads use the network. Each invocation receives an empty allocation; journaled writes do not update balances or positions. Use the hosted engine to test allocation-dependent behavior against a running session. The agent’s agent.log() output streams to stdout:
To sign and broadcast from a local wallet, create it and authorize local signing:
To test against the hosted engine instead, name an owned Circuit wallet: circuit run --hosted engine --wallet <name-or-address>. See the Development reference.

​
Step 3: Upload

If your agent needs API keys or other secrets, create a local .env file before uploading:
circuit upload 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 Uploading → Environment Variables. This uploads your agent to Circuit. Once uploaded, users can find and run it through the Circuit app.