Hosted platform / v0.7.0

Connect to the hosted platform

Name: Code Atelier Governance SDK
Author: Code Atelier

The hosted Code Atelier Governance platform gives every SDK deployment a live dashboard, multi-agent timeline, and workflow-scoped tokens — without asking you to move your audit log off your own Postgres. The SDK dual-writes each event: your local Postgres stays the authoritative source of record, and the platform receives a fire-and-forget copy over HTTPS.

Opt-in, non-blocking

The bridge default is platform_bridge_enabled=False. Setting the URL and token env vars alone is not enough — you must also flip the enable flag. If the platform is unreachable, rate-limited, or the token is revoked, the host application keeps running and local Postgres writes are unaffected. See the data-residency note below before activating in regulated environments.

Setup

Four steps. Under five minutes if you already have the SDK installed.

Install the platform extra

Adds httpx to the SDK so the bridge HTTP client can import. Without this extra, the SDK raises at init time when platform credentials are configured — never silently no-ops.

pip install --upgrade "code-atelier-governance[platform]>=0.7.0"

Sign up and register a workflow

Go to the platform, sign in with a magic link, and register a new workflow. A workflow is a scoped ingest target — usually one per environment (staging, prod) or one per agent surface. You get a wf_... ingest token on the workflow detail page.

# Open the hosted platform and sign up:
https://governance.codeatelier.tech/

# After the magic-link sign-in:
#   1. Create a workflow (e.g. "billing-agents-prod")
#   2. Copy the wf_... ingest token shown on the workflow detail page

Set three environment variables

The SDK reads the URL and token from env, and reads platform_bridge_enabled=true before it activates the bridge. All three are required — omit any one and the bridge stays dark (and, if creds are set without the enable flag, emits a startup INFO line so the misconfiguration is visible).

export GOVERNANCE_PLATFORM_INGEST_URL="https://governance.codeatelier.tech/api/v1/ingest/events"
export GOVERNANCE_PLATFORM_INGEST_TOKEN="wf_..."      # from step 2
export GOVERNANCE_PLATFORM_BRIDGE_ENABLED="true"      # explicit opt-in

Start the SDK and verify

Restart your application. On sdk.start(), the SDK emits a single platform.bridge_enabled WARN line surfacing the configured URL — activation is never invisible. Drive one audit event through your app, then refresh the workflow's event timeline in the platform; the row should appear within a second or two.

import os
from codeatelier_governance import GovernanceSDK, AuditEvent

async with GovernanceSDK(
    database_url=os.environ["DATABASE_URL"],
    # Env-driven. You can also pass platform_* kwargs directly:
    #   platform_ingest_url=...,
    #   platform_ingest_token=...,
    #   platform_bridge_enabled=True,
) as sdk:
    await sdk.audit.log(AuditEvent(
        agent_id="my-agent",
        kind="platform.bridge.smoketest",
    ))
    # Row is in your Postgres immediately.
    # Fire-and-forget POST to the platform completes in the background.

Configuration reference

Every platform-bridge knob has a kwarg on GovernanceSDK(...) and an env-var equivalent. Env wins over kwarg only when the kwarg is unset — explicit code-level config takes precedence. All four options landed in v0.7.0.

Kwarg	Env var	Default	Purpose
`platform_bridge_enabled`	`GOVERNANCE_PLATFORM_BRIDGE_ENABLED`	`False`	Master switch. Bridge never activates without this, even if URL and token are set.
`platform_ingest_url`	`GOVERNANCE_PLATFORM_INGEST_URL`	—	HTTPS ingest endpoint. Normally `https://governance.codeatelier.tech/api/v1/ingest/events`.
`platform_ingest_token`	`GOVERNANCE_PLATFORM_INGEST_TOKEN`	—	Workflow-scoped `wf_...` token from the platform UI. Rotate by revoking on the workflow detail page.
`platform_trusted_hosts`	`GOVERNANCE_PLATFORM_TRUSTED_HOSTS`	—	Optional comma-separated allowlist of hostnames the bridge may POST to. Belt-and-suspenders on top of the default-ON SSRF guard.

Hardening defaults

The bridge is on a public HTTPS path, so v0.7.0 ships with aggressive defaults you do not need to configure. Listed here for security review:

SSRF guard, default-on. RFC1918, loopback, link-local, and cloud-metadata hosts (AWS 169.254.169.254, GCP, Azure) are rejected at resolution time even without an explicit platform_trusted_hosts allowlist.
Proxy + redirect pinning. trust_env=False on the httpx client (blocks HTTPS_PROXY exfiltration) and follow_redirects=False (blocks 302-based exfiltration).
Fire-and-forget with backpressure. Bounded in-process queue (default 1000, drops oldest on saturation). Exponential backoff on 429; silent on 5xx; logs but does not raise on 4xx. On revoked-token 401, the bridge self-disables until restart.
Observability-grade, not durable-queue. On crash or kill -9, up to max_queue_size in-flight rows on the bridge path may be lost. Local Postgres writes are unaffected — that is still your authoritative record.
Seq self-heal. On a seq_out_of_order 409 the bridge reads the server's expected_seq and retries once, so an SDK process restart that jumps the local seq counter converges without operator intervention.

Data residency

Activating the bridge routes a copy of every audit event (event_type, agent_id, session_id, and metadata up to 64 KiB) to codeatelier.tech. The bridge is designed to be OFF by default; customers who cannot move audit metadata off-premise should leave it off — your local Postgres is still the authoritative source of record.

The platform redacts the usual secret-shaped patterns (DSNs, bearer tokens, base64 runs) the same way the OTel exporter does in v0.6.1+. Region, retention window, and DPA template are linked from the WARN line emitted at bridge activation.

Known limitations in v0.7.0

The bridge seq counter is process-scoped. An SDK restart re-starts the counter at 1; seq self-heal converges after the first retry. Postgres-persisted seq lands in v0.8.
Budget-alert webhook dedup (v0.7.0 BudgetPolicy.alert_webhook_url) is in-memory — expect duplicate POSTs on process bounce within the same UTC day. Postgres-backed dedup lands in v0.7.1.

Continue to the Console guide →