DOCUMENTATION · COMPREHENSIVE SETUP & ARCHITECTURE MANUAL

Complete Setup & Usage Guide

Code68 is an independent, autonomous terminal coding agent. This guide covers everything: from running the heavy LLM server on free Kaggle GPUs or local Ollama, to configuring security levels and pair programming in any project repository.

1. The Core Concept: How Code68 Works

Unlike ordinary chatbots that just answer in text, Code68 executes a real autonomous agent loop:

┌──────────────────────────────────────────────┐
│  CLOUD LLM BRAIN (Remote GPU / Kaggle / API) │
│  • Qwen2.5-Coder-7B (4-bit NF4 Quantization) │
│  • Pure reasoning & tool decision engine    │
└──────────────────────┬───────────────────────┘
                       │  Encrypted Tunnel (Cloudflare / HTTPS)
                       ▼
┌──────────────────────────────────────────────┐
│  LOCAL AGENT (Your PC / Terminal)            │
│  • Filesystem: Surgical unified diff edits   │
│  • Search: AST symbols & ripgrep regex       │
│  • Terminal: Sandboxed execution & timeouts  │
│  • Testing: Pytest & coverage verification   │
│  • Security: Workspace boundary enforcement  │
└──────────────────────────────────────────────┘

Key Advantage: Your local machine never needs to load a heavy 15GB model into memory. Your local computer executes only lightweight Python scripts, while the remote GPU does the heavy token generation.

2. Step 1: Install Code68 Globally

Code68 requires Python 3.11 or newer. Install it with pip or pipx so the code68 binary is accessible from any terminal window:

pip install git+https://github.com/PRN-6/code68.git

Or if you prefer an isolated installation with pipx:

pipx install git+https://github.com/PRN-6/code68.git

Verify that Code68 is recognized:

code68 --version → Code68 version 0.1.0

3. Step 2: Choosing & Setting Up Your LLM Brain

Code68 uses a standardized OpenAI-compatible API layer. You can connect it to any of the following four providers:

RECOMMENDED Backend A: Free Kaggle Dual Tesla T4 GPUs

100% Free Cloud GPU

Kaggle provides 30 hours of free GPU access every week with 2x NVIDIA Tesla T4 GPUs (32GB combined VRAM). This is ideal for running Qwen2.5-Coder-7B-Instruct at maximum performance with zero local heat or battery drain.

Instructions:

Open your browser and navigate to kaggle.com/code → click New Notebook.
In the right sidebar under Settings:
- Accelerator: select GPU T4 x 2
- Internet: toggle ON (required to download model & tunnel)
Paste this single command into the notebook cell and run it:

!git clone https://github.com/PRN-6/code68.git
%cd /kaggle/working/code68
!pip install -q -r server/requirements-server.txt
!python server/kaggle_server.py

In ~2 minutes, the cell output will print your private Cloudflare tunnel URL:

CODE68 TUNNEL URL: https://random-name.trycloudflare.com/v1

Copy that URL and register it globally on your computer:

code68 config --global --set-url "https://random-name.trycloudflare.com/v1"

OFFLINE Backend B: Local Ollama (100% On-Device)

Zero Internet Required

If you have a computer with an NVIDIA GPU or Apple Silicon (M1/M2/M3/M4), you can run Code68 completely offline with Ollama.

Start Ollama with Qwen2.5-Coder:

ollama run qwen2.5-coder:7b

2. Configure Code68 to point to localhost:

code68 config --global --set-url "http://localhost:11434/v1" --set-model "qwen2.5-coder:7b"

CLOUD Backend C: OpenRouter, Groq, DeepSeek, OpenAI

Ultra-Fast Commercial APIs

If you already have an API key for OpenRouter, Groq, or DeepSeek, you can point Code68 to it without running any server:

Google Gemini (100% Free API via Google AI Studio — 24/7 Always On):

code68 config --global --set-url "https://generativelanguage.googleapis.com/v1beta/openai" --set-key "AIzaSy..." --set-model "gemini-2.0-flash"

Get your free key at aistudio.google.com. Zero cost, no server to maintain.

OpenRouter (Supports Qwen-32B, DeepSeek, Claude):

code68 config --global --set-url "https://openrouter.ai/api/v1" --set-key "sk-or-v1-..." --set-model "qwen/qwen-2.5-coder-32b-instruct"

Groq (Ultra-Low Latency):

code68 config --global --set-url "https://api.groq.com/openai/v1" --set-key "gsk_..." --set-model "qwen-2.5-coder-32b"

DEV Backend D: Local Developer Mock Server

Testing CLI & UI

Want to test Code68's terminal interface without any GPU or API key? Start the built-in mock server:

python server/kaggle_server.py

4. Step 3: Configuration & Priority Hierarchy

Code68 uses a 3-tier configuration hierarchy. Settings are resolved in this exact order:

Tier 1: Workspace

.code68/config.json in your project directory. Overrides everything for that specific repository.

Tier 2: Global Config

~/.code68/config.json in your home directory. Default settings used across all projects on your PC.

Tier 3: Environment

Standard environment variables (e.g. CODE68_BASE_URL, .env).

All Environment Variables:

Variable	Default	Purpose
CODE68_BASE_URL	http://localhost:8000/v1	Inference server OpenAI-compatible completions endpoint
CODE68_API_KEY	code68-secret-key	Bearer authentication token for the server
CODE68_MODEL	Qwen/Qwen2.5-Coder-7B-Instruct	Target model identifier
CODE68_PERMISSION_LEVEL	edit-approved	Security level (read-only, edit-approved, full-auto...)
CODE68_TIMEOUT_SECONDS	120.0	Maximum HTTP timeout for inference stream

5. Step 4: Everyday Coding Workflow

Once installed and configured, you never need to launch Code68 from its installation directory. Open any project on your computer:

# 1. Navigate to your actual project

cd D:\projects\my-web-app

# 2. Launch Code68 interactive REPL

code68

One-Shot Command Line Prompts:

You can ask Code68 to perform tasks directly from your shell without opening the interactive session:

code68 "Explain the architecture of this project"

code68 "Find all failing pytest tests and apply surgical fixes"

code68 "Refactor utils.py to use async httpx instead of requests"

6. Step 5: Interactive Slash Commands

While inside the Code68 REPL session, use slash commands to inspect state, review git diffs, save sessions, or reconfigure:

Command	Description
/help	Displays the interactive commands quick reference
/status	Check active model, endpoint connection health, and workspace root
/diff	Displays a syntax-highlighted git diff of all uncommitted changes
/undo	Prompts confirmation to revert uncommitted edits via `git checkout .`
/setup	Re-runs the interactive setup wizard to change providers on the fly
/model [name]	View or switch active model without restarting session
/sessions	List all saved conversation sessions in the current workspace
/save [id]	Persist the current conversation thread to disk
/resume <id>	Restore a previously saved session thread
/compact	Summarize older conversation history to free context tokens
/clear	Clear conversation history and re-scan the workspace
/exit	Gracefully exit Code68

7. Step 6: Security, Sandbox & Permissions

Security is built directly into Code68's architecture. Every tool call passes through validation before reaching your operating system:

• Workspace Boundary (No Traversal)

Paths containing ../.. or attempting to escape the project root are rejected by resolve_safe_path. The model cannot read files outside the repository.

• Destructive Command Interceptor

Dangerous terminal patterns (rm -rf /, disk wipes, fork bombs, git push --force) are blocked regardless of permission level.

5 Permission Levels:

1. read-only: Can only read files, search symbols, and check git status. Cannot edit files or run commands.

2. edit-approved (Default): Automatically reads files and searches. Always asks for interactive confirmation before editing files or running terminal commands.

3. auto-edit: Automatically performs file edits and diffs. Asks approval before running terminal commands or deleting files.

4. command-approved: Auto-edits and runs safe read commands. Confirms before terminal execution.

5. full-auto: Executes all non-destructive workspace operations without interactive prompts (for unattended scripts/automation).

8. Step 7: Troubleshooting & Solutions

Error: "[Errno 11001] getaddrinfo failed"

Cause: The endpoint URL is set to a placeholder (e.g. https://xxxx.trycloudflare.com) or your Kaggle server cell was stopped.
Fix: Update your URL globally: code68 config --global --set-url "https://your-new-tunnel.trycloudflare.com/v1"

Error: "Target text not found in file"

Cause: Line-ending differences between Windows (CRLF) and Unix (LF).
Fix: Code68 v0.1.0 has automatic CRLF/LF line-ending normalization built in. If it still fails, provide 2-3 lines of surrounding context to disambiguate.

How do I verify everything is working?

Run the diagnostics command in your terminal: code68 doctor It tests your Python version, Git executable, ripgrep presence, and pings your LLM endpoint.