Environment Variables

Built-in and custom environment variables available to handler scripts.

Built-in variables

Every handler script receives these environment variables automatically. Variables marked with a version are only injected by that worker release or later.

Variable	Since	Description	Example
`CUEAPI_EXECUTION_ID`	0.1.0	Execution UUID	`550e8400-e29b-41d4-a716-446655440000`
`CUEAPI_CUE_ID`	0.1.0	Cue ID	`cue_a1b2c3d4e5f6`
`CUEAPI_CUE_NAME`	0.1.0	Cue name	`nightly-digest`
`CUEAPI_WORKER_ID`	0.1.0	Worker daemon ID	`worker_7f3e...`
`CUEAPI_PAYLOAD`	0.1.0	Full payload as a JSON string	`{"task":"draft-linkedin","instruction":"..."}`
`CUEAPI_API_KEY`	0.2.1	The worker's API key. Lets the handler call CueAPI directly (chain follow-up cues, report outcome with evidence, etc.)	`cue_sk_...`
`CUEAPI_BASE_URL`	0.2.1	CueAPI base URL. Pairs with `CUEAPI_API_KEY` for self-host awareness	`https://cueapi.ai`
`CUEAPI_OUTCOME_FILE`	0.3.0	Path to a per-run temp file the handler can write JSON evidence to	`/tmp/cueapi-outcome-abc.json`

Parse the payload in the handler:

python

import json
import os
 
payload = json.loads(os.environ["CUEAPI_PAYLOAD"])
task = payload.get("task")
instruction = payload.get("instruction")

See Outcome File for $CUEAPI_OUTCOME_FILE usage and schema, and Chain Pattern for using $CUEAPI_API_KEY + $CUEAPI_BASE_URL to schedule follow-up cues from inside a handler.

Custom environment variables

Define custom env vars in the handler config:

yaml

handlers:
  my-task:
    cmd: "python3 handler.py"
    env:
      MY_STATIC_VAR: "hello"
      MY_PAYLOAD_VAR: "{{ payload.instruction }}"

Template syntax

Use {{ payload.field }} to inject payload values:

yaml

env:
  INSTRUCTION: "{{ payload.instruction }}"
  CONTEXT_REF: "{{ payload.context_ref }}"
  AGENT: "{{ payload.agent }}"

Nested fields

Dot notation for nested objects:

yaml

env:
  OUTPUT_DIR: "{{ payload.config.output_dir }}"
  FORMAT: "{{ payload.config.format }}"

Missing fields

If a referenced payload field doesn't exist, it resolves to an empty string ("").

System environment

Handler scripts inherit the system environment. You can reference system env vars with ${} syntax:

yaml

env:
  OPENAI_API_KEY: "${OPENAI_API_KEY}"
  ANTHROPIC_API_KEY: "${ANTHROPIC_API_KEY}"
  HOME: "${HOME}"

Example: full handler env

yaml

handlers:
  draft-linkedin:
    cmd: "python3 linkedin_agent.py"
    timeout: 300
    env:
      # From payload
      INSTRUCTION: "{{ payload.instruction }}"
      CONTEXT_REF: "{{ payload.context_ref }}"
      CONTEXT_MODE: "{{ payload.context_mode }}"
      AGENT: "{{ payload.agent }}"
      # From system
      ANTHROPIC_API_KEY: "${ANTHROPIC_API_KEY}"

In the handler script:

python

import json
import os
 
payload = json.loads(os.environ["CUEAPI_PAYLOAD"])
instruction = payload.get("instruction")  # Or read INSTRUCTION from env
execution_id = os.environ["CUEAPI_EXECUTION_ID"]  # Built-in

DASHBOARD_URL

Dashboard URL for self-hosted deployments. Used in failure notification emails and alert links.

Default: https://dashboard.cueapi.ai
Set to your own URL when self-hosting

bash

export DASHBOARD_URL=https://my-dashboard.example.com

Previous← Handler Routing NextOutcome File →