Environment variables

Every variable the Cycls SDK, the agent runtime and its optional services read, with where each one belongs.

Cycls loads a .env file from the working directory at import. Variables fall into three groups by where they belong.

On your machine

These are for deploying. Keep them out of the container image.

Variable	Required	Purpose
CYCLS_API_KEY	yes, for any cloud command	authenticates deploy, run --remote, ls, rm, logs, cost, sql, volume
CYCLS_BASE_URL	no	overrides the API base, default https://api.cycls.ai
DOCKER_BUILDKIT	no	passed through to Docker for local builds

import cycls

cycls.api_key = "..."     # equivalent to CYCLS_API_KEY
cycls.base_url = "..."    # equivalent to CYCLS_BASE_URL

Inside the container

These belong in the image, usually through .copy(".providers.env", ".env").

Variable	Required	Purpose
ANTHROPIC_API_KEY	for anthropic/* models	read by the Anthropic SDK
OPENAI_API_KEY	for OpenAI and any endpoint without .api_key()	read by the OpenAI SDK. Also enables voice input
BRAVE_API_KEY	for portable web search	without it, WebSearch falls back to the provider’s native search where one exists
CYCLS_SECRET_KEY	for connectors	encrypts stored credentials. Storing a grant fails without it

Any other key your handlers use, such as a service token for your own API, goes here too.

Do not put CYCLS_API_KEY in the image. It is a deploy credential. Splitting .env for your machine and .providers.env for the container keeps it out:

image = cycls.Image().copy(".providers.env", ".env")

Optional services

Set these when the matching feature should be available. With any of them unset, the feature is not offered and nothing else breaks.

Variable	Feature	Documented in
OFFICE_RENDER_URL	presentation and PDF rendering	Files and the canvas
OFFICE_RENDER_SECRET	same
BROWSER_PROVIDER	browser automation, cycls or steel	Tools
BROWSER_URL	the browser service base URL
BROWSER_SECRET	the browser service secret
BROWSER_PROXY, BROWSER_PROXY_SERVER, BROWSER_PROXY_USERNAME, BROWSER_PROXY_PASSWORD	proxy routing for the browser
BROWSER_HUMANIZE	human-like input timing
CYCLS_APP_BUILDER	name of the app build service, default app-build	Tools

Connector relay

Set on deployments that share one registered OAuth redirect across agents.

Variable	Purpose
CYCLS_RELAY_URL	where providers send the authorization code
CYCLS_RELAY_SECRET	signs the state that rides through the provider
CYCLS_RELAY_ORIGINS	comma-separated agent origins the relay may hand a code to

Injected by the platform

Read these, do not set them.

Variable	Meaning
CYCLS_VOLUMES	JSON map of mount path to backing bucket
CYCLS_WORKSPACE	the workspace mount path inside the sandbox, /workspace
CYCLS_TRASH	the trash mount path used by the rm shim
CYCLS_CRON_TOKEN	authenticates a scheduled invocation
PORT	the port the service must bind
K_REVISION	the running revision, used in run records

Checking what a container sees

cycls shell my_agent.py
root@a1b2c3:/app# env | sort

Next

Limits and quotas

Sizes, timeouts and caps in one table.