.xcind.sh is a sourceable bash script. Most projects only need a few of these. For the exhaustive list — every variable, every URL template placeholder, every override-resolution rule — see engineering/reference/configuration.md.
| Variable | Default | Purpose |
|---|---|---|
XCIND_COMPOSE_DIR |
(app root) | Subdirectory where compose files live |
XCIND_COMPOSE_FILES |
("compose.yaml" "compose.yml" "docker-compose.yaml" "docker-compose.yml") |
Compose file patterns; only those that exist on disk are used |
XCIND_COMPOSE_ENV_FILES |
(".env") |
--env-file patterns for ${VAR} substitution in compose files |
XCIND_APP_ENV_FILES |
() |
Env files injected into running containers via env_file: |
XCIND_HOST_ENV_FILE |
(unset) | Opt-in: write a host-view env file — the discovery variables with host-flavored values for assigned exports — for host-run processes |
XCIND_HOST_ENV_MODE |
own |
How XCIND_HOST_ENV_FILE is written: own (xcind owns the whole file) or block (rewrite only the # >>> xcind >>> marked region) |
XCIND_HOST_ENV_ASSIGNED_HOST |
loopback |
Host-reachable host for assigned exports: loopback (127.0.0.1) or hostname (the export's proxy-domain hostname, for wildcard-DNS setups). Also sets _EXTERNAL_HOST inside containers |
XCIND_ADDITIONAL_CONFIG_FILES |
() |
Extra shell scripts to source after .xcind.sh |
For each compose, compose-env, and app-env file pattern, Xcind also checks for an .override variant — see Override files. XCIND_HOST_ENV_FILE is a generated output path and does not derive an override sibling.
File patterns support shell variable expansion (use single quotes to defer expansion until runtime):
XCIND_COMPOSE_FILES=("compose.common.yaml" 'compose.${APP_ENV}.yaml')Walkthrough: Environment files, Override files.
| Variable | Default | Purpose |
|---|---|---|
XCIND_APP |
(directory name) | App name, used in container/network/volume naming and proxy hostnames |
XCIND_WORKSPACE |
(unset) | Self-declare a workspace name without a parent .xcind.sh |
XCIND_IS_WORKSPACE |
(unset) | Set to 1 in a workspace root's .xcind.sh |
XCIND_INSTANCE |
(auto) | Per-worktree isolation token folded into the compose project name and workspace network — never the app name or aliases. Empty on the main checkout; auto-derived from a linked git worktree's directory name. Set explicitly to override the auto value |
XCIND_INSTANCE_AUTO |
1 |
Set to 0 to disable worktree auto-detection (XCIND_INSTANCE stays empty unless set explicitly) |
Walkthrough: Workspaces vs single apps.
| Variable | Default | Purpose |
|---|---|---|
XCIND_PROXY_EXPORTS |
() |
Service exports (proxied, assigned, or unpublished ports) |
XCIND_PROXY_DOMAIN |
localhost.scind.io |
Domain suffix for generated hostnames (must be ≥2 labels — see Local HTTPS) |
XCIND_PROXY_EXPORTS entry format: export[=service][:port][;type=proxied\|assigned\|unpublished[;…]]
XCIND_PROXY_EXPORTS=(
"api=app:3000" # proxied (default)
"web:8080"
"app" # port inferred from compose
"worker:9000;type=assigned" # stable host port
"smtp=mail:1025;type=unpublished" # containers only: discovery variables, no host port
)XCIND_ENV_MAP gives discovery values your own names. Each entry is KEY=template; a template is literal text plus ${XCIND_...} references, expanded separately for containers and for the host env file:
XCIND_ENV_MAP+=(
'DATABASE_HOST=${XCIND_SHOP_DATABASE_HOST}'
'DATABASE_URL=mysql://root@${XCIND_SHOP_DATABASE_HOST}:${XCIND_SHOP_DATABASE_PORT}/shop'
)Use single quotes. Any other $ is an error, so is a backslash, a backtick, or a control character (including a newline), a key cannot start with XCIND_, and a reference that exists in neither view fails. See Environment files.
Walkthrough: Set up the Traefik proxy. To serve apps through a Traefik that already runs on the host (e.g. Coolify's), see Use an existing Traefik (external mode).
| Variable | Default | Purpose |
|---|---|---|
XCIND_HOOKS_GENERATE |
(built-ins: naming, app, app-env, host-gateway, proxy, assigned, workspace, discovery) | Hooks that emit compose overlay files |
XCIND_HOOKS_EXECUTE |
(built-ins: proxy-execute, workspace-execute, hostenv-execute) | Hooks that run preconditions every invocation |
XCIND_HOST_GATEWAY_ENABLED |
1 |
Disable the host-gateway hook for this app |
XCIND_HOST_GATEWAY |
(auto-detected) | Override the detected host-gateway value |
XCIND_HOOKS_TTL |
5 |
Seconds that xcind-config resolve can reuse a completed cache-refresh leg; 0 disables reuse |
Walkthrough: Author custom hooks, host-gateway.
| Variable | Default | Purpose |
|---|---|---|
XCIND_BINS |
() |
Per-service commands for xcind-run and IDE integration. Entry: name:service[;cmd=…][;use=exec|run][;desc=…]. The name __default declares the fallback for unknown xcind-run names; there cmd is a prefix and defaults to empty |
XCIND_SCRIPTS |
() |
Named step lists for xcind-run. Entry: name: followed by steps, one per line |
Walkthroughs: Bins and scripts, IDE and tool integration.
| Variable | Purpose |
|---|---|
XCIND_BAKE_FILES |
Docker Bake file patterns; tracked in xcind-config --json, not yet passed to docker compose |
XCIND_NO_REGISTRY |
When set (non-empty), skip the automatic workspace-registry write during discovery — for read-only callers that must not mutate shared state. Discovery and all XCIND_* resolution are unaffected. |
XCIND_DEBUG |
Set to 1 to enable trace logging of file resolution and hook execution |
URL / router templates (XCIND_*_TEMPLATE) |
Customize generated hostnames and Traefik router names |
For the full list of templates and their placeholders, see engineering/reference/configuration.md.
Full detail: engineering/reference/configuration.md — every XCIND_* variable, including templates, internal flags, and the exact override-resolution algorithm.