Tsk Config

tsk Docker Configuration Guide

You are helping a user configure tsk Docker container images for their project. Follow these steps in order.

Step 1: Gather Project Information

Detect the project's technology stack by checking for these files in the project root. These are tsk's built-in stacks with auto-detection — custom stacks for any language can be defined via stack_config in tsk.toml (covered in Step 5).

Also determine the project name from the current directory name.

Tell the user what you detected and ask them to confirm or override. If their stack isn't listed above, let them know they can define a custom stack.

Step 2: Check for Deprecated Dockerfiles

Check if .tsk/dockerfiles/ exists. If it does, warn the user:

Deprecated: tsk no longer supports filesystem-based dockerfiles in .tsk/dockerfiles/. Docker customization is now done via setup fields in tsk.toml. This guide will help you migrate to the new format.

List any files found in .tsk/dockerfiles/ and note their contents — you will use them to populate the new config.

Step 3: Choose Configuration Location

Ask the user where to put the configuration:

• Project-level (.tsk/tsk.toml): Checked into version control, shared with the team. Best for project-specific dependencies that all contributors need.
• User-level (~/.config/tsk/tsk.toml): Personal settings, not shared. Best for machine-specific paths, personal preferences, or settings across multiple projects.

If the user picks user-level, config goes under [project.<project-name>] in ~/.config/tsk/tsk.toml. If project-level, config goes at the top level of .tsk/tsk.toml.

Step 4: View the Current Docker Build

Run this command and show the output to the user:

tsk docker build --dry-run

Explain to the user: this shows the complete Dockerfile that tsk generates with all layers resolved. Look for comments like # Stack layer, # Project layer, and # Agent layer to see where each setup field injects content. The next step will help them add the right customizations.

Step 5: Populate Configuration

Based on the project analysis, write the tsk.toml configuration. Use the layer reference below to decide what goes where.

tsk Docker Layer Architecture

tsk builds container images using 4 layers, assembled in this order:

1. Base layer    — Ubuntu 25.10, git, build-essential, ripgrep, Python 3, uv, podman
2. Stack layer   — Language runtime and tools (e.g., Go, Rust, Node.js)
3. Project layer — Project-specific system dependencies
4. Agent layer   — AI agent installation (Claude, Codex)

You customize layers 2-4 via tsk.toml:

Each setup field contains raw Dockerfile commands (RUN, ENV, COPY, etc.) that get injected into the generated Dockerfile at the corresponding layer position. Setup commands run as the agent user by default. Use USER root to switch to root for operations that require it (e.g., apt-get), and always switch back to USER agent afterwards.

Built-in Stacks (What's Already Included)

tsk has built-in stack layers. You only need stack_config if the built-in is insufficient.

rust: Rust stable via rustup, CARGO_TARGET_DIR=/home/agent/.cargo/target

go: Go 1.25.0, GOPATH=/home/agent/gopath, CGO_ENABLED=0

node: Node.js LTS, npm, pnpm, yarn, typescript, ts-node, nodemon, eslint, prettier, jest, npm-check-updates. NODE_ENV=development

python: uv venv at /home/agent/.venv, pytest, pip, black, ruff, ty, mypy, poetry

java: OpenJDK 17, Maven, Gradle. Maven settings.xml and Gradle gradle.properties are pre-configured to route through the tsk proxy

lua: LuaJIT, Lua 5.1 dev libs, Neovim, stylua, LuaRocks with luacheck/busted/luassert/luafilesystem/nlua

default: Empty (base layer only)

Base Layer (Always Present)

Every container includes: Ubuntu 25.10, git, git-lfs, build-essential, curl, jq, just, ripgrep, sudo, Python 3, uv, podman (for DIND), and an agent user (UID 1000).

Configuration Format

Project-level (.tsk/tsk.toml):

# Project-specific dependencies (injected at the project layer)
setup = '''
USER root
RUN apt-get update && apt-get install -y libssl-dev pkg-config cmake
USER agent
'''

# Override or extend the stack layer
[stack_config.rust]
setup = '''
RUN cargo install cargo-nextest sccache
ENV RUSTC_WRAPPER=sccache
'''

User-level (~/.config/tsk/tsk.toml):

# Default settings for all projects
[defaults]
memory_gb = 16.0
cpu = 8

# Per-project overrides
[project.my-project]
stack = "rust"
setup = '''
USER root
RUN apt-get update && apt-get install -y libssl-dev pkg-config
USER agent
'''

[project.my-project.stack_config.rust]
setup = '''
RUN cargo install cargo-nextest
'''

Common Examples

Rust project needing system libraries:

setup = '''
USER root
RUN apt-get update && apt-get install -y \
    libssl-dev pkg-config cmake protobuf-compiler
USER agent
'''

Python project with native dependencies:

setup = '''
USER root
RUN apt-get update && apt-get install -y \
    libpq-dev libffi-dev
USER agent
'''

Node.js project needing native build tools:

setup = '''
USER root
RUN apt-get update && apt-get install -y \
    libcairo2-dev libjpeg-dev libpango1.0-dev libgif-dev
USER agent
'''

Go project with CGO and protocol buffers:

[stack_config.go]
setup = '''
USER root
ENV CGO_ENABLED=1
RUN apt-get update && apt-get install -y protobuf-compiler
USER agent
RUN go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
'''

Java project with a specific JDK version:

[stack_config.java]
setup = '''
USER root
RUN apt-get update && apt-get install -y openjdk-21-jdk
USER agent
ENV JAVA_HOME=/usr/lib/jvm/java-21-openjdk-amd64
'''

Adding a stack not built into tsk (e.g., Scala):

stack = "scala"

[stack_config.scala]
setup = '''
USER root
RUN apt-get update && apt-get install -y openjdk-21-jdk
RUN curl -fL https://github.com/coursier/coursier/releases/latest/download/cs-x86_64-pc-linux.gz | gzip -d > /usr/local/bin/cs \
    && chmod +x /usr/local/bin/cs \
    && cs setup --yes
USER agent
ENV JAVA_HOME=/usr/lib/jvm/java-21-openjdk-amd64
'''