Configuration

Configure only what you need at the start: a Project and a read-only API key for your AI tools. Add a provider when you want model-assisted ingestion, linking, lint, or another explicitly configured model-backed job.

Projects

A project is a separate knowledge base. Use one project per repo, service, product, customer, or research area.

In the web app, use Projects to create, switch, and inspect projects. For automation, use the REST API against your licensed Synth deployment:

export SYNTH_URL=https://synth.example.com

curl -b /tmp/synth.cookie \
  -H "Content-Type: application/json" \
  -d '{"name":"backend-api","parent_dir":"/var/lib/synth/projects","backend_type":"local"}' \
  "$SYNTH_URL/api/projects/"

For Kubernetes, prefer Helm + CaSc when the project should be created the same way on every install.

Optional Providers

Canonical Project search and exact page reads do not require a provider. Synth can use different models for extraction, linking, and lint jobs. When you enable those jobs, a practical default is:

• extraction: accurate model
• lint: fast, economical review model
• audits: off or cheap model until you need them

Add provider keys in Settings -> Providers and choose model defaults in Settings -> Models.

If your organization routes models through LiteLLM Proxy or another OpenAI-compatible gateway, use the existing OpenAI provider and follow LiteLLM & OpenAI-Compatible Gateways.

For Docker Compose, set provider keys in values.env. For Kubernetes, put provider keys in Kubernetes Secrets and reference them from Helm values.

kubectl -n synth create secret generic synth-runtime-secrets \
  --from-literal=OPENCODE_API_KEY="$OPENCODE_API_KEY" \
  --dry-run=client -o yaml | kubectl apply -f -

API Keys

API keys use the synth_sk_... format. They power MCP, scripts, and SDK calls.

Create keys in Global Settings -> API Keys. For an AI agent, start with read-only knowledge scopes and add write scopes only when the workflow needs them.

Common scopes:

Scope	Use
knowledge:read	search and read pages
ingest:write	add sources and manage watchers
repo_context:read	read repository context metadata
admin:read / admin:write	manage settings
full_access	local admin scripts only

Safe Defaults

• Keep auto-lint off until you choose a model and budget.
• Use project-scoped API keys for agents.
• Use SYNTH_PUBLIC_URL when deployed behind a real hostname.
• Prefer the web UI for provider credentials unless you are deploying with env vars.

Configuration As Code

CaSc is Synth's Configuration-as-Code format. It is pronounced cask.

Use CaSc for settings that should be repeatable across installs:

• global default provider and model
• agent model and temperature defaults
• project names and project-level overrides
• watcher definitions
• provider enablement and non-secret provider settings

Do not store secrets in CaSc. Provider keys and Git tokens should live in the web credential store, environment variables, Kubernetes Secrets, or your secret manager.

In the web app, open Global Settings -> CaSc to export or import a complete configuration document.

In Kubernetes, the Helm chart renders CaSc from values and imports it on pod startup. See Helm + CaSc.

Next: MCP for AI Agents.