Skip to main content

​
Upload Agent

circuit upload saves the current project as the agent’s code. It requires authentication, valid circuit.toml (including starting-asset 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, whether this was the first upload, and app link. agentId in circuit.toml is the permanent agent identity. Renaming retains its sessions and state. A successful upload replaces the agent’s code, environment, setting definitions and triggers, and every hosted session runs them from its next run. Running hosted sessions keep each unchanged trigger’s state, stop removed triggers and start added ones; a trigger whose filter or cooldown changed starts fresh. 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, paths (a JSON array with one project path per file, in file order; file part names are ignored), and optional envVars. Bodies may be up to 32 MiB. Installation and build validation run in an isolated builder with no backend or developer-host file access.

​
Sharing

All agents are public. Anyone can view an agent and start their own session once it has uploaded code. Share opens link and social sharing in both the builder and agent page. Every agent with uploaded code is listed on its creator’s profile; the Agents page lists it once at least three people other than its creator have run it with real money in the last 30 days. Every upload also becomes the agent’s Builder Workspace, replacing any unsaved Builder changes. Builder Workspaces and chats are owner-only, and environment variables remain encrypted and separate from source. Every agent’s uploaded source is visible to signed-in users, and anyone signed in can fork it.

​
Fixed source exclusions

The agent directory is the complete source boundary. circuit check, local execution, upload and Builder saves collect the same files; Circuit applies the policy again to every upload, and the code viewer shows exactly the files the published bundle was built from. Circuit excludes only these fixed patterns:
  • Version control: .git, .gitignore, .svn
  • Dependencies and builds: node_modules, dist, build, .next, .nuxt, .cache, .bun, .npm, coverage, .nyc_output, __pycache__, .pytest_cache, .ruff_cache, .mypy_cache, *.egg-info, *.pyc, *.bin, .venv, venv
  • Secrets and local config: .env, .env.*, .dev.vars, *.key, *.pem, .npmrc, .pypirc, bunfig.toml
  • Editor, assistant and OS: .vscode, .idea, .claude, .claude.json, AGENTS.md, *.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
Other *.md and *.sh files are source. DESCRIPTION.md is also sent as agent metadata.

​
Environment Variables

run 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. Uploaded variables are limited to 3,500 bytes as serialized JSON; re-upload to rotate them.