Configuration Reference

Configuration file location: ~/.config/jailoc/config.toml

The file is auto-created with defaults on first run. All fields are optional unless noted.

[base]

Global base image settings. Controls the fallback image used when no workspace-level image is set.

Example

[base]
dockerfile = "https://example.com/Dockerfiles/custom"

Or with a local Dockerfile:

[base]
dockerfile = "/opt/myorg/base.Dockerfile"

[defaults]

Global defaults applied to all workspaces. All fields are optional and default to empty.

Example

[defaults]
image = "ubuntu:22.04"
env = ["GOPRIVATE=*.example.com", "NPM_REGISTRY=https://npm.example.com"]
env_file = ["~/.config/jailoc/shared.env"]
allowed_hosts = ["internal-registry.example.com"]
allowed_networks = ["10.0.0.0/8"]

[workspaces.<name>]

Each workspace is declared as a TOML table under [workspaces], keyed by name.

Workspace name constraints: must match ^[a-z0-9-]+$ (lowercase letters, digits, and hyphens only).

Example

[workspaces.my-project]
paths = ["~/projects/my-project", "~/shared/libs"]
allowed_hosts = ["api.example.com", "pypi.org"]
allowed_networks = ["10.0.0.0/8"]
build_context = "~/projects/my-project/docker"
mode = "remote"
dockerfile = "~/projects/my-project/overlay.Dockerfile"

Validation Rules

Workspace names

Must match the regular expression ^[a-z0-9-]+$. Names containing uppercase letters, underscores, or other special characters are rejected.

paths

Each entry is validated against a list of forbidden path prefixes. Paths starting with any of the following are rejected:

~ is expanded to $HOME before validation. HTTP(S) URLs in dockerfile fields are not subject to ~ expansion; local paths starting with ~ are expanded.

allowed_networks

Each entry must be a valid CIDR notation string as accepted by Go's net.ParseCIDR. Invalid CIDR values are rejected at config load time.

Workspace image

The workspace image field is mutually exclusive with dockerfile and build_context. The following combinations are rejected at config load time:

• image set together with dockerfile
• image set together with build_context

dockerfile fields

Accepted values:

• Absolute local paths: must start with / (e.g. /opt/my.Dockerfile)
• Tilde paths: must start with ~ (e.g. ~/my.Dockerfile); ~ is expanded to $HOME before use
• HTTP(S) URLs: must have an http or https scheme and a non-empty host component. Paths like http:///path are rejected.

Relative paths and other URL schemes (e.g. ftp://, file://) are not accepted.

env

Each entry must be in KEY=VALUE format (key cannot be empty, must contain =). The following keys are reserved and cannot be set by users:

env_file

Each path must be absolute (starting with /) or start with ~ (expanded to $HOME). Files must exist at config load time. The file format is Docker .env compatible:

• Lines in KEY=VALUE format
• Lines starting with # are comments
• Empty lines are ignored
• Values may be quoted (KEY="value with spaces")
• Inline comments after values are stripped

Values are treated as literal strings — no host environment variable expansion is performed.

Merge semantics

Environment variables from multiple sources are merged in this order (later entries win for the same key):

1. [defaults].env — global inline values
2. [defaults].env_file — global file values (in list order)
3. Workspace env_file — per-workspace file values (in list order)
4. Workspace env — per-workspace inline values (highest priority)

allowed_hosts and allowed_networks use union deduplication: the global list is merged with the workspace list, with duplicates removed, preserving order.

Port Allocation

Each workspace is assigned a fixed host port based on the alphabetical sort order of all configured workspace names:

port = 4096 + index

Where index is the zero-based position of the workspace name when all workspace names are sorted alphabetically.

Port assignments shift when workspace names are added or removed. Run jailoc status to see current assignments.

See the workspace configuration how-to for step-by-step setup instructions.