Skip to main content

​
Upload Agent

Upload your agent to Circuit infrastructure.
Flags:
  • --path <path>: Upload from a specific agent directory instead of the current directory.
  • --var KEY=VALUE: Override/add env vars for this upload (repeatable).
  • --enable=true|false: Set the agent’s visibility while uploading - true shows it in the app, false hides it and pauses its running sessions. Omit to leave the agent’s enabled state untouched.
What happens:
  1. Validates your project and circuit.toml (including startingAsset and deployment-region rules). A root-level DESCRIPTION.md (the agent’s prose plan, maintained by the agent builder) is optional; when present its content is sent as the agent’s description metadata during upload
  2. Collects project files based on exclusion patterns (DESCRIPTION.proposed.md, a pending builder proposal, is never uploaded)
  3. Reads environment variables from .env in the agent root (if present)
  4. Applies --var KEY=VALUE overrides (CLI flags take precedence)
  5. Builds a deterministic deploy bundle and calculates its SHA-256 hash
  6. Uploads code to Circuit infrastructure
  7. Encrypts env vars at rest and stores them separately from code artifacts
  8. Polls upload status until complete
  9. Returns the agent ID, bundle content hash, whether this was its first publish, and a link to the agent page
Important: Your agent’s agentId in circuit.toml is its permanent identity. Uploads replace that agent’s current runnable content; renaming the agent keeps its sessions and other state attached to the same id. See Agent Identity for details. Requirements:
  • Must be authenticated (circuit auth login)
  • Valid circuit.toml configuration
  • TypeScript projects must include index.ts, package.json, and bun.lock
  • Python projects must include main.py and pyproject.toml
  • Dependencies installed locally before uploading
For TypeScript projects, run bun install before uploading so bun.lock is present and up to date. For Python projects, run uv sync after editing dependencies so local checks and lockfiles match your project.

​
Disabling and Enabling an Agent

Take an uploaded agent down from the app without deleting it, then bring it back. This is a flag on upload, so you upload the current code and set its visibility in one step - handy in a pipeline to pull an agent from circulation on demand.
What --enable=false does:
  • Hides the agent from the app - it drops out of the agent list, the popular/related sections, its detail page, and the leaderboard. You (the creator) and admins can still reach it; turn on the Show disabled agents account setting to keep it in your own agent list.
  • Pauses every running session of the agent, across all users. No funds are moved - pausing only halts trading, and each session owner can still Stop or Unwind their own session from its card.
  • Blocks new sessions, resumes, and manual runs while the agent is disabled.
What --enable=true does:
  • Clears the disabled state so the agent is discoverable again. Previously paused sessions are not auto-resumed - each owner resumes their own.
Both target the agent named in your circuit.toml and require authentication (circuit auth login). The toggle is idempotent - re-uploading with the same value is a no-op on an agent already in that state.

​
Visibility

Newly uploaded agents are public by link, by default. As soon as an upload finishes, anyone with the agent’s detail-page link can view and start it - there is no approval step. circuit upload prints the link, and the agent detail page has a Share button. The main catalog (the Home feed) is curated separately: agents appear there once Circuit features them. Until then, your agent is reachable by direct link only. To make an agent private (visible only to you), use Make private in the agent page’s actions menu - no effect on running sessions. To take it out of circulation entirely, use --enable=false (see Disabling and Enabling an Agent). Runnable content: a successful upload replaces the agent’s current runnable content for new and live sessions. A failed upload leaves the current content unchanged. File exclusion: The CLI automatically excludes these patterns from uploads:
  • Version control: .git/**, .svn/**
  • Dependencies: node_modules/**, dist/**, venv/**, __pycache__/**
  • Secrets: *.key, *.pem
  • IDE files: .vscode/**, .idea/**, *.swp
  • Build artifacts: coverage/**, .pytest_cache/**, .cache/**
  • Unsupported lock files: package-lock.json, bun.lockb, yarn.lock, pnpm-lock.yaml
  • Other: Dockerfile, docker-compose.yml, *.md, *.sh, *.log, .DS_Store
Additional patterns can be added via filesToExclude in your agent config.
Note: DESCRIPTION.md is not uploaded as a file - its content is sent as agent metadata during upload.
Settings: If your circuit.toml includes settings (e.g. [settings.risk_level]), they are validated during upload and stored with the agent. Users will see the settings when starting a session with your agent. Changing settings requires a new upload. See Settings for configuration details. Content deduplication: Circuit stores separate content hashes for the deploy bundle, retained source, and environment variables. Uploading the same three artifacts again is idempotent. A source, bundle, or environment change replaces the agent’s current runnable state.

​
Environment Variables

run, unwind, and upload load environment variables from .env files and support --var overrides. For run and unwind, env vars are injected into the locally spawned agent process. For upload, they are encrypted and stored for deploy-time injection. Source and precedence:
  • Base source: .env in the project root
  • Overrides: --var KEY=VALUE
  • If the same key exists in both, the CLI flag value wins
Example Argument usage:
Security model:
  • Env vars are encrypted before being stored in Circuit’s infrastructure.
  • Plaintext .env values are not stored in the uploaded source bundle or visible in the source code viewer.
  • At deploy time, env vars are decrypted and injected into the agent’s environment.
  • Your code reads them normally with process.env (TypeScript) or os.getenv() (Python).
Important limits and behavior:
  • Environment variables have a 4 KB total limit (including system vars).
  • Changing env vars replaces the agent’s current environment without changing the bundle content hash.
  • To rotate env vars, re-upload your agent.