Skip to content

INSTALLATION.md

Latest commit

 

History

History
340 lines (242 loc) · 7.72 KB

INSTALLATION.md

File metadata and controls

340 lines (242 loc) · 7.72 KB

Installation Guide

Subcog provides multiple installation methods to fit your workflow. Choose the one that best suits your environment.

Quick Install

Method Command Best For
Cargo cargo install subcog Recommended - fast native binary
Homebrew brew install zircote/tap/subcog macOS/Linux users
Docker docker run ghcr.io/zircote/subcog Containers, CI/CD
Binary GitHub Releases Manual installation
npm/npx npx @zircote/subcog --help Fallback if binary install unavailable

Cargo (Rust) - Recommended

Requires Rust 1.88+.

# From crates.io (recommended)
cargo install subcog

# From GitHub (latest)
cargo install --git https://github.com/zircote/subcog.git

# Specific version
cargo install subcog --version 0.14.0

The Cargo installation provides the fastest startup time and best performance, as it compiles a native binary optimized for your system.

Homebrew (macOS/Linux)

# Add the tap (one-time)
brew tap zircote/tap

# Install
brew install subcog

# Upgrade
brew upgrade subcog

Docker

Multi-architecture images are available on GitHub Container Registry.

Quick Start

# Run subcog in a container
docker run --rm ghcr.io/zircote/subcog --help

# With persistent storage
docker run --rm \
  -v ~/.local/share/subcog:/data \
  ghcr.io/zircote/subcog status

# Capture a memory
docker run --rm \
  -v ~/.local/share/subcog:/data \
  ghcr.io/zircote/subcog capture --namespace decisions "Use Docker for deployment"

Available Tags

Tag Description
latest Latest stable release
0.14.0 Specific version
0.14 Latest patch in minor version
sha-abc1234 Specific commit (for debugging)

Supported Architectures

  • linux/amd64 (x86_64)
  • linux/arm64 (aarch64)

Docker Compose

version: '3.8'
services:
  subcog:
    image: ghcr.io/zircote/subcog:latest
    volumes:
      - subcog-data:/data
    command: serve --http --port 8080
    ports:
      - "8080:8080"

volumes:
  subcog-data:

MCP Server in Docker

Run subcog as an MCP server for AI agent integration:

# Stdio transport (for local clients)
docker run --rm -i \
  -v ~/.local/share/subcog:/data \
  ghcr.io/zircote/subcog serve

# HTTP transport (for network access)
docker run --rm \
  -v ~/.local/share/subcog:/data \
  -p 8080:8080 \
  ghcr.io/zircote/subcog serve --http --port 8080

Image Details

Property Value
Base Image scratch
Size ~15MB compressed
User nonroot (65532)
Working Dir /data
Entrypoint /usr/local/bin/subcog

Binary Downloads

Pre-built binaries are available from GitHub Releases.

Download URLs

# macOS (Intel)
curl -LO https://github.com/zircote/subcog/releases/download/v0.14.0/subcog-0.14.0-x86_64-apple-darwin.tar.gz

# macOS (Apple Silicon)
curl -LO https://github.com/zircote/subcog/releases/download/v0.14.0/subcog-0.14.0-aarch64-apple-darwin.tar.gz

# Linux (x64, glibc)
curl -LO https://github.com/zircote/subcog/releases/download/v0.14.0/subcog-0.14.0-x86_64-unknown-linux-gnu.tar.gz

# Linux (x64, musl/Alpine)
curl -LO https://github.com/zircote/subcog/releases/download/v0.14.0/subcog-0.14.0-x86_64-unknown-linux-musl.tar.gz

# Linux (arm64, musl)
curl -LO https://github.com/zircote/subcog/releases/download/v0.14.0/subcog-0.14.0-aarch64-unknown-linux-musl.tar.gz

# Windows (x64)
curl -LO https://github.com/zircote/subcog/releases/download/v0.14.0/subcog-0.14.0-x86_64-pc-windows-msvc.zip

Installation Steps

# Download and extract (Unix)
curl -LO https://github.com/zircote/subcog/releases/latest/download/subcog-VERSION-TARGET.tar.gz
tar -xzf subcog-*.tar.gz
sudo mv subcog /usr/local/bin/
chmod +x /usr/local/bin/subcog

# Windows (PowerShell)
Invoke-WebRequest -Uri "https://github.com/zircote/subcog/releases/latest/download/subcog-VERSION-x86_64-pc-windows-msvc.zip" -OutFile subcog.zip
Expand-Archive subcog.zip -DestinationPath .
Move-Item subcog.exe $env:USERPROFILE\bin\

Verify Checksums

All releases include SHA256 checksums in checksums.txt:

# Download checksums
curl -LO https://github.com/zircote/subcog/releases/download/v0.14.0/checksums.txt

# Verify (Unix)
sha256sum -c checksums.txt --ignore-missing

# Verify (macOS)
shasum -a 256 -c checksums.txt --ignore-missing

npm / npx (Fallback)

The npm package is provided as a fallback for environments where binary installation is not possible. We recommend installing the native binary via Cargo, Homebrew, or direct download for best performance.

The npm package downloads pre-built binaries automatically for your platform.

One-time Execution

# Run without installing
npx @zircote/subcog --help
npx @zircote/subcog status
npx @zircote/subcog capture --namespace learnings "Important insight"

Global Installation

# Install globally
npm install -g @zircote/subcog

# Now use directly
subcog --help
subcog status

Project-local Installation

# Add to your project
npm install --save-dev @zircote/subcog

# Run via npx or package.json scripts
npx subcog status

Supported Platforms

Platform Architecture Status
macOS x64 (Intel) Supported
macOS arm64 (Apple Silicon) Supported
Linux x64 (glibc) Supported
Linux x64 (musl/Alpine) Supported
Linux arm64 Supported
Windows x64 Supported

Environment Variables

Variable Description
SUBCOG_BINARY_PATH Override binary location (for custom builds)
SUBCOG_SKIP_INSTALL Set to 1 to skip binary download (CI caching)

Fallback Behavior

If pre-built binaries are unavailable, the postinstall script will attempt:

  1. Download from GitHub Releases
  2. cargo install subcog (if Rust is installed)
  3. cargo install --git https://github.com/zircote/subcog.git (from source)

Building from Source

Prerequisites

  • Rust 1.88+ (Edition 2024)
  • Git 2.30+
  • C compiler (for native dependencies)

Build Steps

# Clone repository
git clone https://github.com/zircote/subcog.git
cd subcog

# Build release binary
cargo build --release

# Install to cargo bin directory
cargo install --path .

# Or copy binary manually
cp target/release/subcog /usr/local/bin/

Build Options

# With all features
cargo build --release --all-features

# Minimal build (no optional features)
cargo build --release --no-default-features

# Cross-compile for musl (static binary)
cargo build --release --target x86_64-unknown-linux-musl

Verification

After installation, verify subcog is working:

# Check version
subcog --version

# Check status
subcog status

# Run self-test
subcog capture --namespace testing "Installation test"
subcog recall "installation"

Troubleshooting

Binary Not Found

# Check if subcog is in PATH
which subcog

# If using cargo, check cargo bin
ls ~/.cargo/bin/subcog

# If using npm (fallback), check node_modules
ls node_modules/.bin/subcog

Permission Denied

# Make binary executable (Unix)
chmod +x /path/to/subcog

# Check file ownership
ls -la /path/to/subcog

Docker Permission Issues

# Run with current user
docker run --rm -u $(id -u):$(id -g) \
  -v ~/.local/share/subcog:/data \
  ghcr.io/zircote/subcog status

Architecture Mismatch

# Check your architecture
uname -m

# For Apple Silicon Macs running x86 binaries via Rosetta
arch -arm64 subcog --version

For more troubleshooting help, see TROUBLESHOOTING.md.