Environment Variables
AI Crawler / Raw View: Fetch this page as raw Markdown at
/reference/environment-variables.md. Cloud Harness MCP is configured via environment variables supplied to the stateless API, the Runner, and the Cloudflare Worker Gateway.
Copy .env.example to .env and replace all change-me placeholder secrets before starting services.
Configuration Table
| Variable | Default / Example | Required / Mode | Description & Purpose |
|---|---|---|---|
MCP_BEARER_TOKEN | change-me-at-least-32-random-characters | Required | Copy to .env and replace every change-me value. Never commit real secrets. |
RUNNER_TOKEN | change-me-independent-runner-token | Required | Required configuration. |
OWNER_ID | owner | Required | Required configuration. |
AUTH_MODE | owner-bearer | Required | owner-bearer (default) or cloudflare-access. In Access mode, remove MCP_BEARER_TOKEN. |
CLOUDFLARE_ACCESS_ISSUER | https://your-team.cloudflareaccess.com | Optional | Optional configuration. |
CLOUDFLARE_ACCESS_AUDIENCE | — | Optional | Optional configuration. |
CLOUDFLARE_ACCESS_JWKS_URL | https://your-team.cloudflareaccess.com/cdn-cgi/access/certs | Optional | Optional configuration. |
API_KEY_AUTH_ENABLED | false | Optional | Optional managed API-key lane. Enable all four together only in cloudflare-access mode. The gateway audience belongs to a separate Access application scoped exactly to /mcp-api-key. |
API_KEY_GATEWAY_ACCESS_AUDIENCE | — | Optional | Optional configuration. |
API_KEY_GATEWAY_SERVICE_SUBJECT | cf-service:base64url-cloudflare-service-token-client-id | Optional | Optional configuration. |
API_KEY_GATEWAY_PUBLIC_URL | https://api.harness.zuey.me/mcp | Optional | Optional configuration. |
ACCESS_LEGACY_OWNER_ID | owner | Optional | Worker-only secrets CF_ACCESS_CLIENT_ID and CF_ACCESS_CLIENT_SECRET are configured with Wrangler, never here. Exact one-time legacy owner binding for the first Access rollout: |
ACCESS_LEGACY_ISSUER | https://your-team.cloudflareaccess.com | Optional | Optional configuration. |
ACCESS_LEGACY_SUBJECT | — | Optional | Optional configuration. |
ACCESS_PRINCIPAL_RELINKS | [] | Optional | Optional audited subject-rotation mappings, supplied as strict JSON: |
API_PUBLIC_HOSTS | localhost,127.0.0.1,cloud-harness-mcp.46-250-239-227.sslip.io | Required | Required configuration. |
API_ALLOWED_ORIGINS | https://cloud-harness-mcp.46-250-239-227.sslip.io | Required | Required configuration. |
API_PORT | 3000 | Required | Required configuration. |
RUNNER_PORT | 3001 | Required | Required configuration. |
RUNNER_URL | http://runner:3001 | Required | Required configuration. |
JOBS_ROOT | /var/lib/cloud-harness/jobs | Required | Required configuration. |
STATE_DB | /var/lib/cloud-harness/state/cloud-harness.db | Required | Required configuration. |
ARTIFACT_ROOT | /var/lib/cloud-harness/artifacts | Required | Required configuration. |
MAX_ARTIFACT_BYTES | 16777216 | Required | Required configuration. |
MAX_PRINCIPAL_ARTIFACT_BYTES | 134217728 | Required | Required configuration. |
ARTIFACT_RETENTION_SECONDS | 86400 | Required | Required configuration. |
EXECUTOR_IMAGE | cloud-harness-executor:local | Required | Required configuration. |
ALLOWED_GIT_HOSTS | github.com | Required | Required configuration. |
WORKSPACE_NETWORK_MODE | none | Required | Required configuration. |
WORKSPACE_WALL_TTL_SECONDS | 900 | Required | Required configuration. |
WORKSPACE_IDLE_TTL_SECONDS | 300 | Required | Required configuration. |
GITHUB_APP_ID | — | Optional | Optional GitHub App repository access; required fields depend on AUTH_MODE: |
GITHUB_APP_INSTALLATION_ID | — | Optional | Required in owner-bearer mode; omit in Access mode, where each principal binds an installation: |
GITHUB_APP_SLUG | — | Optional | Required in Access mode for the installation redirect: |
GITHUB_APP_PRIVATE_KEY_FILE | /run/cloud-harness-secrets/github-app-private-key.pem | Optional | Production host file: /etc/cloud-harness-mcp/github-app-private-key.pem |
SECRET_KEYRING_FILE | /run/cloud-harness-secrets/secret-keyring.json | Optional | Versioned AES-256-GCM keyring JSON. Prefer the runner-only file form. |
Security Guidelines
- Never commit
.envfiles or tokens into version control. - Runner secrets isolation:
RUNNER_TOKENandSECRET_KEYRING_FILEare passed only to the Runner container, never to the API or workspace executors. - Managed OAuth vs Bearer: When
AUTH_MODE=cloudflare-access, removeMCP_BEARER_TOKENand configureCLOUDFLARE_ACCESS_*variables instead. - Executor Isolation: Executors never inherit host environment variables or control plane tokens.