Configuration

Choosing a Workspace Image

The default workspace image is configured in syn-shared:

# Override via environment variable
SYN_WORKSPACE_DOCKER_IMAGE=ghcr.io/agentparadise/agentic-workspace-claude-cli:2.1.76

To use a custom or locally-built image:

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

# Point syn137 at it
SYN_WORKSPACE_DOCKER_IMAGE=my-workspace:latest

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

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.

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/
    owner__reponame/     # Pattern: org + double-underscore + repo name
    owner__other-repo/   # e.g. acme__api-service, acme__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.