> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cycls.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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                                           |

```python theme={null}
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.

<Warning>
  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:

  ```python theme={null}
  image = cycls.Image().copy(".providers.env", ".env")
  ```
</Warning>

## 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](/agents/files#configuring-office-rendering) |
| `OFFICE_RENDER_SECRET`                                                                      | same                                               |                                                                    |
| `BROWSER_PROVIDER`                                                                          | browser automation, `cycls` or `steel`             | [Tools](/agents/tools#built-in-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](/agents/tools#built-in-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

```bash theme={null}
cycls shell my_agent.py
root@a1b2c3:/app# env | sort
```

## Next

<Card title="Limits and quotas" icon="gauge" href="/reference/limits">
  Sizes, timeouts and caps in one table.
</Card>