Status: Draft
This document is the authoritative reference for all Scind configuration files, their schemas, and their locations.
Scind uses three schema types, separating structure (configuration) from state (runtime):
| Aspect | Structure (config) | State (runtime) |
|---|---|---|
| Proxy settings | proxy.yaml |
- |
| Port assignments | - | ~/.config/scind/state.yaml |
| What apps exist | workspace.yaml |
- |
| Available flavors | application.yaml |
- |
| Active flavor | - | .generated/state.yaml or CLI |
| Active branch | - | git working directory |
| Running containers | - | Docker |
| File | Field | Requirement |
|---|---|---|
workspace.yaml |
workspace.name |
Required, must be valid DNS label |
proxy.yaml |
proxy.domain |
Required, must be valid domain |
application.yaml |
exported_services |
At least one exported service required |
| Type | Pattern | Example |
|---|---|---|
| Workspace names | Lowercase alphanumeric with hyphens, valid DNS label | dev, feature-x, pr-123 |
| Application names | Lowercase alphanumeric with hyphens, inferred from directory | frontend, shared-db |
| Exported service names | Lowercase alphanumeric with hyphens | web, api, db |
| Field | Constraint |
|---|---|
| Port numbers | 1-65535 |
tls.mode |
One of: auto, custom, disabled |
visibility |
One of: public, protected |
port.type |
One of: proxied, assigned |
protocol (for proxied) |
One of: http, https |
Scind configuration files use YAML format exclusively. TOML is not supported.
Scind does not support environment variable overrides for configuration values. Configuration must be set in the appropriate YAML files:
~/.config/scind/proxy.yamlfor proxy settings{workspace}/workspace.yamlfor workspace settings{application}/application.yamlfor application settings
Environment variables prefixed with SCIND_ (e.g., SCIND_FRONTEND_WEB_HOST) are generated by Scind for service discovery within containers. They are injected into application containers, not read by Scind itself.
| File | Location | Scope | Purpose |
|---|---|---|---|
proxy.yaml |
~/.config/scind/proxy.yaml |
Global | Proxy domain, TLS, dashboard settings |
state.yaml |
~/.config/scind/state.yaml |
Global | Port assignments, port inventory |
workspaces.yaml |
~/.config/scind/workspaces.yaml |
Global | Workspace registry |
workspace.yaml |
{workspace}/workspace.yaml |
Per-workspace | Workspace definition, applications |
application.yaml |
{app}/application.yaml |
Per-application | Flavors, exported services |
state.yaml |
{workspace}/.generated/state.yaml |
Per-workspace | Active flavors (runtime) |
manifest.yaml |
{workspace}/.generated/manifest.yaml |
Per-workspace | Computed values (read-only) |
Location: ~/.config/scind/proxy.yaml (global/per-user)
proxy:
domain: scind.test # TLD for generated hostnames
mode: managed # managed | external (default: managed)
auto_start: true # Start the proxy on `up` when needed (default: true)
network: scind-proxy # Shared Docker network apps join (default: scind-proxy)
http_entrypoint: web # Traefik entrypoint name for HTTP (default: web)
https_entrypoint: websecure # Traefik entrypoint name for HTTPS (default: websecure)
certresolver: "" # ACME resolver named on HTTPS routers (default: empty)
traefik_image: traefik:v3.2.3 # Traefik Docker image (defaults to pinned version)
http_port: 80 # Host port for the HTTP entrypoint (default: 80)
https_port: 443 # Host port for the HTTPS entrypoint (default: 443)
dashboard:
enabled: true # Enable/disable Traefik dashboard (default: true)
port: 8080 # Dashboard host port (default: 8080)
# Future: password support via environment variable
tls:
mode: auto # auto | custom | disabled
# For mode: custom (e.g., enterprise CA certificates)
cert_file: ~/.config/scind/certs/wildcard.crt
key_file: ~/.config/scind/certs/wildcard.keymode selects who owns the proxy. It defaults to managed, which is the behavior described throughout this document.
| Field | Type | Default | Description |
|---|---|---|---|
proxy.mode |
string | managed |
Proxy ownership: managed (Scind runs Traefik) or external (a foreign proxy already owns 80/443) |
Under mode: external, Scind never starts, stops, or configures a proxy. Applications join the network named by proxy.network and emit router labels tuned for the host proxy through proxy.http_entrypoint, proxy.https_entrypoint, and proxy.certresolver. See ADR-0017: External Proxy Mode and Proxy Infrastructure — External Proxy Mode.
scind config set proxy.mode externalThese fields determine the network Scind attaches applications to and the values it writes into generated Traefik labels. They are meaningful in both modes — the managed defaults reproduce Scind's historical output exactly — and they are the entire configuration surface for making a foreign Traefik a drop-in consumer.
| Field | Type | Default | Description |
|---|---|---|---|
proxy.network |
string | scind-proxy |
Shared Docker network that exported containers join, and the value of traefik.docker.network |
proxy.http_entrypoint |
string | web |
Traefik entrypoint name used by HTTP routers |
proxy.https_entrypoint |
string | websecure |
Traefik entrypoint name used by HTTPS routers |
proxy.certresolver |
string | (empty) | When set, traefik.http.routers.{name}.tls.certresolver={value} is appended to every HTTPS router (per-export and apex), regardless of proxy mode |
Under mode: external, proxy.network points at the network the host proxy already lives on, and the entrypoint names must match the ones that proxy defines.
auto_start controls whether scind up starts the shared proxy as a side effect. It defaults to true.
| Field | Type | Default | Description |
|---|---|---|---|
proxy.auto_start |
boolean | true |
Start the proxy container during up when a proxied export needs it |
Even with auto_start: true, the proxy container starts only when at least one application in the invocation declares a proxied export — an assigned-ports-only up starts nothing. The scind-proxy network is ensured in every case, because generated overrides declare it external: true.
Set auto_start: false when you run Traefik yourself. Scind then ensures the network, never starts the container, and — if proxied exports are present with no proxy running — warns and continues instead of failing up. Start the proxy explicitly with scind proxy up. This is distinct from mode: external: auto_start: false means "you run the proxy yourself, Scind's routing values still apply", while mode: external means "a foreign proxy owns routing, Scind's label values are retargeted at it".
auto_start lives in proxy.yaml, which is a global (per-user) file, so it applies uniformly across every workspace on the machine — there is no per-workspace override. A user who wants the auto-start behavior in one workspace but not another sets auto_start: false globally and runs scind proxy up by hand in the workspace that wants it, rather than toggling the field per workspace.
See Workspace Lifecycle — Proxy Start Conditions.
http_port, https_port, and dashboard.port set the host ports the shared proxy binds (defaults 80/443/8080). These exist so the proxy can run on machines where 80/443 are already occupied (a common dev situation) without editing generated files. They are also settable via the environment variables SCIND_PROXY_HTTP_PORT, SCIND_PROXY_HTTPS_PORT, and SCIND_PROXY_DASHBOARD_PORT.
When an entrypoint runs on a non-default port, service-discovery values reflect it: the proxied _PORT carries the non-default port and _URL includes it (e.g., https://dev-frontend-web.scind.test:8443). Standard ports (80/443) are omitted from _URL as usual. See Environment Variables — Configurable Proxy Host Ports.
| Mode | Behavior |
|---|---|
auto |
Uses mkcert if available to generate locally-trusted certificates; falls back to Traefik's default self-signed certificate (browser warnings) |
custom |
Uses user-provided certificate and key files (for enterprise CA or manually generated certs) |
disabled |
HTTP only, no HTTPS entrypoint (not recommended for production-like testing) |
- auto with mkcert: Run
mkcert -installonce per machine to add the local CA to your trust store, thenmkcert "*.scind.test"to generate a wildcard certificate. Scind will detect and use these automatically. - custom (enterprise CA): Obtain a wildcard certificate signed by your enterprise CA for
*.scind.test(or your configured domain). Place the cert and key files at the configured paths. - auto without mkcert: Traefik serves its default self-signed certificate. Browsers will show security warnings.
Location: ~/.config/scind/proxy/ (global/per-user)
The proxy is implemented as a Docker Compose project managed by Scind. It runs a Traefik instance that handles reverse proxying for all workspaces on the host.
Created by scind proxy init:
~/.config/scind/proxy/
├── docker-compose.yaml # Traefik service definition
├── traefik.yaml # Traefik static configuration
├── dynamic/ # Dynamic configuration (auto-discovered)
│ └── tls.yaml # TLS certificate configuration (generated)
└── certs/ # TLS certificates (copied or generated here)
name: scind-proxy
services:
traefik:
image: ${TRAEFIK_IMAGE:-traefik:v3.2.3} # Configurable via proxy.yaml
command:
- "--configFile=/etc/traefik/traefik.yaml"
- "--api.dashboard=true" # Set to false if dashboard.enabled: false
ports:
- "80:80" # Host port from proxy.http_port
- "443:443" # Host port from proxy.https_port
- "8080:8080" # Only included if dashboard.enabled: true (port from dashboard.port)
volumes:
- /var/run/docker.sock:/var/run/docker.sock:ro
- ./traefik.yaml:/etc/traefik/traefik.yaml:ro
- ./dynamic:/etc/traefik/dynamic:ro
- ./certs:/etc/traefik/certs:ro
networks:
- scind-proxy # from proxy.network
restart: unless-stopped
labels:
- "scind.managed=true"
- "scind.component=proxy"
networks:
scind-proxy: # from proxy.network
external: trueapi:
dashboard: true # Set based on proxy.yaml dashboard.enabled (default: true)
insecure: true # Dashboard rides Traefik's built-in insecure-API listener
entryPoints:
web: # name from proxy.http_entrypoint
address: ":80" # port from proxy.http_port
websecure: # name from proxy.https_entrypoint
address: ":443" # port from proxy.https_port
providers:
docker:
exposedByDefault: false
network: scind-proxy # from proxy.network
file:
directory: /etc/traefik/dynamic
watch: trueThe dashboard has no entrypoint of its own — enabling it adds the api block above, the --api.dashboard=true command flag, and a host publish of proxy.dashboard.port. Both generated files are produced only under mode: managed; under mode: external none of the settings that shape them (image, host ports, dashboard, entrypoint addresses) have any effect.
Commands: proxy init, proxy up, proxy down, proxy destroy. The proxy starts automatically with workspace up if needed.
See Configuration Schemas - Proxy Behavior for lifecycle details and recovery procedures.
Location: ~/.config/scind/workspaces.yaml (global/per-user)
This file tracks all known workspaces across the system, enabling workspace list and preventing workspace name collisions.
# AUTO-GENERATED - Managed by Scind
# Records known workspaces and their locations
workspaces:
dev:
path: /home/user/workspaces/dev
registered_at: 2024-12-28T10:30:00Z
last_seen: 2024-12-29T14:22:00Z
review:
path: /home/user/workspaces/review
registered_at: 2024-12-28T11:00:00Z
last_seen: 2024-12-29T13:15:00Z
myapp-dev:
path: /home/user/projects/myapp
registered_at: 2024-12-29T09:00:00Z
last_seen: 2024-12-29T14:30:00ZManaged by workspace init, workspace list, and workspace prune commands.
See Configuration Schemas - Workspace Registry Behavior for registration rules and fallback recovery.
Location: ~/.config/scind/state.yaml (global/per-user)
This file tracks port assignments for assigned type ports across all workspaces, plus an inventory of port availability for garbage collection and debugging.
# AUTO-GENERATED - Managed by Scind
# Records assigned ports and port availability inventory
assigned_ports:
dev: # Workspace name
frontend: # Application name
web: 8080 # Exported service: assigned host port
backend:
api: 3000
worker: 9000
shared-db:
db: 5432
cache: 6379
review:
frontend:
web: 8081 # Different workspace, different port
port_inventory:
5432:
status: assigned # assigned | unavailable | released
first_seen: 2025-12-28T17:53:55Z
last_checked: 2025-12-29T13:01:33Z
assignment: # Present only if status=assigned
workspace: dev
application: shared-db
exported_service: db
6379:
status: assigned
first_seen: 2025-12-28T17:53:58Z
last_checked: 2025-12-29T13:01:37Z
assignment:
workspace: dev
application: shared-db
exported_service: cache
5434:
status: unavailable # External process using this port
first_seen: 2025-12-28T17:54:00Z
last_checked: 2025-12-29T13:01:40Z
# No assignment - taken by external processPorts use incremental allocation with sticky assignments. Status values: assigned, unavailable, released.
See Configuration Schemas - Port Assignment Behavior for the assignment algorithm, conflict handling, and status transitions.
Location: {workspace}/workspace.yaml
workspace:
name: dev # Required. Used as prefix for project names and hostnames
# network: dev-custom # Optional. Defaults to {name}-internal
applications:
frontend:
repository: git@github.com:company/frontend.git # Optional. For initial cloning
backend:
repository: git@github.com:company/backend.git
shared-db:
repository: git@github.com:company/shared-db.git
path: ./database # Optional. Defaults to ./{app-name}; may also be
# absolute or point outside the workspace treeworkspace:
name: dev
applications:
myapp:
path: . # Application in workspace root directoryapplications.{name}.path MAY be absolute, or relative and pointing outside the workspace tree. This lets a repository that already lives elsewhere on disk join a workspace without being moved or symlinked into it:
workspace:
name: dev
applications:
frontend: {} # ./frontend — the conventional case
shared-db:
path: ~/src/shared-db # Absolute: application lives outside the workspace
legacy:
path: ../legacy-api # Relative, resolved from the workspace rootMembership still runs one direction: the workspace enumerates its applications. An external application is a member because workspace.yaml lists it, not because it declares anything about itself, so workspace up, the generated manifest, and roster validation all keep a complete and authoritative roster.
Targeting external applications: Context detection never traverses above the workspace root, so standing in an external application's directory does not detect the workspace or the application. Target them explicitly instead:
scind app up --workspace=dev --app=shared-dbThe -w/-a flags of ADR-0011 already cover every command, so no new mechanism is needed. Two consequences follow from the path leaving the workspace tree:
- Path resolution: relative paths resolve from the workspace root;
~expands to the user's home directory. Scind records the resolved absolute path in thescind.app.pathDocker label as usual. - Portability: an absolute or outside-the-tree path is machine-specific, so a
workspace.yamlthat uses one is not portable between machines the way a conventional./{app}path is. Prefer the conventional form unless the application genuinely cannot live in the workspace directory.
- Application name = directory path (e.g.,
frontend→./{workspace}/frontend/) - Network name defaults to
{workspace.name}-internal
Note: Branch (ref) and flavor are runtime state, not configuration.
Scind uses template variables to generate hostnames, aliases, and other computed values. Templates can be customized at the workspace level.
Built-in defaults:
workspace:
name: dev
templates:
# Public hostname pattern
hostname: "%WORKSPACE_NAME%-%APPLICATION_NAME%-%EXPORTED_SERVICE%.%PROXY_DOMAIN%"
# Internal network alias pattern
alias: "%APPLICATION_NAME%-%EXPORTED_SERVICE%"
# Docker Compose project name
project-name: "%WORKSPACE_NAME%-%APPLICATION_NAME%"
# Apex templates (for primary exported service)
hostname-apex: "%WORKSPACE_NAME%-%APPLICATION_NAME%.%PROXY_DOMAIN%"
alias-apex: "%APPLICATION_NAME%"| Variable | Scope | Description | Example |
|---|---|---|---|
%PROXY_DOMAIN% |
Proxy | Domain from proxy.yaml |
scind.test |
%WORKSPACE_NAME% |
Workspace | Workspace name | dev |
%WORKSPACE_NETWORK% |
Workspace | Internal network name | dev-internal |
%APPLICATION_NAME% |
Application | Application identifier | frontend |
%APPLICATION_FLAVOR% |
Application | Resolved flavor | default |
%EXPORTED_SERVICE% |
Export | Key from exported_services |
web-debug |
%SERVICE_NAME% |
Export | Underlying Compose service | web |
%SERVICE_PORT% |
Export | Container port number (see note) | 8080 |
%SERVICE_PROTOCOL% |
Export | Protocol (for proxied) | https |
Note on %SERVICE_PORT%: This variable provides the container's internal port number. While not used in the default templates, it's available for advanced customization such as adding debugging labels or custom routing rules that need to reference the original container port (e.g., scind.debug.port=%SERVICE_PORT%).
Apex template note: The hostname-apex and alias-apex templates intentionally exclude %EXPORTED_SERVICE% — it is not available in apex template resolution context. Referencing it in an apex template will produce an empty string.
Variables are resolved at generation time and written into override files.
See Configuration Schemas - Template Resolution Behavior for resolution timing, flavor change handling, and running application considerations.
Location: {application}/application.yaml (lives in the application's git repository)
This file defines the application's exported services and flavors. The application name is inferred from the directory name.
default_flavor: full # Optional. Defaults to "default" if not specified
apex: true # Optional. Defaults to true; false disables the apex entirely
flavors:
lite:
compose_files:
- docker-compose.yaml
full:
compose_files:
- docker-compose.yaml
- docker-compose.worker.yaml
- docker-compose.extras.yaml
exported_services:
web:
ports:
- type: proxied
protocol: https
visibility: public
- type: proxied
protocol: http
visibility: protected
api:
ports:
- type: proxied
protocol: https
visibility: public
worker:
ports:
- type: assigned
port: 9000
visibility: protectedEach key in exported_services is the "exported service name" used for hostname generation, network aliases, and environment variables. By default, this key maps to a Compose service of the same name.
Mapping to a different Compose service: Use the service: property when the exported name differs from the Compose service name:
exported_services:
db:
service: postgres # Maps to Compose service "postgres", exported as "db"
ports:
- type: assigned
port: 5432
visibility: protectedEach exported service declares one or more ports:
ports:
- type: proxied # Required: proxied or assigned
protocol: https # Required for proxied: http, https, or future SNI types
port: 8080 # Optional: container port (see inference rules below)
visibility: public # Optional: public or protected (documentation only)Port type constraints:
- Each exported service may have at most one
httpand onehttpsproxied port - Each exported service may have multiple
assignedports - If an exported service needs more than one http or https proxy mapping, create separate exported services
Port inference rules:
- If the Compose service has exactly one port in its
ports:configuration, that port is used as the default - If the Compose service has multiple ports,
port:must be explicitly specified - For Compose port mappings like
"80:8080", the container port (8080) is used
flavors and compose_files are optional. When an application.yaml declares neither and the active flavor is the literal default (i.e., default_flavor is unset or set to default), that flavor resolves to the conventional Compose file names, filtered to those that exist, in this order:
compose.yamlcompose.ymldocker-compose.yamldocker-compose.yml
The default env file is .env, also existence-filtered, applied as compose_env_files (interpolation scope — the same scope docker compose gives .env).
This mirrors what docker compose itself does with no -f flag, so the behavior an application already has under plain Compose is the behavior it keeps under Scind. Requiring a declaration that only restates the platform convention is ceremony, not safety.
The default applies only in the absence of any declaration. The moment flavors or compose_files appears, it governs completely — there is no merging of defaults into a declared list, and no per-flavor fallback. A flavor that declares an empty or wrong list fails as it does today. A non-default active flavor with no declaration (for example, default_flavor: full with no flavors: block) fails rather than falling back to convention defaults. The failure is its own error — the flavor was never declared, so there is no file list to report as missing:
Error: Application "backend" has no flavor named "full"
Application: backend
Active flavor "full" came from: default_flavor in application.yaml
Declared flavors: none
Declare the flavor in application.yaml, or remove default_flavor to use
the conventional compose files (compose.yaml, docker-compose.yaml, …).
The active flavor can arrive from --flavor, .generated/state.yaml, or default_flavor, so the error names its source — the fix differs for each. See CLI Error Messages — Active Flavor Not Declared.
No candidate exists: if an application declares nothing and none of the four candidate files is present, generation fails with an error naming the convention:
Error: No compose file found for application "frontend"
Application declares no flavors or compose_files, so Scind looked for:
compose.yaml, compose.yml, docker-compose.yaml, docker-compose.yml
None exist in /Users/beau/workspaces/dev/frontend
Declare compose_files in application.yaml, or add one of the files above.
scind app show and scind app diagnose report the resolved compose file list and mark it as convention-derived, so an application that declares nothing still describes itself when asked.
Adopted from the Xcind proof-of-concept, which specifies the same candidate set and override behavior.
Applications may declare dotenv files at the application level. Scind exposes two distinct fields because Docker Compose has two separate, easily-confused env-file scopes:
# application.yaml
compose_env_files: # Optional. Interpolation-only (--env-file)
- .env.compose
app_env_files: # Optional. Injected into every container (env_file:)
- .env.app| Field | Maps to | Scope | Effect |
|---|---|---|---|
compose_env_files |
Compose --env-file |
Build/parse time | Provides values for ${VAR} interpolation of the Compose YAML only. Does not enter running containers. |
app_env_files |
env_file: on every generated service |
Runtime | Generates an env_file: entry on every service in the generated override, making the variables available inside running containers. |
The two-scope distinction (common pitfall): --env-file and env_file: sound interchangeable but are not. --env-file feeds Compose's own variable substitution when it reads the YAML — it never reaches container processes. env_file: is a per-service list of files whose contents Compose loads into that service's environment at runtime — it never affects YAML interpolation. A value needed for both purposes must be listed in both fields.
Scind currently has no other application-level dotenv concept; these fields fill that gap. This split was validated by the Xcind proof-of-concept.
The primary field designates which exported service receives the apex URL:
exported_services:
web:
primary: true
ports:
- type: proxied
protocol: https
visibility: public| Field | Type | Default | Description |
|---|---|---|---|
primary |
boolean | false |
Designates this export as the application's primary service |
Rules:
Apex hostnames only ever apply to proxied exports, so implicit-primary eligibility is scoped to proxied exports. Assigned exports never count toward apex eligibility (they have no hostname):
- Exactly one proxied export: implicitly primary, apex-eligible (no annotation needed). Assigned exports alongside it are ignored for this determination — a
web(proxied) +db(assigned) app gets an apex with zero annotation. - Multiple proxied exports + one
primary: true: that export gets the apex. - Multiple proxied exports + none marked primary: fall back to positional selection — the first-declared proxied export gets the apex (an apex is still emitted). Explicit
primary: trueis required only to override this default when 2+ proxied exports compete. - More than one
primary: true: validation error.
The primary export receives additional apex hostname, alias, Traefik routing, Docker labels, and environment variables. An assigned export may still be marked primary: true to receive the apex internal alias (only) — but it is never apex-eligible implicitly and never receives an apex hostname.
Opting out of the apex: The application-level apex field turns apex generation off for the whole application:
# application.yaml
apex: false # Optional. Default: true| Field | Type | Default | Description |
|---|---|---|---|
apex |
boolean | true |
When false, the application produces no apex at all |
With apex: false Scind generates no apex hostname, no apex internal alias, no apex Traefik router, no scind.apex.* labels, and no SCIND_{APP}_APEX_* variables; apex and apex_host are null in --json output and scind urls shows no apex URL for the application. The field is application-level because an application has exactly one apex. Combining apex: false with an export marked primary: true is allowed, not an error — the opt-out wins and the designation produces nothing apex-related; under apex: false the primary: true designation has no observable effect.
See ADR-0013 for the hybrid (explicit-then-positional) selection rationale, the ordering requirement it implies for exported_services, and the opt-out rationale.
Simple web service (single port in Compose, inferred):
# docker-compose.yaml
services:
web:
ports:
- "8080"# application.yaml
exported_services:
web:
ports:
- type: proxied
protocol: https
visibility: publicResult: HTTPS proxy to container port 8080. Environment variables will use proxy port 443.
Database with direct port (assigned port, auto-assigned if unavailable):
# application.yaml
exported_services:
db:
service: mysql
ports:
- type: assigned
port: 3306
visibility: protectedService with both proxy and direct ports:
# application.yaml
exported_services:
web:
ports:
- type: proxied
protocol: https
port: 443
visibility: public
- type: proxied
protocol: http
port: 80
visibility: protected
- type: assigned
port: 9229
visibility: protected # Node.js debug portFor complete configuration examples, see appendices/configuration/complete-examples.md.
Location: {workspace}/.generated/state.yaml (gitignored)
Runtime state is tracked separately from configuration. State represents explicit choices made by the user (e.g., which flavor to use), not computed values.
# AUTO-GENERATED - Managed by workspace tooling
applications:
frontend:
flavor: full
backend:
flavor: lite # Overridden from defaultResolution order: CLI flag → state file → default_flavor → "default".
See Configuration Schemas - Flavor Resolution Order for full details.
Location: {workspace}/.generated/manifest.yaml (gitignored)
The manifest is a computed, read-only view of the workspace's current state. It captures all resolved values (hostnames, aliases, environment variables) derived from configuration and state. This serves several purposes:
- Discoverability: Humans and tools can inspect one file to understand the workspace topology
- Tool integration: Dashboards, DNS updaters, or service discovery tools can consume this structured data
- Debugging: Inspect computed hostnames and environment variables without reconstructing from templates
- At-rest integration: The manifest is the one topology surface readable without Docker running and without invoking Scind
The manifest is an output, never a staleness input — regeneration is decided by mtime comparison against source files, not by comparing the manifest against configuration.
# AUTO-GENERATED - Computed from configuration and state
# Generated: 2024-12-27T10:30:00Z
workspace:
name: dev
network: dev-internal
proxy:
domain: scind.test
applications:
frontend:
flavor: full
project: dev-frontend
exported_services:
web:
service: web # Underlying Compose service
alias: frontend-web # Internal network alias
ports:
- type: proxied
protocol: https
container_port: 443
visibility: public
hostname: dev-frontend-web.scind.test
environment:
SCIND_FRONTEND_WEB_HOST: dev-frontend-web.scind.test
SCIND_FRONTEND_WEB_PORT: 443
SCIND_FRONTEND_WEB_SCHEME: https
SCIND_FRONTEND_WEB_URL: https://dev-frontend-web.scind.test
SCIND_FRONTEND_WEB_HTTPS_HOST: dev-frontend-web.scind.test
SCIND_FRONTEND_WEB_HTTPS_PORT: 443
SCIND_FRONTEND_WEB_HTTPS_URL: https://dev-frontend-web.scind.test
shared-db:
flavor: default
project: dev-shared-db
exported_services:
db:
service: postgres
alias: shared-db-db
ports:
- type: assigned
container_port: 5432
host_port: 5432
visibility: protected
environment:
SCIND_SHARED_DB_DB_HOST: shared-db-db # In-network alias
SCIND_SHARED_DB_DB_PORT: 5432 # Container port (pairs with _HOST)
SCIND_SHARED_DB_DB_HOST_PORT: 5432 # Host-published port (127.0.0.1 access)Location: {workspace}/.generated/{application-name}.override.yaml
Generated Docker Compose override files wire applications into the Scind infrastructure. These files are regenerated when configuration changes.
# AUTO-GENERATED - Do not edit directly
# Source: workspace.yaml + frontend/application.yaml
# Flavor: full
# Generated: 2024-12-27T10:30:00Z
name: dev-frontend # Explicit project name to prevent conflicts
services:
web:
networks:
dev-internal:
aliases:
- frontend-web
scind-proxy: {} # Connected to proxy for Traefik routing
labels:
# Traefik HTTPS router
- "traefik.enable=true"
- "traefik.http.routers.dev-frontend-web-https.rule=Host(`dev-frontend-web.scind.test`)"
- "traefik.http.routers.dev-frontend-web-https.entrypoints=websecure"
- "traefik.http.routers.dev-frontend-web-https.tls=true"
- "traefik.http.services.dev-frontend-web-https.loadbalancer.server.port=80"
# Scind context labels
- "scind.workspace.name=dev"
- "scind.workspace.path=/home/user/workspaces/dev"
- "scind.app.name=frontend"
- "scind.app.path=/home/user/workspaces/dev/frontend"
# Scind export labels
- "scind.export.web.host=dev-frontend-web.scind.test"
- "scind.export.web.proxy.https.visibility=public"
- "scind.export.web.proxy.https.url=https://dev-frontend-web.scind.test"
environment:
- SCIND_WORKSPACE_NAME=dev
- SCIND_FRONTEND_WEB_HOST=dev-frontend-web.scind.test
- SCIND_FRONTEND_WEB_PORT=443
- SCIND_FRONTEND_WEB_SCHEME=https
- SCIND_FRONTEND_WEB_URL=https://dev-frontend-web.scind.test
# ... additional environment variables ...
networks:
dev-internal:
external: true
scind-proxy:
external: trueLocation: {workspace}/overrides/{application-name}.yaml
Optional files merged after generated overrides for workspace-specific customizations.
# Manual overrides for frontend in dev workspace
services:
web:
environment:
- DEBUG=true
- FEATURE_FLAG_X=enabled
labels:
- "traefik.http.routers.dev-frontend-web-https.middlewares=dev-auth@docker"Preservation guarantee: Files in {workspace}/overrides/ are never modified by Scind. They persist across all regeneration operations, including workspace generate --force.
Merge order: Docker Compose files are merged in this order:
docker compose -f base.yaml -f .generated/app.override.yaml -f overrides/app.yaml
| Type | Protocol | Behavior | Traefik | Environment Variables |
|---|---|---|---|---|
proxied |
https |
HTTPS proxy via Traefik | Yes (HTTPS router) | *_HOST, *_PORT, *_SCHEME, *_URL |
proxied |
http |
HTTP proxy via Traefik | Yes (HTTP router) | *_HOST, *_PORT, *_SCHEME, *_URL |
proxied |
tcp, postgresql, etc. |
SNI-based TCP proxy (future) | Yes (TCP router) | *_HOST, *_PORT |
assigned |
- | Direct port binding, auto-assigned if unavailable | No | *_HOST, *_PORT, *_HOST_PORT |
- proxied: Traffic is routed through Traefik. The exported service gets a hostname (
{workspace}-{app}-{export}.{domain}) and Traefik labels are generated. Environment variables contain the proxy values (hostname and proxy port 80/443), not the container port. - assigned: The port is bound directly to the host. If the specified port is unavailable (used by another workspace or external process), Scind increments until an available port is found and records the assignment in global state. Environment variables expose three values: the internal alias (
_HOST), the container port (_PORT, for in-network access), and the allocated host-published port (_HOST_PORT, for host /host.docker.internalaccess).
Each port can have a visibility of public or protected (defaults to protected if not specified). Visibility is advisory display metadata, not access control — Scind enforces nothing on it, and neither value changes who can reach the port:
- public: This port is intended for external/production use
- protected (default): This port exists for development/debugging but should not be depended on in production
Visibility does not change Scind's core behavior—all exported services receive internal network aliases and environment variables regardless of visibility. Both public and protected proxied services route through Traefik.
private is not a visibility value: a service is private by being absent from exported_services.
Docker label exposure: Visibility is included in the generated Docker labels (scind.export.<name>.proxy.<protocol>.visibility), enabling external tools to distinguish between public and protected services for display or filtering.
All exported services receive environment variables for service discovery.
Environment variables use a SCIND_ prefix to avoid conflicts. Hyphens in names are converted to underscores, and names are uppercased.
Base variables (always generated for each exported service):
SCIND_{APPLICATION}_{EXPORTED_SERVICE}_HOST={hostname_or_alias}
SCIND_{APPLICATION}_{EXPORTED_SERVICE}_PORT={port}
SCIND_{APPLICATION}_{EXPORTED_SERVICE}_HOST_PORT={host_port} # Only for assigned types
SCIND_{APPLICATION}_{EXPORTED_SERVICE}_SCHEME={scheme} # Only for proxied types
SCIND_{APPLICATION}_{EXPORTED_SERVICE}_URL={url} # Only for proxied types
Assigned exports carry three discovery values — _HOST (in-network alias), _PORT (container port), and _HOST_PORT (allocated host-published port) — because the host-published port routinely differs from the container port after a conflict reassignment. See Environment Variables — Assigned-Export Discovery Contract for the full rationale (validated by Xcind ADR-0018).
Protocol-specific variables (generated for each proxied protocol):
SCIND_{APPLICATION}_{EXPORTED_SERVICE}_{PROTOCOL}_HOST={hostname}
SCIND_{APPLICATION}_{EXPORTED_SERVICE}_{PROTOCOL}_PORT={port}
SCIND_{APPLICATION}_{EXPORTED_SERVICE}_{PROTOCOL}_URL={url}
| Type | Protocol | *_HOST |
*_PORT |
*_HOST_PORT |
*_SCHEME |
*_URL |
Protocol Vars |
|---|---|---|---|---|---|---|---|
proxied |
https |
Proxied hostname | 443 | — | https |
Yes | *_HTTPS_* |
proxied |
http |
Proxied hostname | 80 | — | http |
Yes | *_HTTP_* |
proxied |
both | Proxied hostname | 443 | — | https |
Yes | Both |
assigned |
- | Internal alias | Container port | Host-published port | No | No | No |
HTTPS-default rationale: When both HTTP and HTTPS are configured, base variables default to HTTPS (port 443) following security-by-default principles.
// PHP example - using URL directly for proxied services
$apiUrl = getenv('SCIND_BACKEND_API_URL') ?: 'https://backend-api.scind.test';
$response = $httpClient->get("{$apiUrl}/endpoint");
// PHP example - building connection for assigned port services
$dbHost = getenv('SCIND_SHARED_DB_DB_HOST') ?: 'shared-db-db';
$dbPort = getenv('SCIND_SHARED_DB_DB_PORT') ?: '5432';
$dsn = "pgsql:host={$dbHost};port={$dbPort};dbname=app";// Node.js example - using URL directly
const apiUrl = process.env.SCIND_BACKEND_API_URL || 'https://backend-api.scind.test';
const response = await fetch(`${apiUrl}/endpoint`);
// Node.js example - building connection manually
const dbHost = process.env.SCIND_SHARED_DB_DB_HOST || 'shared-db-db';
const dbPort = process.env.SCIND_SHARED_DB_DB_PORT || '5432';Scind uses Docker labels for workspace discovery, service routing, and external tool integration.
Applied to all application containers:
| Label | Description | Example |
|---|---|---|
scind.workspace.name |
Workspace identifier | dev |
scind.workspace.path |
Absolute path to workspace directory | /Users/beau/workspaces/dev |
scind.app.name |
Application identifier | frontend |
scind.app.path |
Absolute path to application directory | /Users/beau/workspaces/dev/frontend |
Proxied exports (HTTP/HTTPS through Traefik):
scind.export.{name}.host={hostname}
scind.export.{name}.proxy.http.visibility={public|protected}
scind.export.{name}.proxy.http.url={url}
scind.export.{name}.proxy.https.visibility={public|protected}
scind.export.{name}.proxy.https.url={url}
Assigned port exports (direct port mapping):
scind.export.{name}.host={hostname}
scind.export.{name}.port.{internal-port}.visibility={public|protected}
scind.export.{name}.port.{internal-port}.assigned={external-port}
| Label | Description | Example |
|---|---|---|
scind.managed |
Indicates Scind manages this container | true |
scind.component |
Component type | proxy |
# Find all Scind-managed containers
docker ps --filter "label=scind.workspace.name" --format "{{.Names}}"
# Find all containers for a specific workspace
docker ps --filter "label=scind.workspace.name=dev" --format "{{.Names}}"
# Get workspace paths for registry reconstruction
docker inspect --format '{{index .Config.Labels "scind.workspace.path"}}' \
$(docker ps -q --filter "label=scind.workspace.name")~/.config/scind/
├── proxy.yaml # Global proxy configuration
├── state.yaml # Global port assignments and inventory
└── workspaces.yaml # Workspace registry
workspaces/
├── proxy/
│ ├── docker-compose.yaml # Traefik service definition
│ ├── traefik.yaml # Traefik static configuration
│ └── .env # Proxy-level environment variables
│
├── dev/ # Workspace root
│ ├── workspace.yaml # Workspace configuration (structure)
│ │
│ ├── overrides/ # Manual overrides (optional)
│ │ └── backend.yaml # Merged after generated config
│ │
│ ├── .generated/ # Generated files (gitignored)
│ │ ├── state.yaml # Runtime state (active flavors)
│ │ ├── manifest.yaml # Computed values (read-only)
│ │ ├── frontend.override.yaml # Generated compose override
│ │ ├── backend.override.yaml
│ │ └── shared-db.override.yaml
│ │
│ ├── frontend/ # Cloned application repository
│ │ ├── docker-compose.yaml # Application's compose file
│ │ ├── application.yaml # Service contract + flavors
│ │ └── ...
│ ├── backend/
│ │ ├── docker-compose.yaml
│ │ ├── docker-compose.worker.yaml
│ │ ├── application.yaml
│ │ └── ...
│ └── shared-db/
│ └── ...
│
├── review/ # Another workspace
│ └── ...
│
└── control/ # Another workspace
└── ...
~/my-project/ # Workspace AND application directory
├── workspace.yaml # workspace.name = "dev"
├── application.yaml # Application service contract
├── docker-compose.yaml # Existing compose file (unchanged)
├── docker-compose.worker.yaml # Optional additional compose files
├── .generated/ # Generated files (gitignored)
│ ├── state.yaml
│ ├── manifest.yaml
│ └── my-project.override.yaml
├── overrides/ # Manual overrides (optional)
└── src/ # Application source code
- Name:
scind-proxy - Scope: Host-level, shared across all workspaces
- Purpose: Connects Traefik to services that need external access
- Created by: Proxy layer setup (once per host)
- Name:
{workspace-name}-internal(e.g.,dev-internal) - Scope: Per-workspace
- Purpose: Enables inter-application communication within a workspace using stable aliases
- Created by:
workspace up(lazy, idempotent—created if not exists)
- Name: Managed by Docker Compose per application
- Scope: Per-application
- Purpose: Internal communication between services within a single application
- Created by: Docker Compose (automatic)
- Workspace names: Lowercase alphanumeric with hyphens (e.g.,
dev,feature-x,pr-123) - Application names: Lowercase alphanumeric with hyphens, inferred from directory name
- Exported service names: The key in
exported_services, may differ from Compose service name - Proxied hostnames:
{workspace}-{application}-{exported_service}.{domain} - Internal aliases:
{application}-{exported_service}(e.g.,frontend-web) - Environment variables:
SCIND_{APPLICATION}_{EXPORTED_SERVICE}_{SUFFIX}in SCREAMING_SNAKE_CASE - Traefik router names:
{workspace}-{application}-{exported_service}-{protocol} - Apex hostnames (proxied primary):
{workspace}-{application}.{domain} - Apex internal aliases (all primary):
{application} - Apex Traefik router names:
{workspace}-{application}-{protocol}
Collision warning: Docker Compose project names, Traefik router names, volume names, and network names are derived from the naming patterns above. Avoid names that could produce ambiguous concatenations.
- Configuration Schemas Spec - Detailed schema specification
- Port Types Spec - Port type behaviors
- Docker Labels Spec - Label conventions
- CLI Reference - Commands that use these configurations
- ADR-0006: Three Configuration Schemas - Design rationale
- ADR-0013: Apex URL Primary Designation - Primary designation design