Upload Agent
circuit upload publishes the current project. It requires authentication, valid circuit.toml (including starting-asset and deployment-region rules), index.ts, package.json, and a current bun.lock.
Run
bun install after dependency changes, then circuit check. Upload collects the same fixed source set, pins the source and lockfile, installs dependencies without scripts, verifies run, and builds in Circuit’s production environment. It stores one deterministic SHA-256 code artifact and encrypted environment variables separately, returning the agent ID, code hash, publish state and app link. A root DESCRIPTION.md is optional and also becomes description metadata.
agentId in circuit.toml is the permanent agent identity. Renaming retains its sessions and state. A successful upload replaces content for future run admissions in new and live sessions; already-admitted runs keep their pinned code, environment and settings. Failure preserves current content. Unchanged code and environment are deduplicated. Code or environment changes replace the current runnable state; an environment-only change preserves the bundle hash.
The upload endpoint accepts files, optional envVars, and metadataOnly (default false); publication intent follows from the endpoint. Bodies may be up to 32 MiB. Installation and build validation run in an isolated builder with no backend or developer-host file access. Local publication requires Docker and the builder image prepared by bun local up.
Disabling and Enabling an Agent
circuit upload --enable=false publishes current code, hides the agent from lists, popular/related sections, its detail page and leaderboard, and pauses every running session. Creators and admins retain access; Show disabled agents keeps it in the creator’s list. Disabling blocks new sessions, resumes and manual runs. It moves no funds; session owners can still Stop or Unwind from their session cards.
circuit upload --enable=true publishes current code and restores discoverability. Owners must resume previously paused sessions themselves. Both commands require authentication and target the agentId in circuit.toml; repeating the same enabled value makes no further visibility change.
Visibility
New uploads are public by link immediately, without approval. Upload prints the detail-page link; the page’s Share button also provides it. Anyone with the link can view and start the agent. Circuit separately curates the Home feed; unfeatured agents remain reachable by link. Use disabling to stop circulation and pause sessions.Fixed source exclusions
The agent directory is the complete source boundary.circuit check, local execution, and upload
collect the same files. Circuit excludes only these fixed patterns:
- Version control:
.git,.gitignore,.svn - Dependencies and builds:
node_modules,dist,build,.next,.nuxt,.cache,.bun,coverage,.nyc_output,__pycache__,.pytest_cache,.ruff_cache,.mypy_cache,*.egg-info,*.pyc,.venv,venv - Secrets and local config:
.env,.env.*,.dev.vars,*.key,*.pem,.npmrc,.pypirc,bunfig.toml - Editor and OS:
.vscode,.idea,*.swp,*.swo,*~,.DS_Store,Thumbs.db - Unsupported lock files:
package-lock.json,bun.lockb,yarn.lock,pnpm-lock.yaml - Deployment and tooling:
Dockerfile,.dockerignore,wrangler.toml,wrangler.jsonc,.wrangler,.circuit,.builder,docs,*.log,*.tmp
*.md and *.sh files are source. DESCRIPTION.md is also sent as agent metadata.
Settings: circuit.toml settings are validated and stored during upload, then shown when users start a session. Upload again to change them; see the settings contract.
Environment Variables
run, unwind, and upload read project .env, with repeatable --var KEY=VALUE overrides taking precedence. Local execution injects values into the agent subprocess. Upload encrypts them at rest, excludes plaintext from the source bundle and code viewer, and decrypts them for deployment. Agent code reads process.env.KEY.