Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.circuit.org/llms.txt

Use this file to discover all available pages before exploring further.

​
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 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 publishing
For TypeScript projects, run bun install before publishing 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.

​
Version Approval and Visibility

Newly published agents are private by default. That means the agent is only visible to you until an admin changes its visibility to public. After publishing, 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 publish succeeded and review the version details. Other users only see the latest approved version. This means that if you publish 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.

​
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/**
  • 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 publish.
Settings: If your circuit.toml includes settings (e.g. [settings.risk_level]), they are validated during publish and snapshotted with the deployed version. Users will see the settings when starting a session with your agent. Changing settings requires a new publish. See Settings for configuration details. Content deduplication: Circuit calculates a content hash of your uploaded files on the server. Each circuit publish 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 publish is idempotent — the existing version is returned without redeploying. Reverting to older code republishes that content as a new versionNumber so the agent flips back to it.

​
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.