thinkncollab-shell
v0.2.10
Published
Lightweight MicroVM Sandbox & Zero-Daemon Dev Runner: Fast MicroVM Containers, Native Microservices, Live Database Snapshots, and End-to-End Encrypted State Sync
Downloads
2,018
Maintainers
Readme
ThinkNCollab Shell V2 (thinknsh)
The Native-First Collaborative Developer OS: Lightweight MicroVM Sandbox & Zero-Daemon Dev Runner with Live Database Snapshots, P2P Terminal Multiplexing, and OCI Compatibility.
🌟 What is ThinkNCollab Shell?
ThinkNCollab Shell (thinknsh) is a native-first development shell, process sandbox, and collaborative runtime built to eliminate everyday developer environment friction.
Instead of running a heavy 4GB+ RAM virtual machine daemon just to boot a local database, wrestling with teammate database migration drift, or sharing laggy video screens, ThinkNCollab unifies your code, database, and terminal into a single peer-to-peer developer shell.
🔐 Sign in with ThinkNCollab
Every thinknsh command needs a ThinkNCollab account. One command signs you in and connects this project to its room:
thinknsh login # asks: "Continue with Google" or "Email and password", then connects the room
thinknsh connect # choose this project's room again (or: connect <room name>)
thinknsh login --google # Google in the browser; already signed in there? just press Allow
thinknsh login --no-browser # prints the Google sign-in link instead (open it on this computer)
thinknsh login --password # email + password at a hidden prompt
thinknsh auth # who is signed in, where the token is kept, when it was last confirmed
thinknsh auth sessions # this account's shell sessions on every machine
thinknsh auth revoke <ID> # end one (a lost laptop)
thinknsh logout # revoke this machine's token- Which room: a
tncprojectfile in the folder wins; otherwise the room you picked for this project before (kept per project folder in~/.thinkncollab/projects.json); with one room it is that one; otherwiseloginasks once. Commands that need a room (tasks,say,issues, …) join it by themselves. - With Google, a browser that is already signed in to thinkncollab.com only asks you to allow this computer; otherwise it goes straight to Google's account picker.
- The shell never sees your password in browser sign-in: the site sends a one-time code back to
127.0.0.1(state + PKCE), and the shell trades it for a token. - The token lives in the system keychain (macOS Keychain, Windows Credential Manager, Secret Service);
~/.thinkncollab/session.json(0600) keeps only who you are. A token is only ever sent to the server that issued it, over HTTPS. - The shell re-confirms the sign-in with the platform every 12 hours, and any 401 from the platform signs you out at once, so a revoked token stops the shell on its next platform call or check. Offline, the last confirmation counts for 7 days.
- Passwords and tokens are never taken as arguments, and old history lines that had them are scrubbed from
~/.thinknsh_history(now 0600). - CI and scripts: set
THINKNCOLLAB_TOKENto a token from thinkncollab.com (never written to disk). - Without signing in you can still run
login,register,helpand the engine's own setup (dock setup / start / stop / status / autostart / app), which the installers use.
How it works and what the platform has to serve: docs/PLATFORM-AUTH.md.
📦 Containers: thinknsh run, build, compose
thinknsh has its own container engine, dock. You run, build and compose OCI containers with thinknsh commands. No other tool is needed. Images come from any OCI registry (the public one that hosts alpine, postgres and nginx works out of the box), containers run with crun on a real Linux kernel, and all state lives in one SQLite file. The daemon starts by itself on the first command.
thinknsh run --rm -it alpine sh # interactive shell (Ctrl-P Ctrl-Q detaches)
thinknsh run -d --name db -e POSTGRES_PASSWORD=dev -p 5432:5432 postgres:16
thinknsh ps # -a for stopped ones too
thinknsh logs -f db
thinknsh exec -it db psql -U postgres
thinknsh build -t myapp . # Containerfile (or the classic build file name)
thinknsh compose up -d # compose.yaml in this folder
thinknsh compose logs -f
thinknsh compose down -v
thinknsh login -u me ghcr.io # asks for the password (or --password-stdin)
thinknsh tag myapp ghcr.io/me/myapp:1.0 && thinknsh push ghcr.io/me/myapp:1.0
thinknsh logout ghcr.ioRegistry logins are checked with the registry, then saved per registry host in ~/.tnc/dock/auth.json (mode 0600, read only by the dock daemon, never shown by any command). thinknsh login with no arguments, --password, --token or an email signs you in to ThinkNCollab; with -u, --password-stdin or a registry host it logs in to a container registry. thinknsh push ecr://… (also gar://, gcr://, ghcr://) gets the registry and a short-lived login from that cloud's CLI and pushes through dock; push --export IMAGE writes it to an archive (thinknsh save). Registries on localhost/127.0.0.1 use plain HTTP. A registry for the whole LAN (thinknsh registry start --lan) is TLS with its own certificate: other machines pin it with thinknsh registry trust HOST:PORT --fingerprint … and then pull and push over verified TLS. For another plain-HTTP registry, list its host:port in TNC_DOCK_INSECURE_REGISTRIES.
Every command has its own help, for example thinknsh run --help. The full list:
| Area | Commands |
| :--- | :--- |
| Containers | run, create, start, stop, restart, kill, rm, ps, logs, exec, wait, inspect |
| Images | images, pull, push, build (--platform a,b --push), tag, rmi, image prune, search, manifest create / inspect / push / rm |
| Registries | login [-u USER] [--password-stdin] [REGISTRY], logout [REGISTRY] |
| Agent workspaces | workspace up / open / apps / ls / shell / exec / ssh-config / stop / rm, workspace share / join / joined / leave (a teammate's VS Code on your workspace) |
| Sandboxes | dev, sandbox start / freeze / resume / ps / logs / stats / exec / share / destroy, freeze, resume, deploy — project folders as dock containers |
| Dev services | service start postgres\|redis\|mysql\|mongo [-p PORT], service stop / restart / status / logs / rm [-v] |
| Local registry | registry start [--lan] [PORT] / stop / status / push IMAGE / pull IMAGE / trust HOST:PORT |
| Kubernetes | k8s up / status / down / rm / kubeconfig / load IMAGE / kubectl … (a local cluster in one command), cluster k8s up / status / kubeconfig / down (across your servers) |
| Apps | compose up / down / ps / logs / exec / run / create / build / pull / push / start / stop / restart / kill / pause / unpause / rm / top / port / images / cp / scale / wait / events / ls / watch / config |
| Storage and networks | volume ls / create / rm / inspect / prune, network ls / create / rm / connect / disconnect / prune |
| Files and state | cp, diff, export, commit, save, load, import, history, stats, top, pause / unpause, rename, update, port |
| Engine | system info / df / prune, events, dock setup / start / stop / status / selftest / check / config / autostart / diagnose / reset |
| Other tools and engines | dock use [--system] [--off] (engine CLI, compose, buildx, VS Code Dev Containers, testcontainers, the standard socket path), dock env, dock migrate |
| Desktop | dock app install (menu-bar app on macOS, tray icon on Windows), dock ui — dashboard in the browser: containers by compose app, logs with a filter, live stats, a terminal, images, volumes, networks, settings, troubleshooting |
| CI on this machine | ci run [WORKFLOW] [--job ID], ci list — .tnc/workflows jobs, matrix legs for amd64 and arm64, services, JavaScript / composite / container actions, artifacts, each in a fresh container |
One container for all your coding agents: thinknsh workspace
Instead of a separate sandbox for every AI tool, run one secure TNC container and point every agent and editor at it: Claude desktop, the Codex app, Cursor, Antigravity IDE, VS Code, and the claude / codex CLIs.
thinknsh workspace up ~/code/myapp # one project → /work
thinknsh workspace up ~/web ~/api ~/infra --name main # several → /work/web, /work/api, /work/infra
thinknsh workspace apps # which apps are installed and how each connects
thinknsh workspace open main --app cursor # editors open straight onto it (cursor, antigravity, vscode)
ssh tnc-main # terminal; then claude, codex, npm test, …| App | How it connects |
| :--- | :--- |
| Claude desktop | Code tab → environment picker → SSH → tnc-<name> → folder /work |
| Codex app | Settings → Connections → enable tnc-<name> → folder /work (log in once: thinknsh workspace exec <name> codex login --device-auth) |
| Cursor, Antigravity IDE, VS Code | thinknsh workspace open <name> --app …, or Remote-SSH → tnc-<name> |
| Terminal | ssh tnc-<name> or thinknsh workspace shell <name> |
Antigravity: only the IDE has SSH; the Antigravity agent manager app does not. VS Code needs the Remote - SSH extension.
What you get: your folders inside the container (edits land on your Mac at once), a home volume that keeps agent logins and editor servers across rebuilds, and one set of RAM/CPU limits (-m 2g --cpus 2 by default) for all the tools together. With several folders, editors open /run/tnc-workspace/<name>.code-workspace (a multi-root workspace).
Security: SSH listens on 127.0.0.1 only, with a per-workspace key and a pinned host key (no trust-on-first-use, no passwords, no root login). Sessions run as user tnc with zero Linux capabilities, no-new-privileges, no sudo and no setuid binaries, so an agent cannot become root inside the container. Process and memory limits apply. For a system package, you (not the agent) run thinknsh workspace exec --root <name> apt-get install …. Apps that connect run their own engine inside the workspace with your login for that app (Claude, Codex), stored in the workspace's home volume. workspace up writes the tnc-<name> host entries into a marked block at the end of ~/.ssh/config (skip with --no-ssh-config); workspace rm removes them and never touches your folders.
What runs where:
| Where | What |
| :--- | :--- |
| Inside the workspace (one per project, or one per --name for several folders) | Every agent and editor server, your code under /work, language tools, tests, npm / pip installs in the home volume |
| Next to it, as separate containers | Databases and services you start with thinknsh compose up or thinknsh run; the workspace joins their networks and reaches them by name |
| On your machine | The dock engine itself (and, on macOS, the Linux VM it runs containers in) |
The workspace cannot start containers itself: it has no access to the engine and no Linux capabilities, which is what keeps an agent from escaping it. Start services from your own terminal; the workspace joins their network so agents reach them by service name:
thinknsh compose up -d # in the project folder: db, redis, … on <project>_default
thinknsh workspace up # finds compose.yaml in the folder and joins that project's networks
thinknsh workspace exec myapp getent hosts db # agents use postgres://db:5432, http://api:3000, …--compose FILE|DIR picks another compose project, --no-compose joins none, and --network NET (repeatable) joins any other network. The choice is remembered for the next workspace up, and workspace ls shows the networks. The order of compose up and workspace up does not matter: a compose network that does not exist yet is created then, the way compose up would. Joining a network only adds reach to the containers on it; the workspace keeps zero capabilities and still has no engine access. While the workspace is on a compose network, compose down leaves that network in place (it is in use) and the next compose up reuses it.
New here? Read the step-by-step guide: docs/HOW-TO-USE.md.
What works today
| Feature | Status |
| :--- | :--- |
| Run, attach, interactive terminals, exec, logs, exit codes, signals | ✅ |
| Pull from public and private OCI registries (token and basic auth) | ✅ |
| Build: Containerfile, multi-stage, build args, targets, layer cache, .tncignore, RUN --mount (cache, secret, bind, tmpfs, ssh), heredocs | ✅ |
| Build: independent stages at the same time; --cache-from / --cache-to (registry, local folder, inline) to share the cache with CI and other machines | ✅ |
| Build: --ssh default (your SSH agent for RUN --mount=type=ssh, e.g. git clone of private repos; keys never leave the agent) | ✅ needs runtime bundle 0.2.3+ |
| Pushes and pulls that survive a dropped connection (chunked uploads, resumed downloads) | ✅ |
| Image signatures: trust key generate, trust sign, trust verify (the format cosign reads); only signed pulls with dock config --trust-key; keyless with --keyless | ✅ keyless needs cosign installed |
| Vulnerability scan and SBOM: image scan (apk, deb, rpm, npm, Python packages against OSV; --exit-code for CI; CycloneDX / SPDX) | ✅ OS advisories for Alpine, Debian, Ubuntu, AlmaLinux, Rocky, openSUSE; Fedora and Amazon Linux: packages listed only |
| userns-remap: the root of containers (and of build steps) is an unprivileged id range on the host (dock config --userns-remap default) | ✅ Linux as root; needs runtime bundle 0.2.3+ |
| Overlay networks across machines (network create -d overlay, VXLAN), names of every machine's containers | ✅ Linux as root |
| Encrypted overlays (-o encrypted -o key=…: IPsec ESP, AES-256-GCM, per-direction keys; plain VXLAN from a peer dropped) | ✅ Linux as root |
| Kubernetes on this machine (thinknsh k8s up: k3s, kubectl context thinknsh, local images with k8s load, Secrets encrypted at rest) | ✅ on Linux; macOS and Windows VM: needs runtime bundle 0.2.6 or newer |
| BuildKit: buildx and BuildKit-mode builds through the engine CLI (--secret, cache mounts, and SSH-agent forwarding in BuildKit mode) | ✅ |
| buildx multi-platform: buildx build --platform linux/amd64,linux/arm64 --push (one OCI index, pushed with dock's logins), --load | ✅ |
| Compose: build, depends_on with service_healthy, healthchecks, profiles, .env, extends, secrets, configs, recreate on change | ✅ |
| Compose run, watch (sync, sync+restart, rebuild), scale, cp, top, port, ls, events and the other verbs | ✅ |
| Multi-platform images: build --platform linux/amd64,linux/arm64 --push, manifest; image search | ✅ |
| Networks with name resolution, named volumes, bind mounts, published TCP and UDP ports, host.tnc.internal | ✅ |
| IPv6 dual-stack networks (network create --ipv6 [--subnet …/64], compose enable_ipv6): addresses, routes, AAAA, outbound NAT | ✅ |
| macvlan / ipvlan networks (containers with their own address on the LAN) | ✅ Linux as root; ❌ not possible inside the macOS VM, WSL or rootless (they sit behind NAT) |
| Embedded DNS on user networks (127.0.0.11: every replica of a scaled service in turn, PTR, TCP, forwarding; needs runtime bundle 0.2.3+) | ✅ |
| systemd as PID 1 and kind/k3d nodes (--privileged: writable cgroups, host devices, SIGRTMIN+3 stop signal) | ✅ |
| cgroup v1 Linux hosts (for example RHEL/CentOS 8): limits, stats, top | ✅ (CI covers v2 only) |
| linux/amd64 images on Apple Silicon (Rosetta 2; P8 compatibility check is optional) | ✅ |
| Copy files in and out (cp), commit, save/load, export/import, stats, top | ✅ |
| Unmodified tools: engine CLI, compose, VS Code Dev Containers (incl. Features), testcontainers | ✅ checked by tests/ecosystem |
| Move images and volumes over from another engine (dock migrate) | ✅ |
| Dashboard in the browser (dock ui), with settings, troubleshooting and a terminal | ✅ |
| Local CI (ci run, and TNC CI/CD runs from the dashboard): jobs, needs, matrix, both CPUs on one machine, services on localhost, GITHUB_ENV/GITHUB_OUTPUT | ✅ (macOS/Windows jobs and third-party actions are skipped) |
| --network container:<name> and compose network_mode: service:<name> | ✅ |
| Menu-bar app (macOS) / tray icon (Windows) / applications-menu launcher (Linux), all with the ThinkNCollab logo; start at login (dock autostart) | ✅ |
| Installers with their own Node.js: .pkg/.dmg, Windows setup, Linux tarball + systemd | ✅ built in CI (dock-bundle.yml); signing when the certificates are set |
| Corporate proxy and CA certificates, registry mirrors, insecure registries (dock config) | ✅ |
| Registry passwords in the system keychain (macOS Keychain, Windows Credential Manager, Secret Service) | ✅ |
| ThinkNCollab sign-in for every command: browser login (PKCE), token in the system keychain, auth status / sessions / revoke, THINKNCOLLAB_TOKEN for CI | ✅ browser login and --token need the platform update in docs/PLATFORM-AUTH.md deployed; --password works today |
| Diagnostics bundle, factory reset (dock diagnose, dock reset) | ✅ |
| GPUs (--gpus, compose deploy.resources.reservations.devices, CDI names like nvidia.com/gpu=all) | ✅ Linux and WSL2 through CDI (NVIDIA Container Toolkit); ❌ not possible on macOS |
| Registry logins from credential helpers (ECR, GCR, OS keychains: credHelpers / credsStore of the engine CLI config, or dock config --credential-helper) | ✅ |
| zstd-compressed image layers | ✅ |
| Prometheus metrics (GET /metrics on the engine socket) | ✅ |
| Push to a registry (skips existing layers, cross-repo mount), registry login/logout | ✅ |
| Agent workspaces over SSH (key-only, loopback, no capabilities) | ✅ |
| Rootless mode on Linux (a normal user, no sudo: user namespaces, pasta / slirp4netns; limits and pause through the cgroup systemd delegates to the user) | ✅ |
| Deploy compose apps to your own servers | ✅ thinknsh cluster deploy |
| Between your servers: pod traffic over TLS keyed by each server's own key (mesh), secrets sealed to the servers (the platform cannot read them) | ✅ needs the matching thinknagent |
| Kubernetes across your servers (thinknsh cluster k8s up: k3s set up by thinknagent, WireGuard between nodes, join token and kubeconfig sealed end to end) | ✅ needs the matching thinknagent |
Platforms
| Platform | How containers run | Status |
| :--- | :--- | :--- |
| macOS, Apple Silicon | Small Linux VM on Apple Virtualization.framework (tnc-vz). It boots on the first container and sleeps after 5 idle minutes. | ✅ Verified: unit, check suite, e2e, cluster and selftest |
| macOS, Intel | Same VM, x86_64 kernel | 🟡 Built, waiting for selftest reports |
| Windows 10/11, x64 or ARM64 | Dedicated WSL2 distro tnc-dock. C:\ paths work in -v. The distro stops when idle. | 🟡 Built, waiting for selftest reports |
| Linux, x86_64 or aarch64 | Native namespaces and cgroups, no VM | 🟡 CI job set up, first results pending |
Memory (measured, not estimated)
Measured on an Apple Silicon Mac with thinknsh bench. Run the same command on your machine to measure it there:
| State | Memory | | :--- | :--- | | dock running, VM asleep | ≈ 18 MB | | VM awake, idle | ≈ 306 MB | | postgres + redis running | ≈ 491–563 MB |
Install
Downloads and the full guide are at https://thinkncollab.com/dock.
Installers (no Node.js needed; they bring Node 24): Thinknsh-<version>.dmg for macOS,
Thinknsh-<version>-<arch>-setup.exe for Windows, thinknsh-<version>-linux-<arch>.tar.gz
for Linux (sudo ./thinknsh/install.sh). They set up the runtime, start dock at login and
install the menu-bar / tray app. Built by native/installer/ (see .github/workflows/dock-bundle.yml).
With npm:
- Node.js 22.5 or newer. dock stores its state with
node:sqlite. - Windows only: turn on WSL2 in an administrator PowerShell, then reboot. If WSL is already installed, run
wsl --updateinstead.wsl --install --no-distribution - Install thinknsh and the runtime.
setuppicks the right files for your OS and CPU, checks every sha256 against the bundle manifest, and installs them:
On Linux, as a normal user, dock runs rootless (no sudo): it needsnpm install -g https://thinkncollab.com/downloads/dock/0.2.0/thinkncollab-shell.tgz thinknsh dock setupuidmapandpasst, and subordinate ids (sudo usermod --add-subuids 100000-165535 --add-subgids 100000-165535 $USER);thinknsh dock setuplists anything missing. To run it as a system service instead, runsudo thinknsh dock setupandsudo thinknsh dock start(orsudo thinknsh dock autostart onfor a systemd service), thensudo groupadd tnc-dock && sudo usermod -aG tnc-dock $USERand restart dock to use the commands without sudo. The engine listens on/run/thinknsh/dock.sockfor every user; settings are system-wide in/etc/thinknsh/config.json(change them withsudo thinknsh dock config …). On a machine without internet, download the files for your platform andmanifest.jsonfrom the downloads page into one folder, then runthinknsh dock setup --from <folder>. - Run something:
Then open http://localhost:8080.thinknsh run --rm -p 8080:80 nginx:alpine - Optional:
thinknsh dock autostart on(start at login) andthinknsh dock app install(menu-bar / tray app).
Check it works on your machine
thinknsh dock selftest # 12 real checks; writes ~/.tnc/dock/selftest-<os>-<cpu>-<time>.json
thinknsh dock check # all API/CLI compatibility cases; P8 is reported but is not required at the current P7 phase
thinknsh bench idle # memory, measured on this machineIf a check fails, send the selftest JSON file. It contains the machine details and the exact error of each check.
For contributors: build and test from source
git clone -b shell/dock <repo> && cd ThinkNCollab-Shell-V2 && npm install
native/bundle/build.sh aarch64 dist-bundles # also: x86_64, darwin (macOS only)
native/bundle/build.sh manifest dist-bundles 0.2.2
node bin/thinknsh.js dock setup --from dist-bundles
npm test # unit tests (CLI, compose, engine, Windows backend)
node tests/dock-e2e.js # end to end against the running daemon
node bin/thinknsh.js dock check # every command against the running daemonArchitecture and the runtime layout are documented in src/dock/README.md.
A step-by-step guide for users is in docs/HOW-TO-USE.md.
⚡ Core Capabilities
1. One container engine for everything
- Containers, apps and services through dock:
run,build,compose,workspace,serviceandregistryall run on the same engine (see the containers section above). On macOS that is one small Linux VM (tnc-vz) that sleeps when idle; on Windows one WSL2 distro; on Linux the host kernel. - Dev databases in one command:
thinknsh service start postgres(alsoredis,mysql,mongo) runs it as a container on127.0.0.1, waits until it is healthy, prints the connection URL, and keeps its data in a volume across restarts and upgrades. - Bind mounts from your folders:
-v ./src:/appshares files both ways (VirtioFS on macOS,/mnt/con Windows). - Port conflict protection: publishing a port that is already in use fails with a message instead of taking over the running program.
- Older names still work:
capsule,vault,mesh,stackandvmrunbuild/images,volume,network,composeanddock, and print the new command each time.vault backup/restorecopy a volume to or from a.tar.gzfile. - Sandboxes are dock containers too:
thinknsh devdetects the project (Node, Python, Go, Rust, C/C++ orthinkncollab.yml), runs it in the containertnc-sb-<name>with the folder at/workand the dependencies in a volume of their own, installed inside the first time and again only whenpackage.json/requirements.txtchange.freezestops it (0 CPU, 0 RAM, files and dependencies kept) andresumestarts it in about a second. The older separate sandbox engine is gone; one engine runs everything.
2. Multi-Layer Collaborative State Sync (room share / room pull)
- Share entire development environments between teammates in seconds without third-party registries.
- Encrypted Multi-Layer Bundle: Packages workspace code, dumps of your running dock services (
thinknsh service: Postgres, MySQL, Mongo, Redis), and sanitized.envsecrets into a single AES-256-GCM encrypted bundle.room pullstarts the same services on the teammate's machine and loads the dumps into them. - A key per bundle, handed over by you:
room shareprints a sync code (tnc1-…) that holds the bundle's key. Send it to the teammates who should get the state; they runroom pull <state> --code tnc1-…. ThinkNCollab stores and relays only ciphertext and never sees the code. - Hybrid Transport: Direct Gigabit Wi-Fi LAN P2P mesh (zero cloud bandwidth) with automatic fallback to ephemeral in-memory cloud socket relays.
3. Smart 3-Way Code & Secret Merge Engine
- Non-Destructive: Local files created by developers are never deleted during sync.
- Git 3-Way Line Merge (
git merge-file): Non-conflicting edits auto-merge with zero conflicts. Overlapping edits receive standard conflict markers (<<<<<<< LOCAL...>>>>>>> INCOMING), activating VS Code's interactive CodeLens UI. - Smart
.envReconciliation: Preserves local developer overrides (custom ports, local keys) while appending missing teammate secrets. - 1-Click Safety Undo (
room undo): Pre-merge safety snapshots allow instant rollback if desired.
4. Low-Bandwidth Terminal Multiplexing
- Semantic ANSI Text vs Video Pixels: Streams UTF-8 terminal text chunks over WebSockets instead of rendering video frames, eliminating screen sharing latency and blur.
- Sub-Millisecond Dynamic RBAC: Grant and revoke peer keyboard input access in real-time.
- End to end, always: every share has its own random key, carried only in the link's
#k=…part, which browsers never send to the server. Output and input are AES-256-GCM under that key; the platform relays ciphertext only, and unencrypted input is refused. - AAD Replay Defense: each chunk is bound to the session and a sequence number (
term-input:${sessionId}:${seq}); an input runs once, and only within two minutes of being typed. - Emergency Host Lock: Instantly drop all remote input with one command.
5. Signal-Grade E2EE Security
- 60-Digit Out-of-Band Safety Numbers: Verify channels on calls to guarantee zero MITM interception.
- TOFU Registry: Trust-On-First-Use cryptographic registry for peer public keys.
- Forward Secrecy Key Rotation (
room rotate-key): Automatically rekeys rooms when members leave, preventing evicted members from decrypting future streams or states.
🖥️ Terminal Sharing Architecture
ThinkNCollab terminal pair programming operates on semantic text streams rather than video capture:
- Text Streams Over WebSocket: Raw PTY output (ANSI escape sequences and UTF-8 characters) is encrypted and streamed directly to connected peers, rendering natively in their local terminal client.
- Zero Video Overhead: Avoids high-bandwidth video encoding/decoding, delivering sharp text reproduction and minimal latency even over constrained networks.
- Cryptographic Session Integrity: Every packet carries a sequence number and an AES-256-GCM authentication tag bound to the session, under a key only the people with the share link have.
📋 Platform Isolation Matrix
| Capability | macOS | Linux | Windows (WSL2) |
| :--- | :--- | :--- | :--- |
| Isolation Primitive | Apple Virtualization (tnc-vz MicroVM + crun) / Seatbelt fallback | Kernel namespaces (unshare / crun) | WSL2 utility environment |
| Resource Caps | Dynamic Memory Ballooning + VirtioFS | cgroups v2 (memory, CPU, pids) | WSL2 cgroups v2 |
| Networking & Discovery | Native vsock relay + Virtio-Net | Virtual bridge + veth + iptables | Netsh port proxy + localhost |
| Snapshot Strategy | APFS Copy-on-Write (cp -cR) | Btrfs / XFS reflink (--reflink=auto) | VSS / Directory copy fallback |
🚀 Installation & Quick Start
# Install globally via npm
npm install -g thinkncollab-shell
# Or run instantly via npx
npx thinkncollab-shellBoth thinknsh and tnc command shortcuts are registered:
thinknsh --version
# 2.0.0💻 CLI Cheat Sheet
Containers
thinknsh run -d --name pg -p 5433:5432 -e POSTGRES_PASSWORD=secret postgres:alpine
thinknsh run -d --name cache -p 6379:6379 -m 512m redis:alpine
thinknsh ps
thinknsh exec pg psql -U postgres -c "SELECT version();"
thinknsh logs -f pg
thinknsh stop pg && thinknsh rm pg
thinknsh compose up -dRoom State & Database Sync
thinknsh room share [name] # Publish code + the dock services' data (Postgres, MySQL, Mongo, Redis)
thinknsh room share --no-code # Publish database & environment only
thinknsh room pull [state-id] --code tnc1-… # Smart-merge teammate state (code from the author)
thinknsh room merge [state-id] # Explicit 3-way merge
thinknsh room undo # Rollback last merge from safety backup
thinknsh room states # List shared states with service & code indicators
thinknsh room verify # Display 60-digit E2EE safety number & TOFU peers
thinknsh room rotate-key # Rekey room for forward secrecyOpen a teammate's workspace in your own VS Code
thinknsh workspace share main # owner: prints a join code, asks before letting anyone in
thinknsh workspace join CODE # teammate: adds host tnc-join-… and opens VS Code on itThe teammate gets a guest container with your folders and services but its own home (none of your Claude / Codex logins). SSH end to end, checked against the key fingerprint in the code; the code's secret never reaches ThinkNCollab. Directly over a private local network when both are on one, otherwise relayed by ThinkNCollab. Ctrl-C on the owner's side removes the guest container.
Real-Time Terminal Pair Programming
thinknsh share # Start real-time PTY terminal sharing session
thinknsh share --readonly # Start in read-only broadcast modeSandboxes (dock containers)
thinknsh dev --port 3000 # Detect the project and run it in container tnc-sb-<folder>
thinknsh sandbox ps # Sandboxes, ports, images
thinknsh freeze <name> # Stop it: 0% CPU/RAM, files and dependencies kept
thinknsh resume <name> # Start it again, nothing to reinstall
thinknsh sandbox exec <name> # Shell inside (or: use <name> in the thinknsh shell)
thinknsh deploy # Production sandbox here (servers: thinknsh cluster deploy)
thinknsh snapshot create <name> # Create sub-second CoW volume snapshot
thinknsh snapshot restore <name> # Restore volume stateMulti-Language Package Manager (dep)
thinknsh dep install <pkg> # Track & install package across npm/pip/cargo/go
thinknsh dep list # List all tracked dependencies
thinknsh dep sync # Reconcile environment from thinkncollab.yml📄 License
Apache License 2.0. See LICENSE for details.
Copyright (c) 2024-2026 ThinkNCollab Systems Inc. All rights reserved.
