Skip to main content

​
Upload Agent

Upload your agent to Circuit infrastructure. 
circuit upload
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).
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 with the uploaded version
  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. Generates a content hash (SHA-256) of your project files and env vars
  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 agent ID, version, and a link to the agent page
Important: Your agent’s name in circuit.toml is its permanent identity. Changing the name after uploading will create a new, separate agent — version history, sessions, and all other state belong to the original name. 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.

​
Disable and Enable Agent

Take an uploaded agent down from the app without deleting it, then bring it back. Handy in a pipeline to pull an agent from circulation on demand. 
circuit disable
circuit enable
Flags:
  • --path <path>: Target a specific agent directory instead of the current one.
What disable 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 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 (like upload) and require authentication (circuit auth login).

​
Version Approval and Visibility

Newly uploaded agents are private by default. That means the agent is only visible to you until an admin changes its visibility to public. After uploading, your new version goes through an approval process before it becomes visible to other users. What you see vs. what others see: As the agent creator, you always see your latest version on the agent detail page regardless of its approval status. This lets you verify that the upload succeeded and review the version details. Other users only see the latest approved version. This means that if you upload v0.2.0 but it hasn’t been approved yet, you’ll see v0.2.0 on the detail page while everyone else still sees v0.1.0. You can start sessions on your unapproved version, but other users will start sessions on the latest approved version once the agent is public. 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 snapshotted with the deployed version. 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 calculates a content hash of your uploaded files on the server. Each circuit upload mints a new versionNumber (rendered as v1, v2, …); you don’t manage a version field in circuit.toml. If the latest non-failed version already has the same content hash, the upload is idempotent — the existing version is returned without redeploying. Reverting to older code re-uploads that content as a new versionNumber so the agent flips back to it.

​
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: 
circuit upload --var KEY="value" --var KEY2="value2"
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 changes the upload content hash, so a new version is created.
  • To rotate env vars, re-upload your agent.