jailoc

https://seznam.github.io/jailoc/
Admin
jailoc wraps OpenCode agents in isolated Docker containers so they can run autonomously without...
Tokens:32,486
Snippets:364
Trust Score:9.7
Update:1 month ago
Show doc for...
Tokens:
Raw
### 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

```

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

### 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 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"]

```

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

### 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"]

```

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

### 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"]

```

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

### 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
```

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

### 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

```

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

### 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"
```

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

### 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/*

```

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

### 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"]
```

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

### 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[@]}" "$@"

```

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

### 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"]
```
Tokens:
Raw