# Configuration
> "How to configure workspace images: custom images, environment variables, OTel endpoints, and plugin configuration."

## Choosing a Workspace Image

The default workspace image is configured in `syn-shared`:

```bash
# 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:

```bash
# 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:

| Variable | Default | Purpose |
|----------|---------|---------|
| `ANTHROPIC_NO_ATTRIBUTION` | `1` | Disable Claude attribution in commits |
| `DISABLE_TELEMETRY` | `1` | Disable vendor usage metrics |
| `DISABLE_ERROR_REPORTING` | `1` | Disable vendor error reporting |
| `RTK_TELEMETRY_DISABLED` | `1` | Disable RTK analytics |
| `CLAUDE_CODE_ENABLE_TELEMETRY` | `1` | Enable OTel metric export |
| `OTEL_METRICS_EXPORTER` | `otlp` | Export metrics via OTLP |
| `OTEL_METRIC_EXPORT_INTERVAL` | `5000` | 5s export interval |

### Set by Orchestrator at Runtime

These are injected automatically by syn137 when creating workspaces:

| Variable | Purpose |
|----------|---------|
| `ANTHROPIC_API_KEY` | Claude API key (injected via sidecar) |
| `CLAUDE_CODE_ENABLE_TELEMETRY` | Activates OTel export (set to `1` when collector is configured) |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | Collector endpoint, auto-set to `COLLECTOR_URL` from syn-api config |
| `GITHUB_TOKEN` | GitHub access (injected via sidecar) |
| `SYN_ALL_REPOS` | Colon-separated list of pre-cloned repo paths (e.g. `/workspace/repos/acme__api:/workspace/repos/acme__web`). Empty string when no repos are configured. See [Workspace Hydration](/docs/workspaces/hydration). |

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:

```bash
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](https://github.com/AgentParadise/agentic-primitives/docs/adrs/ADR-033-plugin-native-workspace-images.md) 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](/docs/workspaces/hydration) for how repos are cloned and context files are synthesized.