ci.env - Cirron Documentation

Thin convenience over os.environ with .env file loading and automatic JSON parsing for structured values. Not a proprietary config system; ci.env(key) is functionally os.environ.get(key) plus two ergonomic additions.

Signature

def env(key: str, default: Any = None) -> Any

Parameters

Name	Type	Default	Purpose
`key`	`str`	-	Environment variable name
`default`	any	`None`	Returned when the key is absent

Behavior

.env loading: on first call, loads a .env file from the current working directory via python-dotenv if that package is installed. If python-dotenv isn’t installed, .env loading is silently skipped; os.environ is read directly.
JSON auto-parsing: values whose first non-whitespace character is { or [ are parsed with json.loads(). Scalars (numbers, "true", "false", plain strings) stay as strings; cast them yourself. This avoids surprises like "123" becoming an int you didn’t expect.

Examples

Plain env vars

api_base = ci.env("API_BASE_URL", default="https://api.example.com")
debug    = ci.env("DEBUG", default=False)

Structured config

# CONFIG='{"threshold": 0.5, "capture_embeddings": true}'
config = ci.env("CONFIG")          # returns {"threshold": 0.5, "capture_embeddings": True}
ci.profile(config=config)

Platform context

The Cirron runtime injects these automatically inside pipelines and deployments:

Variable	Purpose
`CIRRON_RUN_ID`	Run this process belongs to
`CIRRON_PIPELINE_ID`	Pipeline this run executed as (if any)
`CIRRON_DEPLOYMENT_ID`	Deployment this process is part of (if any)
`CIRRON_WORKSPACE_ID`	Owning workspace
`CIRRON_DATA_DIR`	Base directory for data staged by a Load Data step (`/data`); read your dataset from a subpath like `/data/input`
`CIRRON_DATASET_URI`	Storage URI of the staged dataset, used to read directly from storage when staging is off

ci.env() reads them like any other variable. ci.profile() reads them internally to set span attribution and pick the transport.

run_id       = ci.env("CIRRON_RUN_ID")
workspace_id = ci.env("CIRRON_WORKSPACE_ID")

Updating values on the deployment

On the deployment config panel in the Cirron platform dashboard, edit an env var and hit apply. The platform triggers a rolling restart of the deployment’s containers with the new values. There is a brief pause per replica, not zero-downtime. The next call to ci.env() after restart returns the updated value; the SDK doesn’t cache env values, so no additional invalidation step is needed.

Alternatives

ci.env() is a convenience, not a requirement. os.environ.get(), python-decouple, and pydantic-settings all work fine with the SDK.

ci.secret

For credentials. Never pass a secret through ci.env.

Configuration guide

Full resolution order: explicit → env → config.toml → defaults.

​Signature

​Parameters

​Behavior

​Examples

​Plain env vars

​Structured config

​Platform context

​Updating values on the deployment

​Alternatives

​Related