Skip to main content

​
Publish Agent

Publish your agent to Circuit infrastructure. 
circuit publish
Flags:
  • --path <path> / -p <path>: Publish from a specific agent directory instead of the current directory.
  • --env KEY=VALUE / -e KEY=VALUE: Override/add env vars for this publish (repeatable).
What happens:
  1. Validates your project and circuit.toml (including startingAsset and deployment-region rules)
  2. Collects project files based on exclusion patterns
  3. Reads environment variables from .env in the agent root (if present)
  4. Applies --env 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 publish 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 publishing 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 signin)
  • Valid circuit.toml configuration
  • All dependencies installed

​
Deployment Regions

If you set deploymentRegionOverride in circuit.toml, the allowed values are:
Allowed valuesDefault when omitted
us-east-1, eu-central-1us-east-1
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/**
  • Lock files: package-lock.json, 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 publish.
Content deduplication: Circuit calculates a content hash of your uploaded files on the server. If you retry a publish while a build is still in progress and the content hash matches, the existing in-flight build is reused rather than creating a duplicate. In all other cases, you must increment the version in circuit.toml before publishing.

​
Environment Variables

All commands that touch agent code (run, unwind, check, publish) load environment variables from .env files and support --env overrides. For run and unwind, env vars are injected into the locally spawned agent process. For publish, they are encrypted and stored for deploy-time injection. Source and precedence:
  • Base source: .env in the project root
  • Overrides: --env KEY=VALUE
  • If the same key exists in both, the CLI flag value wins
Example Argument usage: 
circuit publish --env KEY="value" --env 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 publish content hash, so a new version is created.
  • To rotate env vars, republish your agent.