Configuration

Choosing a Workspace Image

The default workspace image is agentic-workspace-toolchain, pinned by digest in syn-shared. It is the omni-agent image (both the claude and the codex harness, so switching a phase's agent.provider needs no image change) plus a native build floor: a C toolchain, rustup, pnpm and bun.

# Override via environment variable
SYN_WORKSPACE_DOCKER_IMAGE=ghcr.io/agentparadise/agentic-workspace-toolchain@sha256:<digest>

To use a custom or locally-built image:

# Build locally
cd lib/agentic-workspace
uv run scripts/build-provider.py omni-agent --tag my-workspace:latest

# Point syn137 at it. A local image has no signature, so it must be
# allowed explicitly and must already exist on the Docker host.
SYN_WORKSPACE_DOCKER_IMAGE=my-workspace:latest
SYN_IMAGE_VERIFY_ALLOW_LOCAL_IMAGES=true

Environment Variables

Set by the Image (Defaults)

These are baked into the image and generally should not be overridden:

Set by Orchestrator at Runtime

These are injected automatically by syn137 when creating workspaces:

You do not need to set these manually. The orchestrator injects them when workspace containers are provisioned.

OTel Configuration

How OTel connects to syn-collector

OTel export is a claude harness feature. Codex phases emit no OTel metrics or logs. CLAUDE_CODE_ENABLE_TELEMETRY=1 is baked into the workspace image as a default. When syn-api has COLLECTOR_URL set, it also injects OTEL_EXPORTER_OTLP_ENDPOINT pointing at the collector. If no COLLECTOR_URL is configured, OTel export silently no-ops, no crash, no side effects.

syn-collector's internal port is 8080 (service name collector inside Docker). The dev stack maps it to localhost:8080.

# Inside Docker (agent-net), what the container uses:
http://collector:8080

# From your host machine, for debugging:
http://localhost:8080

syn-collector accepts OTLP JSON on /v1/metrics and /v1/logs.

Privacy Controls

By default, prompt content and tool I/O are not exported:

OTEL_LOG_USER_PROMPTS=0   # Don't log prompt content
OTEL_LOG_TOOL_DETAILS=0   # Don't log tool input/output

Set to 1 to enable detailed logging (useful for debugging, not recommended for production).

Plugin Configuration

Plugins are loaded from /opt/agentic/plugins/ at container startup. The entrypoint builds --plugin-dir flags for each discovered plugin directory.

Plugin Environment Variables

Plugins can declare required environment variables in their plugin.json. The orchestrator auto-forwards these from the workspace configuration. See ADR-033 for the plugin specification (moved from agentic-primitives, 2026-09, see #1417).

Workspace Directory Structure

/workspace/
  AGENTS.md              # Synthesized - imports each repo's AGENTS.md (when repos configured)
  CLAUDE.md              # Synthesized - imports each repo's CLAUDE.md (when repos configured)
  artifacts/
    input/               # Previous phase outputs (read-only)
    output/              # Current phase deliverables
  repos/                 # Always present; empty when the phase set clone_repos: false
    api-service/         # The bare repo name - the owner is not in the path
    web-app/
/opt/agentic/
  plugins/               # Pre-bundled plugins
  config/                # Runtime configuration
  version.json           # Image version manifest
  entrypoint.sh

See Workspace Hydration for how repos are cloned and context files are synthesized.