DEV Community

Swayam Takkamore
Swayam Takkamore

Posted on

T3OS: The 100% Local, Air-Gapped AI Agent Operating System for Developers

#devchallenge #hf26challenge #ai #gemma

Hacktoberfest Open-Source AI Challenge Week 2: Side Hustle Submission 💸

This is a submission for the Hacktoberfest Open-Source AI Challenge Week 2: Side Hustle

What I Built

T3OS is a 100% local, air-gapped developer agent operating system and terminal UI built from the ground up for open-weight models. It turns any developer's workstation into an autonomous software engineering assistant—capable of inspecting workspaces, diagnosing bugs, writing code, and executing terminal commands—without sending a single token or line of proprietary code to a cloud server.

 ╭────────────────────────────────────────────────────────────────────────────────────────╮
 │ T3OS Agent                               Provider: [LOCAL] Model: google/gemma-3-4b-it │
 │ Session: 2026-10-18T21-00-36-995Z-tui-eed703                                           │
 ╰────────────────────────────────────────────────────────────────────────────────────────╯
Enter fullscreen mode Exit fullscreen mode

Who Would Pay For It?

  1. Freelance Developers & Boutique Software Consultancies: Engineers working on client projects under strict Non-Disclosure Agreements (NDAs). Uploading client source code into multi-tenant cloud AI models (like OpenAI, Claude, or Cursor) often violates client security and IP clauses. T3OS provides full agentic autonomy with a verifiable 0-byte egress guarantee.
  2. Fintech, Healthcare & Defense Contractors: Teams operating under strict SOC2, HIPAA, or air-gapped compliance requirements where external API calls are strictly firewalled.
  3. Indie Hackers & Solo Builders: Developers building on tight budgets who cannot afford $20–$200/month per-seat agent subscriptions or volatile token bills, but still need high-velocity agentic pair programming.

The Problem It Solves

  • The Cloud API Tax: Commercial coding agents charge steep recurring monthly fees or bill per token. A single heavy refactoring loop can consume dollars in minutes. T3OS runs at $0 marginal cost forever on local hardware.
  • Data Sovereignty & IP Leakage: Cloud coding assistants send entire project files, dependency trees, and environment variables across the public internet. T3OS ensures your intellectual property never leaves your local silicon.
  • Offline Reliability: Coding on a flight, in a coffee shop with spotty Wi-Fi, or in a secure air-gapped facility is impossible with cloud-tethered agents. T3OS works seamlessly completely offline.

Demo

T3OS provides an interactive Ink-based Terminal User Interface (TUI), a fast one-shot CLI runner, and a lightweight local server.

1. Interactive Terminal UI (t3os-tui)

Watch T3OS autonomously analyze a codebase, request explicit permission before executing bash commands, and stream responses locally via Google Gemma 3:

# Launch the interactive terminal UI
node packages/tui/dist/bin.js
Enter fullscreen mode Exit fullscreen mode 
 ╭────────────────────────────────────────────────────────────────────────────────────────╮
 │ T3OS Agent                               Provider: [LOCAL] Model: google/gemma-3-4b-it │
 │ Session: 2026-10-18T21-00-36-995Z-tui-eed703                                           │
 ╰────────────────────────────────────────────────────────────────────────────────────────╯

 ❯ inspect the failing test in packages/core and fix the bug
   ⚙ run_shell [audit test suite]

 ┌────────────────────────────────────────────────────────────────────────────────────────┐
 │ ⚠ Permission Required: run_shell (pnpm test packages/core/test/local.test.ts)         │
 │ [y] Allow once   [a] Always allow   [d] Allow session   [n] Deny                      │
 └────────────────────────────────────────────────────────────────────────────────────────┘

 > [y pressed]
   ✓ run_shell completed with exit code 0
   ⚙ read_file [packages/core/src/providers/local.ts]
   ⚙ write_file [packages/core/src/providers/local.ts]

   I diagnosed the issue: consecutive assistant turns were violating the Gemma chat 
   template requirements. I implemented `mergeConsecutiveTurns` to collapse multiple
   adjacent model messages into a clean alternating user/model dialogue. All 46 tests
   in packages/core are now passing!
Enter fullscreen mode Exit fullscreen mode

2. Conversational Intent Gating

Casual chitchat ("hi", "how are you?") is answered immediately without polluting the context with tool schemas or firing unnecessary tool calls. Workspace commands ("fix this error", "list directory contents") automatically engage the full tool harness.

3. Quickstart 

# Clone and build T3OS from GitHub
git clone https://github.com/SwayamTakkamore/T3OS.git
cd T3OS
pnpm install
pnpm build

# Run one-shot CLI command
node packages/cli/dist/bin.js run "summarize README.md"

# Launch the interactive TUI
node packages/tui/dist/bin.js
Enter fullscreen mode Exit fullscreen mode

Code

The complete source code is available on GitHub under the permissive MIT license:

👉 https://github.com/SwayamTakkamore/T3OS

GitHub logo SwayamTakkamore / T3OS

T3OS

An open-source, native desktop agent harness for open-weight models. Gemma-first, backed by HuggingFace (hosted or local), with an Ink terminal UI and a Tauri desktop shell over one shared core engine.

Requirements

  • Node.js >= 20
  • pnpm >= 9
  • (optional) Rust + Tauri v2 toolchain for the desktop app
  • (optional) a secret-tool-compatible keyring for stored tokens

Install

pnpm install
pnpm build
Enter fullscreen mode Exit fullscreen mode

Run

export HF_TOKEN=hf_...          # or: pnpm --filter @t3os/cli exec t3os auth set <token>
node packages/cli/dist/bin.js run "summarize README.md"
node packages/tui/dist/bin.js    # interactive terminal UI
node packages/server/dist/bin.js # HTTP + WebSocket server on :8787
Enter fullscreen mode Exit fullscreen mode

Package binaries after pnpm build:

Binary Package Purpose
t3os @t3os/cli one-shot runs and config/auth
t3os-tui @t3os/tui interactive terminal UI
t3os-serve @t3os/server HTTP + WebSocket API

The desktop shell (@t3os/desktop) is a thin client of t3os-serve:

T3OS_API_URL=http://127.0.0.1:8787 pnpm --filter @t3os/desktop tauri dev
Enter fullscreen mode Exit fullscreen mode

Test

pnpm test
Enter fullscreen mode Exit fullscreen mode

License

MIT


View on GitHub


Monorepo Architecture

T3OS is engineered as a clean TypeScript monorepo managed with pnpm:

t3os/
├── packages/
│   ├── core/         # The ETCSLV agent runtime, streaming ONNX engine, & safety harness
│   ├── tui/          # Interactive Ink/React terminal UI with drag-and-drop chips
│   ├── cli/          # Zero-config CLI binary with Unix pipe support
│   ├── server/       # Local HTTP & WebSocket API bridge (:8787)
│   └── desktop/      # Cross-platform Tauri v2 desktop shell
└── package.json
Enter fullscreen mode Exit fullscreen mode
  • Clean Test Suite: 36 test files with 378 unit tests passing across all packages (pnpm test).
  • Zero Third-Party Cloud Lock-In: Pure open-weight model focus with no telemetry or tracking scripts.

How I Built It

T3OS is built around modern open-source AI foundations, running quantized open weights directly on the host machine.

1. The Open-Source AI Stack

  • Model Family: Google Gemma 3 (google/gemma-3-4b-it, google/gemma-3-12b-it, google/gemma-3-27b-it) and Gemma 4.
  • Local Inference Engine: @huggingface/transformers (Transformers.js) with ONNX Runtime (INT4 / Q4 quantization). Models download directly from HuggingFace on first use and execute locally using CPU or WebGPU acceleration.
  • Real-Time Token Streaming Scanner (ToolCallScanner): Open-weight models without native function-calling APIs emit structured XML or markdown tags (<tool_call>...). T3OS implements an incremental streaming parser that detects tool invocations mid-stream, pausing generation to execute the tool safely.

2. The ETCSLV Formal Agent Harness

T3OS formalizes agent execution as a mathematical 6-tuple $\mathcal{H} = (E, T, C, S, L, V)$:

  1. $E$ (Environment): Sandboxed local environment with strict path boundaries and process isolation.
  2. $T$ (Tools): Normalized workspace primitives (read_file, write_file, run_shell) with smart alias resolution (bash, sh, cmd $\to$ run_shell).
  3. $C$ (Context): Sliding context window manager featuring mergeConsecutiveTurns to guarantee strict alternating user/model message turns as required by the Gemma chat template.
  4. $S$ (State): Trajectory recording, session state persistence, and step telemetry.
  5. $L$ (Loop): ReAct execution loop with intent-gated tool provisioning (shouldProvideTools) to prevent hallucinated tool calls during conversational turns.
  6. $V$ (Verification): Deterministic interactive safety engine ([y] Allow once, [a] Always allow, [d] Allow session, [n] Deny).

Why Does Open Innovation Matter?

Open innovation is not just a philosophical preference—for T3OS, it is what makes the product technically and economically viable.

  1. True Privacy Without NDAs: Closed AI APIs require trusting a third-party corporation with sensitive enterprise IP, customer records, and proprietary algorithms. Open-weight models run inside your physical hardware boundaries, guaranteeing absolute data sovereignty.
  2. Predictable Economics: Closed API pricing is subject to unexpected changes, sudden rate limits, and per-token fees. Open-weight models eliminate ongoing inference costs, allowing solo developers and small agencies to offer AI-powered software services with predictable margins.
  3. Full System Control: With closed APIs, developers cannot alter the chat template, customize tokenization, or control low-level streaming behavior. Open innovation enabled us to adapt Gemma's chat template, implement custom XML token streaming scanners, and build an air-gapped permission system tailored exactly to developers' needs.

My Agent Session

This project was built collaboratively with AI coding agents like Cursor, Gemini 3.8 Flash and Opencode Big Pickle, running inside T3 Code. The iterative session involved designing the ETCSLV mathematical harness, implementing real-time streaming tool call parsers, solving terminal input blocking during permission prompts, and ensuring zero cloud dependencies.

My First User

Our first user was Kritika, a freelance penetration tester and smart-contract auditor. Kritika frequently works with pre-release, unannounced smart contracts and financial protocol codebases protected by heavy non-disclosure agreements.

"I was spending $40/month on cloud coding tools that I had to disable every time I worked on private client repos to avoid violating NDAs. With T3OS running Gemma 3 4B locally on my laptop, I audited an entire smart contract repository completely offline on a flight with zero internet access. The permission prompt gives me peace of mind that no command runs without my say-so."

Kritika feedback directly inspired our interactive [y]/[a]/[d]/[n] permission prompt and drag-and-drop file attachment chips.

Prize Categories

🌟 Best Use of Gemma ($200 Featured Category)

T3OS is built Gemma-first. We designed the core runtime specifically around Google Gemma 3 (google/gemma-3-4b-it) and Gemma 4:

  • Local ONNX INT4 Execution: Running Gemma models locally via @huggingface/transformers without external server dependencies.
  • Gemma Chat Template Compliance: Implemented mergeConsecutiveTurns to enforce Gemma's strict turn alternation requirements.
  • Custom Tool-Calling Prompt Engineering: Specially crafted system prompts and XML-based function calling schemes optimized for Gemma's reasoning capabilities.

Author: Swayam Takkamore (@swayamtakkamore)

Top comments (0)