Deployment Guide

Coder Workspace Deployment (Primary)

SPT uses Coder on an Azure VM with Docker provisioning to deliver cloud development workspaces with 600+ AI agents, SPT Orchestrator, and the full agentic toolchain.

Architecture

GitHub Actions → smartpoints.azurecr.io/coder-base:latest
                           ↓ (pull)
Azure VM (D4s v3) → Docker Engine → Workspace Container
                  → Coder Server (coder.smartpoints.tech)
                           ↓
                  SPT Orchestrator + Beads + GitNexus + spt crates

Prerequisites

• Coder server running at https://coder.smartpoints.tech
• Azure Container Registry at smartpoints.azurecr.io
• Azure VM with Docker installed
• VM authenticated to pull from ACR

Step 1: Configure ACR Authentication on the VM

# Option A: Managed Identity (recommended)
az vm identity assign --resource-group <rg> --name <vm-name>
az role assignment create \
  --assignee-object-id $(az vm show --resource-group <rg> --name <vm> --query identity.principalId -o tsv) \
  --role AcrPull \
  --scope $(az acr show --name smartpoints --query id -o tsv)
az acr login --name smartpoints

# Option B: Admin credentials (quick setup)
az acr update --name smartpoints --admin-enabled true
az acr credential show --name smartpoints
docker login smartpoints.azurecr.io -u smartpoints -p <password>

Step 2: Configure GitHub Secrets for CI

Add these secrets to the GitHub repository settings:

Secret	Value
ACR_USERNAME	Service principal app ID or admin username
ACR_PASSWORD	Service principal secret or admin password

The GitHub Actions workflow at .github/workflows/build-image.yaml will push to both smartpoints.azurecr.io (primary) and ghcr.io (mirror) on pushes to main.

Step 3: Build and Push the Docker Image

# Trigger manually via GitHub Actions
gh workflow run "Build and Push Coder Base Image"

# Or push a change to infra/images/coder-base/ to trigger automatically

Verify the image is available:

# On the Azure VM
docker pull smartpoints.azurecr.io/coder-base:latest

Step 4: Push the Terraform Template to Coder

# On the Azure VM (or any machine with coder CLI)
cd infra/terraform/coder-template

# Login to Coder
coder login https://coder.smartpoints.tech

# Push template
coder templates push sptx-workspace \
  --directory . \
  --yes

Step 5: Create a Workspace

# Using spt CLI (recommended)
spt init
# Enter URL: https://coder.smartpoints.tech
# Enter token: <your-session-token>

spt up my-workspace

# Or using Coder CLI directly
coder create my-workspace --template sptx-workspace

# Or via the web UI
# Visit https://coder.smartpoints.tech and click "Create Workspace"

Step 6: Validate the Workspace (SPT Orchestrator)

Once the workspace is running, verify:

# SSH into workspace
coder ssh my-workspace

# Check core tools are installed
claude --version            # Claude Code
sptx --version  # SPT Orchestrator
go version                  # Go 1.24+
node --version              # Node.js 20+
rustc --version             # Rust

# Check SPT MCP registration
claude mcp list | grep spt

# Check Beads memory
bd --version

# Check GitNexus
npx gitnexus --version

# Check agents
ls ~/spt/agents/ | wc -l    # Should show 600+

# Check plugins (should be 6)
sptx plugins list | wc -l

Step 7: Verify 3-Tier Memory

# Initialize Beads in workspace
bd init

# Test memory operations
bd-ready              # Should show "Beads ready"
bd-add "Test entry"   # Store test entry
bd-list               # Should show test entry

# Test SptDB
mem-stats             # Should show memory statistics

Step 8: Verify GitNexus

# Index the workspace repository
gnx-analyze

# Test blast-radius detection
gnx-blast README.md

# Test dependency lookup
gnx-deps CLAUDE.md

Workspace Variables

When creating a workspace, you can customize:

Variable	Default	Description
docker_image	smartpoints.azurecr.io/coder-base:latest	Container image with SPT Orchestrator
repo_url	(empty)	Repository to clone
dotfiles_url	(empty)	Dotfiles repo for personalization
enable_nested_virt	false	Enable Docker-in-Docker
arch	amd64	CPU architecture

Resource Considerations

The Azure VM (D4s v3: 4 vCPU, 16 GiB) supports 1-2 concurrent workspaces comfortably. Each workspace with active Claude Code sessions and SPT uses approximately 6-8 GiB RAM.

To scale up:

• D8s v3 (8 vCPU, 32 GiB) for 3-4 concurrent workspaces
• D16s v3 (16 vCPU, 64 GiB) for 5-8 concurrent workspaces

---

DevPod Deployment (Alternative)

The DevPod-based deployment remains functional for local and multi-cloud environments.

Supported Providers

Provider	Configuration Command	Key Options
DigitalOcean	devpod provider add digitalocean	DROPLET_SIZE, DIGITALOCEAN_ACCESS_TOKEN
AWS	devpod provider add aws	AWS_INSTANCE_TYPE, AWS_REGION
Azure	devpod provider add azure	AZURE_VM_SIZE, AZURE_LOCATION
Google Cloud	devpod provider add gcp	GOOGLE_PROJECT_ID, GOOGLE_MACHINE_TYPE
Local Docker	devpod provider add docker	No additional config

DevPod Deployment Process

1. Configure Provider: devpod provider use [provider_name]
2. Deploy Workspace: devpod up https://github.com/smartpointstech/spt --ide vscode
3. Stop/Resume: devpod stop spt / devpod up spt

DevPod Setup Script

The setup script at scripts/bootstrap/setup.sh installs:

1. System prerequisites (build-essential, python3, git, curl, jq)
2. Node.js 20+
3. Claude Code + SPT Orchestrator (single init command)
4. SPT MCP registration
5. 6 SPT plugins
6. UI UX Pro Max skill
7. GitNexus (codebase knowledge graph)
8. Beads (cross-session memory)
9. Agent Teams enablement
10. Statusline Pro v4.0

---

CI/CD Pipeline

Docker Image Build

The GitHub Actions workflow at .github/workflows/build-image.yaml:

• Triggers: Push to infra/images/coder-base/** on main, or manual dispatch
• Builds: Multi-stage Docker image with Go, Node, Rust, Python, code-server, SPT Orchestrator
• Pushes to: smartpoints.azurecr.io/coder-base (primary) + ghcr.io (mirror)
• Smoke tests: On PRs, builds and runs version checks

Post-Setup Verification

The scripts/bootstrap/verify.sh script runs 13 verification checks:

1. Claude Code installed
2. SPT Orchestrator initialized
3. SPT MCP registered
4. 6 plugins installed
5. Beads CLI available
6. GitNexus available
7. Agent Teams enabled
8. Workspace directories created
9. CLAUDE.md present
10. Agents directory populated
11. Aliases configured
12. Go CLI builds
13. Memory systems operational

Required GitHub Secrets

Secret	Purpose
ACR_USERNAME	Azure Container Registry login
ACR_PASSWORD	Azure Container Registry password
GITHUB_TOKEN	Auto-provided for ghcr.io mirror

---

AKS Deployment (Kubernetes)

For larger deployments, use the Kubernetes Coder template.

Prerequisites

• AKS cluster with sufficient resources
• kubectl configured for the cluster
• Coder deployed to AKS

Deploy to AKS

cd infra/terraform/coder-template-k8s

# Push template to Coder
coder templates push sptx-k8s \
  --directory . \
  --yes

AKS-Specific Variables

Variable	Default	Description
kubernetes_namespace	coder-workspaces	Target namespace
resource_limit_cpu	4	CPU limit per workspace
resource_limit_memory	8Gi	Memory limit per workspace
storage_class	managed-premium	Azure storage class

---

Troubleshooting

SPT Not Initializing

# Check Node.js version (must be 20+)
node --version

# Manually initialize SPT
sptx init --wizard

# If wizard fails, use non-interactive
sptx init

# Run doctor to auto-fix issues
sptx doctor --fix

Beads Not Working

# Ensure workspace is a git repository
git status

# Initialize Beads
bd init

# Check Beads directory exists
ls -la .beads/

GitNexus Indexing Failed

# Large repos may need more time
# Run with verbose output
npx gitnexus analyze --verbose

# For very large repos, increase timeout
GITNEXUS_TIMEOUT=120 npx gitnexus analyze

Plugin Installation Failed

# Check plugin directory
ls -la .spt/plugins/

# Reinstall specific plugin
sptx plugins install -n "@smartpointstech/plugin-agentic-qe"

# Alternative flag syntax
sptx plugins install --name "@smartpointstech/plugin-agentic-qe"

Memory System Issues

# Check SptDB status
mem-stats

# Reset memory if corrupted
sptx memory reset

# Verify Beads
bd-list