Xcind is configured through .xcind.sh files — sourceable Bash scripts that set XCIND_* variables.
| Level | File | Purpose |
|---|---|---|
| Global proxy | ~/.config/xcind/proxy/config.sh |
Proxy domain, image, ports |
| Workspace | {workspace}/.xcind.sh |
Workspace-level hooks, domain, settings |
| Application | {app}/.xcind.sh |
App-specific compose files, env files, exports |
When in workspace mode, the workspace .xcind.sh is sourced first, then the application .xcind.sh (which can override workspace settings).
Array of environment file patterns for Docker Compose YAML interpolation. Each file that exists on disk is passed via --env-file to docker compose. These variables are available for ${VAR} substitution in compose files but are not injected into running containers.
Default: (".env")
XCIND_COMPOSE_ENV_FILES=(".env" ".env.local" '.env.${APP_ENV}')Array of environment file patterns to inject into all container services via Docker Compose's env_file: directive. Unlike XCIND_COMPOSE_ENV_FILES, these files are available inside the running containers.
Default: () (empty)
XCIND_APP_ENV_FILES=(".env" ".env.local")Note: It is valid and common to list the same file (e.g.,
.env) in bothXCIND_COMPOSE_ENV_FILESandXCIND_APP_ENV_FILES. This makes.envavailable for both YAML interpolation and inside containers.
Array of additional .xcind.sh-style config file patterns to source after the main .xcind.sh. Paths are resolved relative to the app root. Each file that exists is sourced, along with its .override variant (if present). Supports variable expansion.
Default: () (empty)
XCIND_ADDITIONAL_CONFIG_FILES=('xcind.${APP_ENV}.sh')Override auto-sibling:
.xcind.shitself automatically sources.xcind.override.shif it exists — you do not need to declare.xcind.shin this array. This matches thecompose.yaml→compose.override.yamlconvention. However, environment-specific variants like.xcind.dev.override.shrequire their base (.xcind.dev.sh) to be listed here. In workspace mode, the workspace's.xcind.shalso auto-sources its.xcind.override.shsibling.
Optional subdirectory where compose files live, relative to the app root. If set, compose file patterns are resolved relative to this directory.
Default: (unset — compose files resolve from the app root)
XCIND_COMPOSE_DIR="docker"Array of compose file patterns, relative to XCIND_COMPOSE_DIR (or the app root if XCIND_COMPOSE_DIR is unset). Each file that exists on disk is passed via -f.
Default: ("compose.yaml" "compose.yml" "docker-compose.yaml" "docker-compose.yml")
XCIND_COMPOSE_FILES=(
"compose.common.yaml"
'compose.${APP_ENV}.yaml'
"compose.traefik.yaml"
)Array of Docker Bake file patterns, relative to the app root. Reserved for future use. Currently tracked in xcind-config JSON output but not passed to docker compose.
Default: () (empty)
XCIND_BAKE_FILES=("docker-bake.hcl")Array of bin declarations: per-service commands run by xcind-run and picked up by IDE and plugin integrations. Declared bins appear in the bins object of the xcind-config --json output.
Default: () (empty)
Format: name:service[;key=value[;key=value…]]
| Metadata Key | Default | Description |
|---|---|---|
cmd |
the bin's name | Command inside the container. May contain spaces; tokenized at run time. |
use |
"exec" |
How the bin is invoked: exec (default) attaches to an existing service container; run starts a new one-shot container (run --rm). |
desc |
(omitted) | Description shown by xcind-run --list. Cannot contain ;. |
Validation is strict: a missing colon, an empty name or service, a name starting with @ or - or containing whitespace, an unknown key, a bad use, or a duplicate name is an error.
The name __default is special: it declares the fallback for xcind-run names that match no bin, script, or compose subcommand. Its cmd defaults to empty and acts as a prefix before the dispatched command, not as a command itself. Declaring __default as a script is a load-time error. Like every declared bin, __default appears in the bins object of the JSON output.
XCIND_BINS=(
"php:app"
"npm:app"
"composer:app;cmd=/usr/bin/composer"
"__default:app"
)Changes to XCIND_BINS affect the configuration SHA, triggering cache invalidation.
Array of script declarations: named step lists run by xcind-run. Declared scripts appear in the scripts object of the xcind-config --json output.
Default: () (empty)
Format: name: followed by steps, one per line (a single-line name:step form is allowed).
- Step lines are trimmed; blank lines are skipped.
- A line starting with
#is a comment; the first one is the script's description. - A leading
-marks a step whose failure is ignored (the prefix is kept in the stored step). A bare-is an error. - Name constraints match bins; a name in both
XCIND_BINSandXCIND_SCRIPTSis a load-time error.
XCIND_SCRIPTS=(
"fresh:
# Reinstall node modules from scratch
-rm -rf node_modules
@npm install"
)Changes to XCIND_SCRIPTS affect the configuration SHA, triggering cache invalidation. Step semantics (kinds, $@ splicing, cycle detection) live in docs/guides/bins-and-scripts.md.
Set to 1 in a workspace root's .xcind.sh to mark the directory as a workspace. When xcind discovers an app inside this directory, it sources the workspace .xcind.sh first.
XCIND_IS_WORKSPACE=1Override the application name. The name feeds the naming hook (project name), discovery, assigned-port state, and proxy hostnames, and it is folded into the configuration SHA.
Default: (basename of the application root directory)
XCIND_APP="storefront"Per-worktree isolation token. When set to a non-empty value, it is folded into the Docker Compose project name and the workspace network name so that multiple git worktrees of the same repository do not collide on either:
- Project name:
{workspace}-{instance}-{app}(workspace mode) or{app}-{instance}(workspaceless). - Workspace network:
{workspace}-{instance}-internal.
When empty (the default on a primary checkout), naming is byte-identical to the un-instanced form — no migration is forced on single-worktree users. It does not change the app name or in-network service aliases, only the project and network namespacing. A non-empty value also participates in the generation-cache SHA so worktrees keep separate caches.
Default: (auto-detected — empty on the main checkout; the sanitized linked-worktree name inside a git worktree)
XCIND_INSTANCE="pr-123" # explicit token wins over auto-detectionPrecedence: an explicit XCIND_INSTANCE (environment or .xcind.override.sh)
wins; otherwise it is auto-detected from a linked git worktree unless
XCIND_INSTANCE_AUTO is 0.
Controls git-worktree auto-detection of XCIND_INSTANCE.
Set to 0 to disable auto-detection (an explicit XCIND_INSTANCE still wins).
Default: 1 (enabled)
XCIND_INSTANCE_AUTO=0 # never derive an instance token from the worktreeOpt-in path to a host-view env file that mirrors the injected service-discovery
variables (see Environment Variables) for
processes running on the host rather than inside containers. When set non-empty,
an EXECUTE-phase hook (__xcind-hostenv-execute-hook) writes the host-view
values (assigned exports use their published _HOST_PORT) to this file on every
xcind-compose run. _INTERNAL_* variables and type=unpublished exports are
never written. Relative paths resolve against the app root. jq is required
when the app declares any type=assigned exports.
Default: (unset — the host env file is not written)
XCIND_HOST_ENV_FILE=".env.xcind" # written relative to the app rootHow XCIND_HOST_ENV_FILE is written:
own(default) — xcind fully owns the file and overwrites it each run.block— xcind rewrites only its own managed region, delimited by# >>> xcind >>>…# <<< xcind <<<markers, preserving the rest of the file.
Default: "own"
XCIND_HOST_ENV_MODE="block" # merge into a hand-maintained .env fileThe host-reachable host for type=assigned exports. It sets the assigned
_HOST in the host-view env file and _EXTERNAL_HOST in
both views (see Environment Variables):
loopback(default) —127.0.0.1.hostname— the export's URL-template hostname (XCIND_APP_URL_TEMPLATE). Use it when the proxy domain resolves to the Docker host, for example through wildcard DNS, so the address also works from other machines.
Any other value fails generation.
Default: "loopback"
XCIND_HOST_ENV_ASSIGNED_HOST="hostname" # e.g. dev-shop-db.example.testArray of KEY=template entries that give discovery values app-defined names
(ADR-0025). A template is literal text
plus ${XCIND_NAME} references (NAME matches [A-Z0-9_]+). Xcind expands it
for each view and appends the result after the XCIND_* variables: in the
environment: block of every service in compose.discovery.yaml (container
view), and in the host env file (host view).
Rules:
- Any other
$($NAME,${OTHER},${XCIND_X:-d},$(...), a lone$) is an error. Xcind does no shell evaluation. - A backslash, a backtick, or any control character (including a newline) in an entry is an error.
- A key matches
[A-Za-z_][A-Za-z0-9_]*; a key that starts withXCIND_is an error. - Byte-identical repeated entries are emitted once; the same key with two templates is an error.
- A reference that is missing from one view drops the entry from that view only. A reference that is missing from both views fails with an error that names the entry and the reference.
- Mapped keys override the same key in the app's own
environment:orenv_file:.
Default: ()
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, so the shell that sources the config file does not expand the
references. xcind-config --json reports the raw templates in envMap.
Controls whether the host gateway hook runs. Set to 0 to disable automatic host.docker.internal normalization.
Default: 1 (enabled)
XCIND_HOST_GATEWAY_ENABLED=0 # disable host gateway hookOverride the auto-detected host gateway value. When set, this value is used directly as the extra_hosts target for host.docker.internal without platform detection.
Default: (unset — auto-detect)
XCIND_HOST_GATEWAY="192.168.1.100"The hook also exposes the resolved value inside containers under the same
name, so tools that read a host address from the environment (Xdebug
client_host, for example) can use it directly:
services:
web:
environment:
XCIND_HOST_GATEWAY: "192.168.1.100"A service that sets XCIND_HOST_GATEWAY in its own compose file keeps that
value; the overlay only fills the variable in where it is absent.
The hook writes no overlay at all in two cases: when detection yields an
empty value (Docker Desktop, where host.docker.internal resolves
natively — so no in-container XCIND_HOST_GATEWAY variable is injected
there), and when every service already carries both the extra_hosts
entry and the environment variable.
The host-gateway hook requires
yq. Ifyqis not installed, the hook is skipped with a warning. The hook's generated output is cached by SHA; changes toXCIND_HOST_GATEWAYorXCIND_HOST_GATEWAY_ENABLEDautomatically invalidate the cache.For details on platform detection logic, see the Scind specification for host.docker.internal normalization.
Array of hook function names that generate compose overlay files. Hooks run after file resolution and their output is cached by SHA.
Default: ("xcind-naming-hook" "xcind-app-hook" "xcind-app-env-hook" "xcind-host-gateway-hook" "xcind-proxy-hook" "xcind-assigned-hook" "xcind-workspace-hook" "xcind-discovery-hook")
All built-in hooks are registered automatically. Override to () to disable all generation hooks.
XCIND_HOOKS_GENERATE=() # disable all generation hooksBoth common yq implementations work: mikefarah yq (Go) and kislyuk
yq (Python). When yq is missing at runtime, default-registered hooks behave in one of
two ways: non-load-bearing hooks (xcind-app-hook,
xcind-host-gateway-hook, xcind-workspace-hook, xcind-discovery-hook)
soft-skip with a consolidated warning at the end of the run; hooks with
load-bearing output (xcind-app-env-hook, xcind-proxy-hook,
xcind-assigned-hook) hard-fail the pipeline. See
Hook Lifecycle for the full policy.
Always-run hooks:
xcind-assigned-hookandxcind-discovery-hookare also listed inXCIND_HOOKS_ALWAYS, so on a cache hit they re-run against current live state (assigned host ports) rather than replaying cached stdout. They stay inXCIND_HOOKS_GENERATEfor ordering and completeness.
Array of hook function names that ensure runtime preconditions before docker compose runs. These hooks run on every invocation (not cached) and only apply in xcind-compose, not xcind-config.
Default: ("__xcind-proxy-execute-hook" "__xcind-workspace-execute-hook" "__xcind-hostenv-execute-hook")
XCIND_HOOKS_EXECUTE=() # disable all execute hooksSee Hook Lifecycle for details on all hook phases.
Seconds that xcind-config resolve can reuse a completed cache-refresh
leg before it re-runs hooks. 0 disables reuse. An explicit
--hooks-ttl=N flag overrides this variable. Only the resolve path
honors the TTL.
Default: 5
XCIND_HOOKS_TTL=0 # always refresh on resolveArray of service export declarations. Each entry names an exported service and — via an optional type attribute — chooses how its port is exposed: routing through the shared Traefik proxy (type=proxied, default), reserving a stable host port (type=assigned), or not at all (type=unpublished: discovery variables for containers only).
Default: () (empty)
Format: export_name[=compose_service][:port][;key=value[;key=value…]]
| Metadata Key | Default | Description |
|---|---|---|
type |
"proxied" |
proxied routes traffic through Traefik on a generated hostname. assigned reserves a stable host port, persisted across restarts. unpublished exposes nothing outside Docker; containers get discovery variables only. |
tls |
"auto" |
Per-export TLS behaviour (only meaningful for type=proxied). auto emits both HTTP and HTTPS routers. require emits HTTPS only and redirects HTTP → HTTPS. disable emits HTTP only, even when proxy TLS is enabled. |
Unknown metadata keys, invalid type values, and invalid tls values cause the generation hooks to fail fast. Two entries that produce the same discovery prefix XCIND_{APP}_{EXPORT} (for example one name declared twice with different definitions) also fail; byte-identical repeats are allowed.
When XCIND_PROXY_TLS_MODE=disabled (global), every type=proxied export collapses to HTTP-only regardless of its tls= setting.
XCIND_PROXY_EXPORTS=(
"web" # proxied, service=web, port inferred, tls=auto (http + https)
"api=uvicorn:8080;tls=require" # proxied, https only, http router redirects to https
"legacy:8080;tls=disable" # proxied, http only even when proxy TLS is on
"worker:9000;type=assigned" # assigned, name=worker, service=worker, port 9000
"database=db:3306;type=assigned" # assigned, name=database, service=db, port 3306
"smtp=mailpit:1025;type=unpublished" # unpublished, discovery variables only
)When the port is omitted, it is inferred from the compose service's port mapping (requires exactly one port mapping). When the port is specified explicitly, no compose ports: entry is required — Traefik reaches the container over the shared proxy network (XCIND_PROXY_NETWORK, default xcind-proxy) on the given target port. yq is required whenever XCIND_PROXY_EXPORTS is configured, not only for port inference.
Multiple exports may target the same compose service with different ports, which is useful for attaching additional hostnames to ad-hoc processes running inside a service. For example, to expose a vitest --ui dev server on port 51204 that lives inside an existing app container:
# .xcind.sh (committed)
XCIND_PROXY_EXPORTS=("web=app:3000")
# .xcind.override.sh (local/gitignored) — auto-sourced next to .xcind.sh
XCIND_PROXY_EXPORTS+=("vitest=app:51204")After editing, run xcind-config to regenerate the compose override files, then docker compose up -d to apply the new Traefik labels. The container process must bind 0.0.0.0 (not 127.0.0.1) on the target port so Traefik can reach it; this is a common gotcha for dev servers like Vite/vitest, which default to loopback.
xcind-proxy-hook owns entries with type=proxied and emits compose.proxy.yaml with Traefik routing labels. xcind-assigned-hook owns entries with type=assigned, emits compose.assigned.yaml with host-port mappings, and persists assignments under ${XDG_STATE_HOME:-~/.local/state}/xcind/proxy/assigned-ports.tsv via flock-serialized state.
Controls whether the proxy execute hook automatically starts Traefik when XCIND_PROXY_EXPORTS is configured.
Default: 1 (enabled)
XCIND_PROXY_AUTO_START=0 # disable proxy auto-startDomain suffix for generated proxy hostnames. Can be set in the workspace .xcind.sh or in the global proxy config.
Default: "localhost.scind.io" (a multi-label domain that resolves to loopback; see ADR-0016)
The domain must contain at least one dot. A single-label domain (e.g. bare localhost) makes the wildcard cert *.<domain> untrusted by strict TLS clients (macOS curl/Safari, Go), so xcind-proxy emits an advisory warning when it sees one. localhost.scind.io resolves to 127.0.0.1, so it needs no local DNS configuration while still satisfying the multi-label constraint.
XCIND_PROXY_DOMAIN="dev.localhost.scind.io"These control how hostnames, router names, and network aliases are generated. Defaults are provided for both workspaceless and workspace modes.
| Variable | Default | Used When |
|---|---|---|
XCIND_WORKSPACELESS_APP_URL_TEMPLATE |
{app}-{export}.{domain} |
No workspace |
XCIND_WORKSPACE_APP_URL_TEMPLATE |
{workspace}-{app}-{export}.{domain} |
In workspace |
| Variable | Default | Used When |
|---|---|---|
XCIND_WORKSPACELESS_APP_APEX_URL_TEMPLATE |
{app}.{domain} |
No workspace, primary export |
XCIND_WORKSPACE_APP_APEX_URL_TEMPLATE |
{workspace}-{app}.{domain} |
In workspace, primary export |
Set an apex template to an empty string to disable apex URL generation.
| Variable | Default | Used When |
|---|---|---|
XCIND_WORKSPACELESS_ROUTER_TEMPLATE |
{app}-{export}-{protocol} |
No workspace |
XCIND_WORKSPACE_ROUTER_TEMPLATE |
{workspace}-{app}-{export}-{protocol} |
In workspace |
XCIND_WORKSPACELESS_APEX_ROUTER_TEMPLATE |
{app}-{protocol} |
No workspace, primary export |
XCIND_WORKSPACE_APEX_ROUTER_TEMPLATE |
{workspace}-{app}-{protocol} |
In workspace, primary export |
| Variable | Default | Used When |
|---|---|---|
XCIND_WORKSPACE_SERVICE_TEMPLATE |
{app}-{service} |
Workspace networking aliases |
| Placeholder | Description |
|---|---|
{app} |
Application name (basename of app directory) |
{workspace} |
Workspace name (basename of workspace directory) |
{export} |
Export name from XCIND_PROXY_EXPORTS |
{domain} |
Domain suffix (XCIND_PROXY_DOMAIN) |
{protocol} |
Protocol — http or https depending on which router is being rendered |
{service} |
Compose service name |
For each file pattern, xcind also checks for an .override variant.
Extension-aware insertion — for files with a recognized extension (.yaml, .yml, .json, .hcl, .toml, .sh), .override is inserted before the extension:
| Base File | Override Variant |
|---|---|
compose.yaml |
compose.override.yaml |
compose.common.yaml |
compose.common.override.yaml |
docker-bake.hcl |
docker-bake.override.hcl |
Appended — for all other files (like env files), .override is appended:
| Base File | Override Variant |
|---|---|
.env |
.env.override |
.env.local |
.env.local.override |
Files that don't exist on disk are silently skipped — both the base file and its override variant.
File patterns support shell variable expansion at runtime:
XCIND_COMPOSE_FILES=(
"compose.common.yaml"
'compose.${APP_ENV}.yaml' # Single quotes prevent premature expansion
)With APP_ENV=dev, xcind checks for compose.dev.yaml and compose.dev.override.yaml.
xcind-proxy init creates ~/.config/xcind/proxy/config.sh (generated files in ~/.local/state/xcind/proxy/) with these defaults:
| Variable | Default | Description |
|---|---|---|
XCIND_PROXY_MODE |
"managed" |
managed (xcind runs its own Traefik) or external (an existing host proxy serves the apps) — see ADR-0022 |
XCIND_PROXY_NETWORK |
"xcind-proxy" |
Docker network the proxy and apps share; in external mode, set to the existing proxy's network (e.g. coolify) |
XCIND_PROXY_HTTP_ENTRYPOINT |
"web" |
Entrypoint name used in generated HTTP router labels |
XCIND_PROXY_HTTPS_ENTRYPOINT |
"websecure" |
Entrypoint name used in generated HTTPS router labels |
XCIND_PROXY_CERTRESOLVER |
"" |
When set, adds tls.certresolver=<name> to every HTTPS router (e.g. letsencrypt) |
XCIND_PROXY_DOMAIN |
"localhost.scind.io" |
Domain suffix for hostnames (and wildcard cert *.${XCIND_PROXY_DOMAIN}); must be multi-label — see ADR-0016 |
XCIND_PROXY_IMAGE |
"traefik:v3" |
Traefik Docker image |
XCIND_PROXY_HTTP_PORT |
"80" |
Host port for HTTP traffic |
XCIND_PROXY_TLS_MODE |
"auto" |
TLS mode: auto (mkcert → openssl fallback), custom (user-provided cert), or disabled (HTTP-only) |
XCIND_PROXY_HTTPS_PORT |
"443" |
Host port for HTTPS traffic (ignored when TLS is disabled) |
XCIND_PROXY_TLS_CERT_FILE |
"" |
Absolute path to TLS cert (used only when XCIND_PROXY_TLS_MODE=custom) |
XCIND_PROXY_TLS_KEY_FILE |
"" |
Absolute path to TLS key (used only when XCIND_PROXY_TLS_MODE=custom) |
XCIND_PROXY_DASHBOARD |
"false" |
Enable Traefik dashboard |
XCIND_PROXY_DASHBOARD_PORT |
"8080" |
Dashboard port (if enabled) |
Edit this file to customize the proxy. Run xcind-proxy init again to regenerate all files (existing config values are preserved as defaults).
In auto mode, certificates are provisioned in this order (first hit wins):
- User-provided wildcard at
~/.config/xcind/proxy/certs/wildcard.{crt,key}— always wins; copied into the state cert when newer than the existing state copy - Previously generated state cert for the same domain (fast path, skipped automatically when
XCIND_PROXY_DOMAINchanges) mkcertif available onPATH— produces a locally-trusted wildcard for*.${XCIND_PROXY_DOMAIN}opensslif available onPATH— self-signed wildcard (browser warning, but functional)- Error — install
mkcertoropenssl, provide files at (1), or setXCIND_PROXY_TLS_MODE=disabled
Certificates are written to ~/.local/state/xcind/proxy/certs/wildcard.{crt,key} alongside a domain marker file; changing XCIND_PROXY_DOMAIN triggers regeneration on the next xcind-proxy up.
These are set automatically when workspace mode is active:
| Variable | Value |
|---|---|
XCIND_WORKSPACE |
Basename of the workspace directory |
XCIND_WORKSPACE_ROOT |
Absolute path to the workspace directory |
XCIND_WORKSPACELESS |
0 in workspace mode, 1 otherwise |
An app can also self-declare workspace membership by setting XCIND_WORKSPACE directly in its .xcind.sh. The self-declaration takes effect only when the app is not already inside a workspace directory; otherwise the discovered name wins and xcind warns that the app value was ignored.
These variables are set automatically based on workspace mode and are used internally by hooks. They are not user-configurable — configure the workspace-mode-specific variants above instead.
| Variable | Derived From |
|---|---|
XCIND_APP_URL_TEMPLATE |
XCIND_WORKSPACELESS_APP_URL_TEMPLATE or XCIND_WORKSPACE_APP_URL_TEMPLATE |
XCIND_APP_APEX_URL_TEMPLATE |
XCIND_WORKSPACELESS_APP_APEX_URL_TEMPLATE or XCIND_WORKSPACE_APP_APEX_URL_TEMPLATE |
XCIND_ROUTER_TEMPLATE |
XCIND_WORKSPACELESS_ROUTER_TEMPLATE or XCIND_WORKSPACE_ROUTER_TEMPLATE |
XCIND_APEX_ROUTER_TEMPLATE |
XCIND_WORKSPACELESS_APEX_ROUTER_TEMPLATE or XCIND_WORKSPACE_APEX_ROUTER_TEMPLATE |
The appropriate variant is selected based on whether XCIND_WORKSPACELESS is 1 (workspaceless mode) or 0 (workspace mode).
Replaced by: XCIND_COMPOSE_ENV_FILES
If XCIND_ENV_FILES is set, xcind migrates it to XCIND_COMPOSE_ENV_FILES automatically and prints a deprecation warning. If both are set, XCIND_ENV_FILES takes precedence (with an additional warning).
- CLI Reference — Command usage
- Configuration Schemas Spec — Behavioral rules
- Naming Conventions Spec — How names are generated
- ADR-0006: Three Configuration Schemas — Design rationale