### Start workspace

Source: https://seznam.github.io/jailoc/how-to/secrets

Start or restart the workspace to apply the configuration changes.

```bash
jailoc up my-project
```

--------------------------------

### Start workspace with jailoc up

Source: https://seznam.github.io/jailoc/tutorials/getting-started

Starts the workspace environment in the background using the explicit up subcommand. Useful for scripting lifecycle from CI or starting the workspace and returning later.

```bash
# Start the environment in the background
jailoc up

```

--------------------------------

### Install custom binary from URL

Source: https://seznam.github.io/jailoc/how-to/custom-images

Downloads and installs a pre-built binary from a release URL in a single RUN layer.

```dockerfile
ARG BASE
FROM ${BASE}

RUN curl -fsSL https://github.com/org/tool/releases/download/v1.0/tool-linux-amd64 \
    -o /usr/local/bin/tool \
    && chmod +x /usr/local/bin/tool

```

--------------------------------

### Install jailoc with go install

Source: https://seznam.github.io/jailoc/tutorials/getting-started

Installs the latest jailoc release using Go's install command. Requires Go to be installed and configured on your system.

```bash
go install github.com/seznam/jailoc/cmd/jailoc@v1.18.0

```

--------------------------------

### Install binary from archive

Source: https://seznam.github.io/jailoc/how-to/custom-images

Downloads and extracts an archive containing a tool. For archives that need extraction.

```dockerfile
RUN curl -fsSL https://github.com/org/tool/releases/download/v1.0/tool-linux-amd64.tar.gz \
    | tar -xzf - -C /usr/local/bin tool

```

--------------------------------

### Start Docker daemon on Linux and macOS

Source: https://seznam.github.io/jailoc/how-to/troubleshooting

When 'jailoc up' fails with a Docker connection error, start the Docker daemon. On Linux with systemd, use 'sudo systemctl start docker'; on macOS with Docker Desktop, use 'open -a Docker'. Verify with 'docker info' before retrying.

```bash
# Linux (systemd)
sudo systemctl start docker

# macOS (Docker Desktop)
open -a Docker

```

--------------------------------

### Run first workspace with jailoc

Source: https://seznam.github.io/jailoc/tutorials/getting-started

Runs jailoc without arguments from your project directory to start a sandboxed workspace. On first run, it creates a default config, prompts to add the workspace, starts the opencode and dind containers, and attaches the OpenCode TUI.

```bash
cd ~/myproject
jailoc

```

--------------------------------

### Set a default base image in [defaults]

Source: https://seznam.github.io/jailoc/how-to/custom-images

Configures a pre-built image as the starting point for all workspaces. Workspaces with a dockerfile use this as the BASE build argument, while others use it directly.

```toml
[defaults]
image = "myregistry.example.com/myteam/opencode-base:v1.2.3"
```

--------------------------------

### jailoc up command usage

Source: https://seznam.github.io/jailoc/reference/cli

Starts the Docker Compose environment for the target workspace. No-op if containers are already running.

```bash
jailoc up [flags]

```

--------------------------------

### Check jailoc version

Source: https://seznam.github.io/jailoc/tutorials/getting-started

Confirms that jailoc is installed and accessible on your PATH after installation.

```bash
jailoc --version

```

--------------------------------

### jailoc [defaults] configuration example

Source: https://seznam.github.io/jailoc/reference/configuration

Example of a [defaults] section in a jailoc configuration file. All fields are optional and default to empty. This snippet shows how to set global defaults for all workspaces, including image, environment variables, mounts, firewall rules, and resource limits.

```ini
[defaults]
image = "myregistry.example.com/myteam/opencode-base:v1.2.3"
env = ["GOPRIVATE=*.example.com", "NPM_REGISTRY=https://npm.example.com"]
env_file = ["~/.config/jailoc/shared.env"]
mounts = ["~/.local/share/opencode:/home/agent/.local/share/opencode"]
allowed_hosts = ["internal-registry.example.com"]
allowed_networks = ["10.0.0.0/8"]
ssh_auth_sock = true
git_config = true
enable_docker = true
cpu = 4.0
memory = "8g"
```

--------------------------------

### Define a workspace with a custom dockerfile

Source: https://seznam.github.io/jailoc/how-to/custom-images

Example of a workspace configuration that builds on top of the default base image using a specific overlay Dockerfile.

```toml
[workspaces.myproject]
paths = ["~/projects/myproject"]
dockerfile = "~/projects/myproject/overlay.Dockerfile"
```

--------------------------------

### Check opencode process logs

Source: https://seznam.github.io/jailoc/how-to/troubleshooting

Verify the opencode process started inside the container by checking the workspace logs.

```bash
jailoc logs <workspace>
```

--------------------------------

### Workspace Dockerfile base template

Source: https://seznam.github.io/jailoc/how-to/custom-images

Required beginning of a workspace Dockerfile. Must start with `ARG BASE` and `FROM ${BASE}`. jailoc runs the build with `--build-arg BASE=<resolved-base-tag>` and tags the result as `jailoc-myproject:<content-hash>`.

```dockerfile
ARG BASE
FROM ${BASE}

RUN apt-get update && apt-get install -y --no-install-recommends \
    postgresql-client redis-tools \
    && rm -rf /var/lib/apt/lists/*

```

--------------------------------

### Install packages with apk

Source: https://seznam.github.io/jailoc/how-to/custom-images

Installs packages with apk (Alpine-derived layers) using `--no-cache` to avoid cache layers.

```dockerfile
RUN apk add --no-cache curl jq

```

--------------------------------

### Define multiple workspaces with port allocation

Source: https://seznam.github.io/jailoc/how-to/workspace-configuration

Defines two workspaces, 'api' and 'frontend', each with its own isolated container environment. Ports are assigned starting at 4096, sorted alphabetically by workspace name, so 'api' gets 4096 and 'frontend' gets 4097.

```toml
[workspaces.api]
paths = ["/home/you/projects/api", "/home/you/projects/shared-libs"]

[workspaces.frontend]
paths = ["/home/you/projects/frontend"]

```

--------------------------------

### jailoc command usage

Source: https://seznam.github.io/jailoc/reference/cli

Runs jailoc with optional flags to auto-detect the workspace, start it if not running, and attach to the environment.

```bash
jailoc [flags]

```

--------------------------------

### Allow multiple hostnames with allowed_hosts

Source: https://seznam.github.io/jailoc/how-to/network-access

List multiple hostnames in `allowed_hosts` using a multi-line array. Each hostname is resolved at container start; if a hostname doesn't resolve, its rule is not added.

```ini
[workspaces.api]
paths = ["/home/you/projects/api"]
allowed_hosts = [
  "internal-registry.example.com",
  "internal-mcp.example.com",
]

```

--------------------------------

### Allow a specific hostname with allowed_hosts

Source: https://seznam.github.io/jailoc/how-to/network-access

Add a single hostname to the `allowed_hosts` list in a workspace config. The hostname is resolved to an IP at container start and gets an explicit ACCEPT rule before the catch-all DROP.

```ini
[workspaces.api]
paths = ["/home/you/projects/api"]
allowed_hosts = ["internal-registry.example.com"]

```

--------------------------------

### Allow multiple CIDR ranges with allowed_networks

Source: https://seznam.github.io/jailoc/how-to/network-access

List multiple CIDR ranges in `allowed_networks` using a multi-line array. All listed ranges get ACCEPT rules.

```ini
[workspaces.frontend]
paths = ["/home/you/projects/frontend"]
allowed_networks = [
  "172.20.0.0/16",
  "10.10.5.0/24",
]

```

--------------------------------

### Combine allowed_hosts and allowed_networks

Source: https://seznam.github.io/jailoc/how-to/network-access

Set both `allowed_hosts` and `allowed_networks` on the same workspace. All resolved host IPs and listed CIDRs get ACCEPT rules; everything else in RFC 1918, link-local, and CGNAT ranges is blocked.

```ini
[workspaces.api]
paths = ["/home/you/projects/api"]
allowed_hosts = ["internal-registry.example.com"]
allowed_networks = ["10.10.5.0/24"]

```

--------------------------------

### entrypoint.sh passes secrets to setpriv

Source: https://seznam.github.io/jailoc/explanation/secrets

Used in the environment destination configurations (with from_env or from_file) to start the agent process with the secret environment variables. Runs as root before privileges are dropped, then passes the environment variable array to setpriv, which drops privileges to UID 1000 and disables inheritable capabilities.

```bash
exec setpriv --reuid=1000 --regid=1000 --init-groups --inh-caps=-all --no-new-privs \
    -- env HOME=/home/agent "${secret_envs[@]}" "$@"

```

--------------------------------

### Combine RUN commands into single layer

Source: https://seznam.github.io/jailoc/how-to/custom-images

Combines related RUN commands into a single layer to keep layers small and cache-friendly. Order instructions from least to most volatile, putting package installs before copying project files.

```dockerfile
ARG BASE
FROM ${BASE}

RUN apt-get update && apt-get install -y --no-install-recommends \
    postgresql-client \
    redis-tools \
    build-essential \
    && rm -rf /var/lib/apt/lists/*

```

--------------------------------

### Disable update checks with JAILOC_NO_UPDATE_NOTIFIER

Source: https://seznam.github.io/jailoc/reference/cli

Disables update checks by setting the JAILOC_NO_UPDATE_NOTIFIER environment variable to any non-empty value. The example shows exporting the variable and then running jailoc up.

```bash
export JAILOC_NO_UPDATE_NOTIFIER=1
jailoc up

```

--------------------------------

### Build and Test Commands

Source: https://seznam.github.io/jailoc/development

Standard commands for building the binary, verifying compilation, running tests, and linting the codebase.

```bash
# Build the binary
go build ./cmd/jailoc

# Verify all packages compile (pre-commit)
go build ./...

# Run unit tests
go test ./...

# Run integration tests (requires a running Docker daemon)
go test -tags=integration ./internal/...

# Lint
go vet ./...
golangci-lint run
```

--------------------------------

### Configure a workspace with paths, mounts, and Dockerfile

Source: https://seznam.github.io/jailoc/reference/configuration

Declares a workspace named 'my-project' with bind-mounted paths, allowed hosts and networks, a custom mount, a build context, remote mode, and a Dockerfile overlay. The first path becomes the container's working directory. The 'image' field is mutually exclusive with 'dockerfile' and 'build_context'.

```toml
[workspaces.my-project]
paths = ["~/projects/my-project", "~/shared/libs"]
allowed_hosts = ["api.example.com", "pypi.org"]
allowed_networks = ["10.0.0.0/8"]
mounts = ["~/.local/share/opencode:/home/agent/.local/share/opencode"]
build_context = "~/projects/my-project/docker"
mode = "remote"
dockerfile = "~/projects/my-project/overlay.Dockerfile"
```

--------------------------------

### List and switch Docker contexts

Source: https://seznam.github.io/jailoc/how-to/installation

Commands to list available Docker contexts and switch to a specific runtime, useful when using non-default socket paths like with Colima or Podman.

```bash
# list available contexts
docker context ls

# switch to a specific runtime
docker context use colima

```

--------------------------------

### View container logs for workspace startup

Source: https://seznam.github.io/jailoc/how-to/troubleshooting

Use this command to view container logs when `jailoc up` completes but `jailoc status` shows the workspace is not running. Replace <workspace> with the workspace name.

```bash
# Check container logs for startup errors
jailoc logs <workspace>

```

--------------------------------

### Error Handling Pattern

Source: https://seznam.github.io/jailoc/development

Demonstrates the required practice of wrapping errors with context using fmt.Errorf and %w.

```go
// correct
return fmt.Errorf("resolve workspace: %w", err)

// wrong
return err
```

--------------------------------

### Execute privilege drop with setpriv

Source: https://seznam.github.io/jailoc/explanation/container-architecture

The entrypoint uses setpriv to transition from root to UID/GID 1000, drop all inheritable capabilities, and set the no_new_privs bit.

```bash
setpriv --reuid=1000 --regid=1000 --inh-caps=-all --no-new-privs
```

--------------------------------

### Define a workspace with paths

Source: https://seznam.github.io/jailoc/how-to/workspace-configuration

Defines a workspace named 'default' with a single path. The first path becomes the container's working directory, and all paths are bind-mounted at their original absolute path. The tilde is expanded to the home directory, and paths under system directories are rejected.

```toml
[workspaces.default]
paths = ["/home/you/projects/myproject"]

```

--------------------------------

### Configure Jailoc Workspace

Source: https://seznam.github.io/jailoc/development

Configuration to add to ~/.config/jailoc/config.toml to enable development inside a jailoc container.

```toml
[workspaces.jailoc]
paths = ["/path/to/jailoc"]
dockerfile = "https://raw.githubusercontent.com/seznam/jailoc/main/dev/Dockerfile.jailoc"
```

--------------------------------

### Configure a pre-built image in a workspace

Source: https://seznam.github.io/jailoc/how-to/custom-images

Set the image property in the workspace block to use a pre-built image from a registry, skipping build steps. Note that this cannot be combined with dockerfile or build_context.

```toml
[workspaces.myproject]
paths = ["~/projects/myproject"]
image = "myregistry.example.com/myteam/myapp:v1.2.3"
```

--------------------------------

### Set a tilde path or URL for a custom base Dockerfile

Source: https://seznam.github.io/jailoc/how-to/custom-images

Demonstrates using tilde-expanded paths or remote HTTP(S) URLs for the base Dockerfile configuration.

```toml
[base]
dockerfile = "~/dockerfiles/base.Dockerfile"
# or
dockerfile = "https://git.example.com/team/dockerfiles/-/raw/main/opencode.Dockerfile"
```

--------------------------------

### Share additional paths

Source: https://seznam.github.io/jailoc/how-to/workspace-configuration

Mount additional host directories as read-only to make them available inside the container.

```toml
[defaults]
mounts = ["~/.config/ai-instructions:/home/agent/.config/ai-instructions:ro"]
```

--------------------------------

### jailoc CLI synopsis

Source: https://seznam.github.io/jailoc/reference/cli

Shows the general command structure for jailoc: `jailoc [command] [flags]`.

```bash
jailoc [command] [flags]

```

--------------------------------

### Enable everything at once and override per workspace

Source: https://seznam.github.io/jailoc/how-to/ssh-git-passthrough

Enable SSH agent and Git config forwarding for all workspaces by default, then override both settings for a specific workspace. Workspace-level settings take precedence over defaults.

```ini
[defaults]
ssh_auth_sock = true

```

```ini
[workspaces.public-only]
paths = ["~/projects/public-only"]
ssh_auth_sock = false
git_config = false

```

--------------------------------

### Required Dockerfile header for workspace overlay build (Step 2)

Source: https://seznam.github.io/jailoc/reference/image-resolution

When `image` is set in `[defaults]` and `dockerfile` is set in the workspace, the workspace Dockerfile must begin with these lines. The `BASE` build argument is provided by jailoc from `defaults.image`.

```dockerfile
ARG BASE
FROM ${BASE}

```

--------------------------------

### Apply rules to all workspaces with [defaults]

Source: https://seznam.github.io/jailoc/how-to/network-access

Apply allow rules to all workspaces by using the `[defaults]` section. Per-workspace rules are merged with defaults (duplicates removed); workspace-level rules add to defaults, not override them.

```ini
[defaults]
allowed_hosts = ["internal-registry.example.com"]
allowed_networks = ["10.0.0.0/8"]

```

--------------------------------

### jailoc status command usage

Source: https://seznam.github.io/jailoc/reference/cli

Prints the state and assigned port for each configured workspace.

```bash
jailoc status [flags]

```

--------------------------------

### Load host file into environment variable

Source: https://seznam.github.io/jailoc/how-to/secrets

Configure the workspace to load the contents of a host file directly into a container environment variable.

```toml
[workspaces.my-project]
paths = ["~/projects/my-project"]

[workspaces.my-project.secrets.env.API_KEY]
from_file = "~/.secrets/api_key.txt"
```

--------------------------------

### Verifying TUI configuration and plugin files

Source: https://seznam.github.io/jailoc/how-to/tui-plugin

Check for the existence of generated TUI configuration and plugin files in the cache directory.

```bash
ls ~/.cache/jailoc/tui.json ~/.cache/jailoc/tui-container.json ~/.cache/jailoc/tui-plugin/
```

--------------------------------

### Manage workspace with jailoc subcommands

Source: https://seznam.github.io/jailoc/tutorials/getting-started

Shows other useful jailoc subcommands: status displays running workspaces and ports, logs tails container logs, and down stops and removes the workspace containers.

```bash
jailoc status   # show running workspaces and their ports
jailoc logs     # tail container logs
jailoc down     # stop and remove the workspace containers

```

--------------------------------

### Verify Docker daemon is running

Source: https://seznam.github.io/jailoc/tutorials/getting-started

Verifies that the Docker Engine daemon is running, a prerequisite for jailoc. The command should succeed without errors if Docker is available.

```bash
docker info

```

--------------------------------

### jailoc config command

Source: https://seznam.github.io/jailoc/reference/cli

Prints the current resolved configuration. Reads ~/.config/jailoc/config.toml, resolves defaults and ~ expansions, and lists secrets per scope as NAME (<destination> from_<source> <reference>). Secret values are never displayed.

```bash
jailoc config [flags]

```

--------------------------------

### Multi-stage build for compiled tools

Source: https://seznam.github.io/jailoc/how-to/custom-images

Multi-stage build for compiled tools. Builds a binary in a separate stage and copies only the output, keeping the final image free of compilers and intermediate artifacts.

```dockerfile
ARG BASE
FROM golang:1.24 AS builder
WORKDIR /src
COPY tool/ .
RUN CGO_ENABLED=0 go build -o /bin/mytool .

FROM ${BASE}
COPY --from=builder /bin/mytool /usr/local/bin/mytool

```

--------------------------------

### Check workspace status

Source: https://seznam.github.io/jailoc/how-to/troubleshooting

Confirm the workspace is running using the jailoc status command.

```bash
jailoc status
```

--------------------------------

### Set a local path for a custom base Dockerfile

Source: https://seznam.github.io/jailoc/how-to/custom-images

Configures a custom Dockerfile using a local file path in the [base] section.

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

--------------------------------

### Set a custom image

Source: https://seznam.github.io/jailoc/how-to/workspace-configuration

Use the image field to specify a pre-built Docker image for the workspace.

```toml
[workspaces.myproject]
paths = ["/home/you/projects/myproject"]
image = "myregistry.example.com/myteam/myimage:v1.2.3"
```

--------------------------------

### Set default environment variables

Source: https://seznam.github.io/jailoc/how-to/workspace-configuration

Apply environment variables to all workspaces by defining them in the [defaults] section.

```toml
[defaults]
env = ["GOPRIVATE=*.example.com"]
env_file = ["~/.config/jailoc/shared.env"]
```

--------------------------------

### Pass through OpenCode auth credentials

Source: https://seznam.github.io/jailoc/how-to/workspace-configuration

Mount only the auth.json file to pass host credentials into the container without replacing the entire named volume.

```toml
[defaults]
mounts = ["~/.local/share/opencode/auth.json:/home/agent/.local/share/opencode/auth.json:ro"]
```

--------------------------------

### Config file location

Source: https://seznam.github.io/jailoc/how-to/workspace-configuration

Shows the default location of jailoc's configuration file. The file is created automatically on first run with a default workspace already in place.

```text
~/.config/jailoc/config.toml
```

--------------------------------

### Restarting the workspace

Source: https://seznam.github.io/jailoc/how-to/tui-plugin

Restart the workspace to apply changes to the plugin configuration.

```bash
jailoc restart <name>
```

--------------------------------

### Configure environment secret in config.toml

Source: https://seznam.github.io/jailoc/how-to/secrets

Add the secret to your workspace configuration in ~/.config/jailoc/config.toml to map the host environment variable.

```toml
[workspaces.my-project]
paths = ["~/projects/my-project"]

[workspaces.my-project.secrets.env.MCP_SERVER_TOKEN]
from_env = "HOST_MCP_TOKEN"
```

--------------------------------

### jailoc logs command usage

Source: https://seznam.github.io/jailoc/reference/cli

Streams container logs from the target workspace environment.

```bash
jailoc logs [flags]

```

--------------------------------

### Run jailoc from a subdirectory

Source: https://seznam.github.io/jailoc/how-to/access-modes

When run from a subdirectory, jailoc resolves the current working directory and forwards it as --dir. Works because workspace paths are identity-mounted.

```bash
cd ~/projects/myproject/src
jailoc    # attaches with --dir pointing at src/

```

--------------------------------

### Grep jailoc log for image resolution errors

Source: https://seznam.github.io/jailoc/how-to/troubleshooting

Use this command to inspect the jailoc log for image resolution errors when `jailoc up` fails to pull or build the container image. The log path is ~/.cache/jailoc/jailoc.log.

```bash
# Check the log for image resolution errors
grep -Ei "image|pull|build|dockerfile" ~/.cache/jailoc/jailoc.log

```

--------------------------------

### Add multiple paths to a workspace

Source: https://seznam.github.io/jailoc/how-to/workspace-configuration

Adds multiple paths to a workspace. All listed paths are mounted read-write, and the first path is the working directory.

```toml
[workspaces.api]
paths = [
  "/home/you/projects/api",
  "/home/you/projects/shared-libs",
]

```

--------------------------------

### Add a host directory mount

Source: https://seznam.github.io/jailoc/how-to/workspace-configuration

Use the mounts field to add a host directory to the container, following the host:container[:mode] format.

```toml
[workspaces.my-project]
paths = ["/home/you/projects/my-project"]
mounts = ["~/.local/share/opencode:/home/agent/.local/share/opencode"]
```

--------------------------------

### Find process using a port with lsof

Source: https://seznam.github.io/jailoc/how-to/troubleshooting

When 'jailoc up' fails with 'address already in use' or attach fails with connection refused, use 'lsof -i :4096' to find what's using the port. Ports are assigned as 4096 + alphabetical index among all configured workspaces.

```bash
# Find what's using the port (e.g. 4096)
lsof -i :4096

```

--------------------------------

### Open a specific directory with --dir

Source: https://seznam.github.io/jailoc/how-to/access-modes

Use --dir to open a subdirectory instead of the workspace root. The root jailoc command does this automatically when run from a subdirectory.

```bash
jailoc --dir /home/you/projects/myproject/src

```

--------------------------------

### Manual configuration of tui.json

Source: https://seznam.github.io/jailoc/how-to/tui-plugin

Add the shared plugin directory to your custom ~/.config/opencode/tui.json file if you have one.

```json
{
  "plugin": ["file:///Users/<you>/.cache/jailoc/tui-plugin"]
}
```

--------------------------------

### Enable SSH agent forwarding

Source: https://seznam.github.io/jailoc/how-to/workspace-configuration

Enable SSH agent forwarding to allow cloning private repositories or pushing over SSH. Git configuration is mounted by default.

```ini
[defaults]
ssh_auth_sock = true
```

--------------------------------

### Use HTTP URL for workspace Dockerfile

Source: https://seznam.github.io/jailoc/how-to/custom-images

Uses an HTTP URL for the workspace Dockerfile. jailoc supports remote Dockerfiles in addition to local paths.

```ini
[workspaces.myproject]
paths = ["~/projects/myproject"]
dockerfile = "https://git.example.com/team/dockerfiles/-/raw/main/myproject-overlay.Dockerfile"

```

--------------------------------

### Set a custom Dockerfile

Source: https://seznam.github.io/jailoc/how-to/workspace-configuration

Use the dockerfile field to build the workspace image from a remote Dockerfile.

```toml
[workspaces.myproject]
paths = ["/home/you/projects/myproject"]
dockerfile = "https://git.example.com/team/dockerfiles/-/raw/main/myproject.Dockerfile"
```

--------------------------------

### jailoc add command

Source: https://seznam.github.io/jailoc/reference/cli

Adds the current working directory to the target workspace's paths list in ~/.config/jailoc/config.toml. Validates secret sources and path restrictions. When --workspace is not set, resolves the workspace from the path; if set explicitly and the path is not under a configured path, returns an error.

```bash
jailoc add [flags]

```

--------------------------------

### Allow an HTTP proxy on a private network

Source: https://seznam.github.io/jailoc/how-to/network-access

Allow an HTTP proxy on a private network by adding its hostname to `allowed_hosts` and passing the proxy URL via `env`. Without the allowlist entry, the proxy address falls into a blocked range and all proxied requests fail silently.

```ini
[workspaces.api]
paths = ["/home/you/projects/api"]
allowed_hosts = ["proxy.internal.example.com"]
env = [
  "HTTP_PROXY=http://proxy.internal.example.com:3128",
  "HTTPS_PROXY=http://proxy.internal.example.com:3128",
]

```

--------------------------------

### Run jailoc with auto-detection

Source: https://seznam.github.io/jailoc/how-to/access-modes

Default behavior: jailoc checks PATH for opencode or opencode-cli. If found, uses remote mode; otherwise falls back to exec mode. No config needed.

```bash
jailoc

```

--------------------------------

### Allow private hosts and networks in workspace config

Source: https://seznam.github.io/jailoc/how-to/troubleshooting

Add allowed hosts or networks to the workspace config to permit access to private services, then restart the workspace for changes to take effect. jailoc blocks RFC 1918, link-local, and CGNAT addresses by default.

```ini
[workspaces.myproject]
allowed_hosts = ["internal-registry.example.com"]
allowed_networks = ["10.10.5.0/24"]

```

```bash
jailoc restart myproject

```

--------------------------------

### Workspace path configuration

Source: https://seznam.github.io/jailoc/how-to/workspace-configuration

Defines two workspaces with different path scopes. The 'specific' workspace has a longer prefix match, so it is selected when the current working directory is under '/home/you/projects/api'.

```toml
[workspaces.broad]
paths = ["/home/you/projects"]

[workspaces.specific]
paths = ["/home/you/projects/api"]
```

--------------------------------

### Set base dockerfile to an HTTP URL

Source: https://seznam.github.io/jailoc/reference/configuration

Configures the base image to use a Dockerfile from an HTTP(S) URL. The URL takes priority over the embedded fallback, and the maximum file size for HTTP sources is 1 MiB.

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

```

--------------------------------

### Find jailoc log file location

Source: https://seznam.github.io/jailoc/how-to/troubleshooting

jailoc writes structured logs to ~/.cache/jailoc/jailoc.log. The log file rotates at startup when it exceeds 5 MB, renaming the previous file to jailoc.log.1; if rename fails, it truncates instead. If home directory cannot be determined, logs fall back to $TMPDIR/jailoc/jailoc.log, and if the file cannot be opened, logging is silently disabled.

```text
~/.cache/jailoc/jailoc.log

```

--------------------------------

### Mount credential file in config.toml

Source: https://seznam.github.io/jailoc/how-to/secrets

Define a file secret in your workspace configuration pointing to an absolute or tilde path on your host.

```toml
[workspaces.my-project]
paths = ["~/projects/my-project"]

[workspaces.my-project.secrets.file.db_cert]
from_file = "~/.config/my-project/db.pem"
```

--------------------------------

### Set environment variables via env_file

Source: https://seznam.github.io/jailoc/how-to/workspace-configuration

Load environment variables from a file using the env_file field, which must follow the Docker .env format.

```toml
[workspaces.api]
paths = ["/home/you/projects/api"]
env_file = ["~/.config/jailoc/api.env"]
```

--------------------------------

### Allow a CIDR range with allowed_networks

Source: https://seznam.github.io/jailoc/how-to/network-access

Permit an entire subnet by adding a CIDR range to `allowed_networks`. Values must be valid CIDR notation; invalid entries are rejected at config load time.

```ini
[workspaces.frontend]
paths = ["/home/you/projects/frontend"]
allowed_networks = ["172.20.0.0/16"]

```

--------------------------------

### Check DinD sidecar logs

Source: https://seznam.github.io/jailoc/how-to/troubleshooting

Inspect the sidecar logs to diagnose why Docker commands inside the workspace are failing.

```bash
# Check sidecar logs
jailoc logs <workspace>
```

--------------------------------

### Go Module Path

Source: https://seznam.github.io/jailoc/development

The primary Go module identifier for the project.

```text
github.com/seznam/jailoc
```

--------------------------------

### Set workspace resource limits

Source: https://seznam.github.io/jailoc/how-to/workspace-configuration

Control CPU and memory allocation for the opencode container. Workspace-specific settings override defaults, with a fallback of 2.0 CPU cores and 4g memory.

```ini
[defaults]
cpu = 2.0
memory = "4g"

[workspaces.heavy-agent]
cpu = 8.0
memory = "16g"
```

--------------------------------

### Verify port listening status

Source: https://seznam.github.io/jailoc/how-to/troubleshooting

Use lsof to check if the specific port is actively listening.

```bash
lsof -i :<port>
```

--------------------------------

### Configure workspace-specific Dockerfile

Source: https://seznam.github.io/jailoc/how-to/custom-images

Sets a workspace-specific Dockerfile in the `[workspaces.<name>]` block. jailoc builds this Dockerfile on top of the resolved base image, passing the base tag as a build argument.

```ini
[workspaces.myproject]
paths = ["~/projects/myproject"]
dockerfile = "~/projects/myproject/overlay.Dockerfile"

```

--------------------------------

### Remove a default mount

Source: https://seznam.github.io/jailoc/how-to/workspace-configuration

Set an empty host source for a specific container path to remove a default mount.

```toml
[workspaces.my-project]
paths = ["/home/you/projects/my-project"]
mounts = [":/home/agent/.opencode"]
```

--------------------------------

### Set host environment variable

Source: https://seznam.github.io/jailoc/how-to/secrets

Set the environment variable on your host system to be used as a secret.

```bash
export HOST_MCP_TOKEN="secret-token-value"
```

--------------------------------

### Override default mounts

Source: https://seznam.github.io/jailoc/how-to/workspace-configuration

Mounts defined in the [defaults] section apply to all workspaces, but per-workspace mounts override defaults for the same container path.

```toml
[defaults]
mounts = ["~/.local/share/opencode:/home/agent/.local/share/opencode:ro"]

[workspaces.my-project]
paths = ["/home/you/projects/my-project"]
mounts = ["~/.local/share/opencode:/home/agent/.local/share/opencode:rw"]
```

--------------------------------

### Set a build context

Source: https://seznam.github.io/jailoc/how-to/workspace-configuration

Override the default Docker build context using the build_context field.

```toml
[workspaces.myproject]
paths = ["/home/you/projects/myproject"]
build_context = "/home/you/projects/myproject/docker"
```

--------------------------------

### Set environment variables via env

Source: https://seznam.github.io/jailoc/how-to/workspace-configuration

Pass environment variables directly to the agent container using the env field.

```toml
[workspaces.api]
paths = ["/home/you/projects/api"]
env = ["MY_TOKEN=abc123", "LOG_LEVEL=debug"]
```

--------------------------------

### Verifying JAILOC environment variable

Source: https://seznam.github.io/jailoc/how-to/tui-plugin

Check if the JAILOC environment variable is set inside the container to ensure the plugin can render.

```bash
env | grep JAILOC
```

--------------------------------

### Set a connection mode

Source: https://seznam.github.io/jailoc/how-to/workspace-configuration

Control the container connection method using the mode field, which supports remote or exec options.

```toml
[workspaces.myproject]
paths = ["/home/you/projects/myproject"]
mode = "remote"   # or "exec", or omit for auto-detect
```

--------------------------------

### jailoc restart command usage

Source: https://seznam.github.io/jailoc/reference/cli

Stops and restarts the Docker Compose environment for a workspace. Equivalent to `jailoc down` followed by `jailoc up`.

```bash
jailoc restart [flags]

```

--------------------------------

### Set global default secrets

Source: https://seznam.github.io/jailoc/how-to/secrets

Declare secrets under [defaults.secrets.env.<NAME>] or [defaults.secrets.file.<NAME>] to make them available across all workspaces.

```toml
[defaults.secrets.env.API_TOKEN]
from_env = "GLOBAL_API_TOKEN"

[workspaces.my-project]
paths = ["~/projects/my-project"]
```

--------------------------------

### Set fixed mode in workspace config

Source: https://seznam.github.io/jailoc/how-to/access-modes

Pin a workspace to a specific mode by setting mode in the workspace config. Valid values: "" (auto-detect), "remote", "exec".

```ini
[workspaces.myproject]
paths = ["/home/you/projects/myproject"]
mode = "remote"

```

--------------------------------

### Override mode with CLI flags

Source: https://seznam.github.io/jailoc/how-to/access-modes

Force a mode for a single run without changing config. The flag takes precedence over config and auto-detection.

```bash
jailoc --remote   # force remote mode for this run
jailoc --exec     # force exec mode for this run

```

--------------------------------

### Set explicit build context for workspace overlay

Source: https://seznam.github.io/jailoc/how-to/custom-images

Sets an explicit build context for the workspace overlay. By default, the build context is the parent directory of the Dockerfile; setting it explicitly controls which files are available during the build. With this configuration, files from `~/projects/myproject` are accessible via `COPY` instructions.

```ini
[workspaces.myproject]
paths = ["~/projects/myproject"]
dockerfile = "~/projects/myproject/docker/overlay.Dockerfile"
build_context = "~/projects/myproject"

```

--------------------------------

### jailoc down command usage

Source: https://seznam.github.io/jailoc/reference/cli

Stops and removes the containers for the target workspace. Equivalent to `docker compose down` on the generated compose file.

```bash
jailoc down [flags]

```

--------------------------------

### Clean npm cache in same layer

Source: https://seznam.github.io/jailoc/how-to/custom-images

Uses `--prefer-offline` or cleans the npm cache in the same layer to keep layers small.

```dockerfile
RUN npm ci --prefer-offline && npm cache clean --force

```

--------------------------------

### Set password_mode to auto in config.toml

Source: https://seznam.github.io/jailoc/reference/configuration

Sets the password storage mode to automatic, which uses the environment variable override, then the OS keyring, then a password file. This is the default behavior.

```toml
password_mode = "auto"

```

--------------------------------

### Per-workspace overrides for ssh_auth_sock and git_config

Source: https://seznam.github.io/jailoc/how-to/ssh-git-passthrough

Show per-workspace overrides: workspaces inherit defaults unless they set a field explicitly. When neither workspace nor defaults set git_config, the fallback is true. Workspace values win when set.

```ini
[defaults]
ssh_auth_sock = true

[workspaces.private-repos]
paths = ["~/projects/private-repos"]
# inherits ssh_auth_sock = true from defaults

[workspaces.isolated]
paths = ["~/projects/isolated"]
ssh_auth_sock = false  # disables SSH for this workspace only
git_config = false     # disables Git config for this workspace only

```

--------------------------------

### Enable SSH agent forwarding with ssh_auth_sock

Source: https://seznam.github.io/jailoc/how-to/ssh-git-passthrough

Enable SSH agent forwarding globally in [defaults] or per workspace. When enabled, jailoc mounts the SSH agent socket at /run/ssh-agent.sock and sets SSH_AUTH_SOCK automatically. If no valid socket is found, the mount is silently skipped.

```ini
[defaults]
ssh_auth_sock = true

```

```ini
[workspaces.my-project]
paths = ["~/projects/my-project"]
ssh_auth_sock = true

```

--------------------------------

### Remove jailoc log files

Source: https://seznam.github.io/jailoc/how-to/troubleshooting

Delete the jailoc log files to free up space or reset logging.

```bash
rm -f ~/.cache/jailoc/jailoc.log ~/.cache/jailoc/jailoc.log.1
```

--------------------------------

### Remove stale jailoc Docker resources

Source: https://seznam.github.io/jailoc/how-to/troubleshooting

Stop workspaces and remove exited containers and volumes associated with jailoc.

```bash
# Stop each workspace first (repeat for every running workspace)
jailoc down <workspace>

# Remove exited jailoc containers
docker ps -a --filter "label=com.docker.compose.project" --filter "status=exited" \
  --format '{{.Names}}' | grep '^jailoc-' | xargs docker rm

# Remove jailoc volumes (all workspaces must be stopped)
docker volume ls --format '{{.Name}}' \
  | grep '^jailoc-' | xargs docker volume rm
```

--------------------------------

### Check and fix bind mount permissions

Source: https://seznam.github.io/jailoc/how-to/troubleshooting

When the agent reports permission errors on mounted paths, check ownership with 'ls -ln' and fix with 'sudo chown -R 1000:1000'. The agent runs as UID 1000 inside the container; mounted host directories must be readable and writable by UID 1000. On macOS with Docker Desktop, file sharing handles UID mapping automatically, so this issue primarily affects Linux hosts.

```bash
# Check ownership
ls -ln /path/to/mounted/dir

# Fix if needed
sudo chown -R 1000:1000 /path/to/mounted/dir

```

--------------------------------

### Commit Message Format

Source: https://seznam.github.io/jailoc/development

The required format for commit messages, using imperative mood.

```text
type(scope): description
```

--------------------------------

### Disable Git config mounting with git_config

Source: https://seznam.github.io/jailoc/how-to/ssh-git-passthrough

Disable Git configuration mounting for a specific workspace or globally. Git config is mounted read-only by default; setting git_config = false skips the mount. jailoc checks ~/.gitconfig then ~/.config/git/config, mounting the first found at /home/agent/.gitconfig.

```ini
[workspaces.isolated]
paths = ["~/projects/isolated"]
git_config = false

```

```ini
[defaults]
git_config = false

```

--------------------------------

### Suppress pip cache

Source: https://seznam.github.io/jailoc/how-to/custom-images

Suppresses the pip cache directory to keep layers small.

```dockerfile
RUN pip install --no-cache-dir -r requirements.txt

```

--------------------------------

### Remove cached compose files

Source: https://seznam.github.io/jailoc/how-to/troubleshooting

Clear the cached compose files for a specific workspace.

```bash
rm -rf ~/.cache/jailoc/<workspace>/
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.