thinknsh dock: Fast, Zero-Daemon Containers

dock is the native container engine integrated directly into thinknsh. It gives you the full developer experience of modern container runtimes without the bloat, battery drain, and memory overhead of running heavy background daemons.

Images come directly from standard OCI registries (Docker Hub, GitHub Packages ghcr.io, Quay), containers execute using fast crun on a real Linux kernel, and state is preserved cleanly in a local SQLite store.

• macOS Isolation: Runs on Apple's native Virtualization framework. It boots in under 1 second when you launch your first container and automatically sleeps after 5 idle minutes.
• Windows (WSL2): Powered by an optimized, dedicated WSL2 distro named tnc-dock with native C:\ path mapping and zero background CPU usage when idle.
• Native Linux: Runs directly on host cgroups v2 and namespaces with zero virtualization penalty or hypervisor overhead.

Getting started requires Node.js 22.5 or newer (for built-in SQLite state storage). Check your version by running node --version in your terminal.

1. Install the shell globally

# Install V2 Beta via npm
npm install -g thinkncollab-shell@beta
# Or run instantly with npx
npx thinkncollab-shell@beta

2. Download and verify runtime components

Run dock setup. It automatically detects your host OS and CPU architecture (Apple Silicon M-series, Intel x86_64, or Linux aarch64), verifies sha256 checksums, and provisions the engine:

thinknsh dock setup

• Windows Users: Ensure WSL2 is enabled first in an administrator PowerShell with 'wsl --install --no-distribution' and restart.
• Linux Users: Run 'sudo thinknsh dock setup' and 'sudo thinknsh dock start', then add your user to 'tnc-dock' group to run without sudo.
• macOS Auto-Start: Run 'thinknsh dock autostart' to boot dock seamlessly on login.

3. Verify engine health

thinknsh dock status

No separate daemon start command is required—the engine boots automatically on your first command.

Interactive Sandbox (Alpine Linux)

Launch an instant interactive container with pseudo-terminal and cleanup flag (--rm). Press Ctrl-P Ctrl-Q to detach without stopping:

thinknsh run --rm -it alpine sh

Background Web Server (Nginx)

Publish container ports to your host machine using the -p flag. Here port 80 inside the container maps to port 8080 on your host:

# Start web server in background
thinknsh run -d --name web -p 8080:80 nginx:alpine
# Verify it is running
thinknsh ps
# View output logs live
thinknsh logs -f web
# Open in browser: http://localhost:8080

Execute commands in a running container

# Run an interactive shell inside 'web'
thinknsh exec -it web sh
# Stop and clean up
thinknsh stop web && thinknsh rm web

Containers are ephemeral by default. For stateful workloads like PostgreSQL, Redis, or MySQL, mount a persistent volume so data survives container restarts and upgrades.

1. Create a persistent named volume

thinknsh volume create pgdata

2. Spin up a production-grade PostgreSQL 16 container

thinknsh run -d --name dev-postgres \
  -e POSTGRES_PASSWORD=devsecret \
  -p 5432:5432 \
  -v pgdata:/var/lib/postgresql/data \
  postgres:16-alpine

3. Connect directly via psql CLI

thinknsh exec -it dev-postgres psql -U postgres

Connecting back to your host: host.tnc.internal

Need your containerized service to talk to a local API server running on your Mac/Windows host? Use host.tnc.internal (e.g. http://host.tnc.internal:3000) to connect directly to host ports.

thinknsh build reads standard Dockerfile or Containerfile formats with full support for multi-stage builds, build arguments, caching, and BuildKit secret mounts.

Build and tag a project

# Build with default build file in current folder
thinknsh build -t myapp:latest .
# Build with custom file and target stage
thinknsh build -f deploy/Dockerfile --target production -t myapp:prod .
# Run your newly built image
thinknsh run --rm -p 3000:3000 myapp:latest

Secure BuildKit mounts & private registries

Build with temporary secret mounts so access tokens or certificates never end up in layer history. Then push your image to GitHub Packages or Docker Hub:

# Build with secret mount
thinknsh build --secret id=npmrc,src=$HOME/.npmrc -t myapp .
# Log in to OCI registry
thinknsh login -u myusername ghcr.io
# Tag and push
thinknsh tag myapp ghcr.io/myusername/myapp:1.0
thinknsh push ghcr.io/myusername/myapp:1.0

Orchestrate your entire local tech stack (frontend, backend, database, cache) with a single compose.yaml file. thinknsh compose supports depends_on healthchecks, profiles, environment files (.env), and volume mounts out of the box.

Start and manage your compose stack

# Build missing images and start all services in background
thinknsh compose up -d
# View running services across the project
thinknsh compose ps
# Stream logs for a specific service (e.g. 'api')
thinknsh compose logs -f api
# Execute a test suite inside a compose service
thinknsh compose exec api npm test
# Stop everything and clean up volumes
thinknsh compose down -v

You do not need to rewrite your CI scripts or change existing editor setups. Run dock use once, and third-party tools will automatically route to dock via the standard engine API socket.

# Configure standard tools to use dock
thinknsh dock use
# macOS: also bridge the system root socket (/var/run/docker.sock)
thinknsh dock use --system
# Revert back whenever you want
thinknsh dock use --off

• VS Code Dev Containers: 'Reopen in Container' works instantly with your Dockerfile or devcontainer.json configuration.
• Testcontainers: Automated integration tests in Node.js, Go, Python, and Java spin up test containers without manual setup.
• Standard CLI: Scripts calling legacy engine CLI commands execute seamlessly against the dock engine socket.

Prefer a graphical view over terminal commands? dock includes both a self-contained local web dashboard and a native macOS menu bar application.

Local Web Dashboard (thinknsh dock ui)

Launch the browser dashboard with live CPU/RAM charts, real-time log viewers, container inspectors, and network diagnostics. It runs strictly on 127.0.0.1 with session security:

thinknsh dock ui

macOS Menu Bar App (TNC Dock)

Install TNC Dock directly into your macOS status bar for one-click container starts, stops, quick terminal shells, and browser port jumping:

thinknsh dock app

Migrating from another container tool? Transfer all your locally pulled images and data volumes in one command without re-downloading gigabytes of layers:

# Preview what images and volumes will be transferred
thinknsh dock migrate --dry-run
# Migrate images and volumes over to dock
thinknsh dock migrate --images --volumes

Hardware & Isolation Selftest

Validate end-to-end functionality on your specific machine. selftest runs 12 automated integrity checks (MicroVM boot, bridge networking, NAT port routing, volume persistence, buildkit, process cleanup) and generates a shareable JSON report:

thinknsh dock selftest

Need a real Kubernetes API for Helm charts, operators or manifests? dock runs k3s, a certified Kubernetes distribution, in a single container and wires kubectl to it. The API listens on 127.0.0.1 only, and Kubernetes Secrets are encrypted at rest.

# Start a local cluster and add the kubectl context "thinknsh"
thinknsh k8s up
kubectl get nodes
# Use images you built locally, no registry needed
thinknsh build -t myapp:1 .
thinknsh k8s load myapp:1
kubectl create deployment myapp --image=myapp:1
# Stop it (state is kept) or delete it
thinknsh k8s down
thinknsh k8s rm

• No kubectl installed? Run 'thinknsh k8s kubectl get pods -A' to use the one inside the cluster.
• Memory: Kubernetes needs 2 GB or more for containers. 'thinknsh dock config --memory 4g --cpus 2' then 'thinknsh dock vm-restart'.
• macOS & Windows: needs the dock runtime bundle 0.2.6 or newer (run 'thinknsh dock setup' after updating).

Install thinknagent on your servers, approve them in your room's DevOps wall, and deploy the same compose file you use locally. dock schedules replicas across servers, rolls out updates one pod at a time, and moves pods away from a server that stops answering.

thinknsh cluster deploy -f compose.yaml      # spread across your servers
thinknsh cluster status                      # pods, nodes and their keys
thinknsh cluster scale shop-web 3
thinknsh cluster secret set DB_PASSWORD      # sealed to your servers' keys
# Or a full Kubernetes cluster across the same servers
thinknsh cluster k8s up
thinknsh cluster k8s kubeconfig

• Secrets the platform cannot read: values are sealed on your machine to each server's own key, and only those servers can open them.
• Encrypted traffic between servers: pods talk across servers over TLS keyed by the two servers' own keys; Kubernetes nodes use WireGuard.
• Servers need Linux 5.6 or newer. Keep ports 7947/tcp (and 6443/tcp, 10250/tcp, 51820/udp for Kubernetes) open only between your servers.

Collaboration should not mean trusting a middleman. Everything below is encrypted on one machine and opened only on the other; ThinkNCollab relays ciphertext it cannot read.

# An encrypted network across two Linux machines
openssl rand -hex 32 > /etc/tnc-mesh.key   # copy to each machine
sudo thinknsh network create -d overlay --subnet 10.20.0.0/16 --ip-range 10.20.1.0/24 \
  -o peers=192.168.1.11 -o encrypted -o key-file=/etc/tnc-mesh.key mesh
# A registry for your office network, over verified TLS
thinknsh registry start --lan                                   # prints its fingerprint
thinknsh registry trust 192.168.1.20:5000 --fingerprint AB:CD:…  # on each other machine

• Not end to end: a sandbox's public preview link goes through ThinkNCollab, which serves it over HTTPS.

Real-world memory footprint measured on Apple Silicon using 'thinknsh bench'. Notice how dock drops memory consumption when idle compared to traditional hypervisor daemons:

Every command has detailed built-in documentation. Run any command with --help for options and usage examples (e.g. thinknsh run --help).