Getting Started with gosec

This guide walks you through compiling gosec, running diagnostics, inspecting local LLM runtime models, and executing the backlog manager.

1. Prerequisites

Before getting started, ensure you have:

Go Toolchain: Go 1.27.1 or higher (compiled with CGO_ENABLED=0).
Make: GNU Make for running automation recipes.
Ollama (Optional for $0.00 Tier): Local Ollama daemon running on http://127.0.0.1:11434.
Node.js (Optional for Web Portal): Node 20+ with npm for building the Astro portal.

2. Installation & Compilation

Clone & Make (Recommended)Go InstallMulti-Arch Release Packaging

git clone https://github.com/gosecio/gosec.git
cd gosec
make build

This compiles zero-CGo static binaries directly into bin/: - bin/gosec: The human developer CLI. - bin/mcp-server: The stdio JSON-RPC 2.0 Model Context Protocol server.

CGO_ENABLED=0 go install -ldflags="-s -w" github.com/gosecio/gosec/cmd/gosec@latest
CGO_ENABLED=0 go install -ldflags="-s -w" github.com/gosecio/gosec/cmd/mcp-server@latest

make dist
# Builds tar.gz and zip archives for Darwin, Linux, and Windows to dist/

Verify the installation:

./bin/gosec version
# Output: gosec version 0.0.2

3. System Health & Environment Doctor

Run the built-in system diagnostics suite:

./bin/gosec doctor

Sample diagnostic report:

Running gosec system diagnostic checks...
=========================================
[OK] Go Compiler: go version go1.27.1 darwin/arm64
[OK] Git VCS: git version 2.48.1
[OK] Ollama Runtime: http://127.0.0.1:11434 (Installed models: qwen3-coder:30b, deepseek-r1:14b, llama3.3:70b)

All diagnostic checks passed. System is ready.

4. Pure-Go SQLite Backlog Management

gosec embeds a pure-Go SQLite ledger (local/backlog.sqlite) for task and dependency coordination:

Inspect Ready TasksBacklog Metrics & StatsList All Tasks

./bin/gosec backlog ready

Displays tasks whose prerequisites have been completed and are ready to execute.

./bin/gosec backlog stats

Reports total tasks, distribution across 6 phases, and average completion velocities.

./bin/gosec backlog list --stage=in_progress

5. Local LLM Runtime ($0.00 Tier)

Check your local Ollama connection and model catalogue:

# Check daemon connectivity
./bin/gosec llm status

# List installed local models
./bin/gosec llm list

# Check models loaded in GPU/VRAM
./bin/gosec llm ps

# Test a fast zero-cost generation
./bin/gosec llm generate "Explain Go channels in two sentences."

6. Astro Landing Portal & Cloudflare Pages

To test or deploy the unified Astro web portal and MkDocs documentation:

# Launch Astro local development server
make website-dev

# Build unified portal and docs
make website-build

# Deploy both website and docs to Cloudflare Pages
make deploy

🛡️ Next Steps: Runtime Security with ctxsec.io

Once your gosec application is running, integrate ctxsec.io to protect your AI agent tool calls with Google CEL policy hypervisors and in-kernel OS process sandboxing.