ussycode

module

v0.0.0-...-8883d6f Latest Latest Go to latest Published: Mar 22, 2026 License: MIT

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/mojomast/ussycode

Links

Open Source Insights

README ¶

ussycode

Self-hosted dev environment platform for the Ussyverse. Instant SSH-accessible microVMs with persistent disks, automatic HTTPS, and AI agent support.

ssh -p 2224 dev.ussyco.de -- get a dev environment in seconds. No signup. No credit card. SSH keys are identity.

What is this?

ussycode gives anyone instant dev environments via SSH. Under the hood it provisions Firecracker microVMs with persistent storage, automatic HTTPS via Caddy wildcard TLS, and a built-in metadata service. LLM access is provided through Routussy, a Discord-managed OpenAI-compatible proxy that handles access control and billing.

Product Vision

ussycode targets feature parity with exe.dev -- a self-hosted, Ussyverse-native version of the full product loop:

SSH in -> create a VM
Run your app inside the VM
Get an automatic HTTPS URL (vmname.dev.ussyco.de)
Share it (public link, email invite, or access-controlled)
Control access (public / private / invite-only)
Script it via API (POST /exec, tokens, BYOK LLM access)

Where exe.dev is a closed hosted product, ussycode is open-source and self-hostable while staying first-class within the Ussyverse (trust tiers, community arena, email gateway, agent support).

See PLAN-exe-dev-parity-roadmap.md for the full gap analysis and phased delivery plan.

Architecture

ssh dev.ussyco.de  -->  SSH Gateway  -->  VM Manager  -->  Firecracker microVM
                            |                                    |
                         SQLite DB                          metadata service
                            |                              (169.254.169.254)
                      Caddy Reverse Proxy  -->  vmname.dev.ussyco.de
                            |
                    Routussy (api.ussyco.de)
                      - SSH key validation
                      - LLM proxy + billing
                      - Discord access control

Single binary: SSH gateway, VM manager, Caddy proxy integration, metadata service, SQLite -- all in one Go binary.

Multi-node: Control plane coordinates agent nodes over gRPC/mTLS + WireGuard mesh. Agents run VMs on bare metal, VPS, or homelab hardware.

Tech Stack

Component	Technology
Language	Go
Database	SQLite (WAL mode, modernc.org/sqlite)
VMM	Firecracker microVMs
Reverse Proxy	Caddy v2 (admin API, wildcard certs)
SSH	gliderlabs/ssh
Networking	TAP devices, nftables, bridge networking
Base Image	Ubuntu 24.04 (Go + Python + Node pre-installed)
LLM Proxy	Routussy
PTY Handling	creack/pty/v2

Project Status

Area	Status
Core platform (SSH gateway, VM lifecycle, proxy, auth, metadata, API)	Done
LLM gateway (5 providers, BYOK, rate limiting)	Done
Email (inbound SMTP + outbound)	Done
Trust/quota system (4 tiers)	Done
Admin panel	Done
Custom domains	Done
Tutorial (10 lessons)	Done
Pi default AI experience	Done
Arena / community features	Done
Routussy integration (SSH auth, fingerprint billing, Discord onboarding)	Done
API wiring (`POST /exec`)	Needs fix (nil executor)
Browser auth flow	Needs fix (URL mismatch)
Multi-node cluster	Scaffolded, not integrated
Telemetry / observability	Not yet implemented

Development Roadmap

Full plan: PLAN-exe-dev-parity-roadmap.md

Phase	Goal
0 -- Stabilize	Fix API wiring, browser auth, failing tests, stale docs
1 -- Core UX loop	Verified boot -> run -> HTTPS URL end-to-end
2 -- Sharing & auth	Public/private/invite-only URL sharing, access control
3 -- API	`/exec` + token auth fully wired, scriptable from agents
4 -- Email	Inbound routing + outbound delivery integrated into product flows
5 -- Agents	AGENTS.md support, prompt-on-create, Shelley-compatible tooling
6 -- Teams	Multi-user orgs, SSO, per-org resource quotas
7 -- Cluster	Multi-node agent pool fully integrated and schedulable

Routussy Integration

Ussycode delegates access control and LLM billing to Routussy, a Discord bot and OpenAI-compatible proxy hosted at api.ussyco.de.

How It Fits Together

Onboarding: Users request ussycode access via Discord (/ussycode-request) with their SSH public key. Admins approve or deny.
SSH Authentication: When a non-Tailscale user connects, the SSH gateway calls Routussy's /ussycode/authorized-keys endpoint to check if their SSH fingerprint is approved.
LLM Access: VMs get automatic LLM access without users copying API keys. The metadata service injects OPENCODE_API_KEY=ussycode-fp:SHA256:<fingerprint> into each VM. When OpenCode or pi makes requests, Routussy resolves the fingerprint back to the user and charges their budget.

Auth Flow

User connects via SSH
  -> Gateway extracts SSH fingerprint
  -> Non-Tailscale IPs: GET api.ussyco.de/ussycode/authorized-keys
     (checks fingerprint against approved keys)
  -> User enters VM
  -> VM env has OPENCODE_API_KEY=ussycode-fp:SHA256:<fingerprint>
  -> AI tools send LLM requests to api.ussyco.de/v1
  -> Routussy resolves fingerprint -> user -> budget -> proxies to upstream

Configuration

Set these in /etc/ussycode-dev/ussycode.env (or via CLI flags):

USSYCODE_ROUTUSSY_URL=https://api.ussyco.de
USSYCODE_ROUTUSSY_INTERNAL_KEY=<shared-secret>

The shared secret must match USSYCODE_INTERNAL_KEY in Routussy's .env.

SSH Gateway

The SSH gateway (internal/ssh/) provides:

Interactive REPL: Create, start, stop, rename, and delete VMs
Direct VM access: ssh vmname@dev.ussyco.de -p 2224 proxies into the VM with proper PTY handling (dimensions, SIGWINCH forwarding via creack/pty/v2)
Hardened auth: Non-Tailscale connections (outside 100.64.0.0/10) require an SSH fingerprint registered through Routussy
Tailscale passthrough: Connections from the Tailscale range are trusted without Routussy validation

Web Apps Inside VMs

ussycode automatically proxies each VM's port 8080 to its public subdomain via Caddy.

Bind app servers to 0.0.0.0, not 127.0.0.1
Prefer port 8080 (Caddy proxies this port automatically)
Public URL: https://<vm-name>.dev.ussyco.de

Example:

python3 -m http.server 8080 --bind 0.0.0.0
# -> accessible at https://mild-owl.dev.ussyco.de

VMs have USSYCODE_VM_NAME and USSYCODE_PUBLIC_DOMAIN env vars so AI tools can construct the correct public URL automatically.

AI Assistance In VMs

The ussyuntu VM image includes pi (default) and OpenCode (optional) as AI coding assistants.

pi (Default -- auto-launches on SSH)

pi launches automatically when users SSH into a VM. It's configured with:

@ussyverse/pi-ussycode package for ussycode-specific tools, skills, and theme
ussyrouter provider for LLM access with budget enforcement
Fingerprint-based authentication (no raw API keys exposed)
First-run onboarding for new users
/publish command for quick web app exposure

Users can exit pi anytime for a normal shell, and restart it with pi.

OpenCode (Optional)

OpenCode is installed and manually runnable via opencode. Pre-configured with:

~/.config/opencode/opencode.json -- provider config pointing at Routussy for GLM models
~/.config/opencode/instructions/ussycode-runtime.md -- runtime instructions
~/.config/opencode/skills/ussycode-web-proxy/SKILL.md -- skill that teaches OpenCode to bind to 0.0.0.0:8080 and report the correct *.dev.ussyco.de public URL

Uses the same Routussy proxy and budget as pi. Does not auto-launch.

VM Networking

Bridge ussy0 at 10.0.0.1/24
VMs get IPs from 10.0.0.x
NAT masquerade via nftables inet ussycode table
Metadata service at 169.254.169.254:80 (DNAT from VM traffic on port 80 to :8083)
Metadata injects SSH keys, hostname, and env vars (including LLM credentials) into VMs at boot

Repository Structure

cmd/ussycode/          Main server entry point
cmd/ussyverse-agent/   Multi-node agent binary
internal/
  admin/               Operator/admin web panel
  api/                 HTTPS /exec API
  auth/                SSH-signed token primitives
  config/              Configuration loading and validation
  db/                  SQLite models, queries, embedded migrations
  gateway/             Metadata + LLM/email gateway services
  proxy/               Caddy auth/proxy integration
  ssh/                 SSH gateway, REPL shell, shared command executor
  vm/                  Firecracker VM manager, images, networking
images/ussyuntu/       Base VM image (Dockerfile + init script)
deploy/                Deployment assets
spec.md                Full product specification
PLAN-exe-dev-parity-roadmap.md  exe.dev parity gap analysis and roadmap

Development

Prerequisites

Go 1.22+
Linux with KVM support (/dev/kvm)
Firecracker binary
Root access (for VM networking and TAP devices)

Build

go build -o ussycode-dev ./cmd/ussycode

Test

go test ./...

Run

sudo ./ussycode-dev \
  --addr :2224 \
  --domain dev.ussyco.de \
  --admin-addr :9091 \
  --data-dir /var/lib/ussycode-dev \
  --routussy-url https://api.ussyco.de

Deploy as systemd service

sudo cp ussycode-dev /usr/local/bin/
sudo systemctl restart ussycode-dev

Rebuild VM base image

docker build --network host -t ussyuntu:latest images/ussyuntu/
# Go code auto-extracts to ext4 on next VM creation

Infrastructure (Current Deployment)

Service	Port	Description
SSH gateway	2224	ussycode SSH entry point
Caddy	8085	VM web subdomain proxy
Metadata	8083	VM metadata service (169.254.169.254 via DNAT)
Routussy	3000	LLM proxy + Discord bot (separate project)
nginx	80/443	TLS termination, reverse proxy to all services

DNS: *.dev.ussyco.de and *.ussyco.de both resolve to 104.218.100.104. Wildcard SSL via Let's Encrypt DNS-01 challenge.

Credits

Created by Kyle Durepos (@mojomast) and shuv (@shuv1337).

Part of The Ussyverse -- an ever-expanding open-source ecosystem.

License

MIT

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
cmd
ussycode command
ussyverse-agent command Package main implements the ussyverse-agent CLI, the node agent that joins and participates in the ussyverse server pool.	Package main implements the ussyverse-agent CLI, the node agent that joins and participates in the ussyverse server pool.
internal
admin Package admin implements the ussycode admin web panel.	Package admin implements the ussycode admin web panel.
agent Package agent implements the ussyverse node agent that registers with the control plane, sends heartbeats, and executes commands.	Package agent implements the ussyverse node agent that registers with the control plane, sends heartbeats, and executes commands.
api Package api implements the ussycode HTTPS API endpoints.	Package api implements the ussycode HTTPS API endpoints.
auth Package auth provides HTTP middleware for token-based authentication.	Package auth provides HTTP middleware for token-based authentication.
config
controlplane Package controlplane implements the server-side logic for managing nodes in the ussyverse server pool.	Package controlplane implements the server-side logic for managing nodes in the ussyverse server pool.
db Package db provides SQLite database access with WAL mode, split reader/writer connection pools, and embedded migrations.	Package db provides SQLite database access with WAL mode, split reader/writer connection pools, and embedded migrations.
gateway Package gateway implements the metadata service and gateway proxies available inside VMs at http://169.254.169.254/.	Package gateway implements the metadata service and gateway proxies available inside VMs at http://169.254.169.254/.
mesh Package mesh provides WireGuard mesh networking for the ussyverse server pool.	Package mesh provides WireGuard mesh networking for the ussyverse server pool.
pki Package pki provides Ed25519-based certificate authority functionality for the ussyverse server pool.	Package pki provides Ed25519-based certificate authority functionality for the ussyverse server pool.
proto/nodev1 Package nodev1 contains hand-written Go types mirroring the protobuf definitions in proto/node/v1/node.proto.	Package nodev1 contains hand-written Go types mirroring the protobuf definitions in proto/node/v1/node.proto.
proxy Package proxy implements a reverse proxy manager that integrates with Caddy to provide automatic TLS and per-VM subdomain routing.	Package proxy implements a reverse proxy manager that integrates with Caddy to provide automatic TLS and per-VM subdomain routing.
scheduler Package scheduler implements a two-phase VM placement scheduler for the ussyverse server pool.	Package scheduler implements a two-phase VM placement scheduler for the ussyverse server pool.
ssh Package ssh implements the ussycode SSH gateway server.	Package ssh implements the ussycode SSH gateway server.
storage Package storage defines the StorageBackend interface and provides a ZFS-based implementation for managing VM disk storage.	Package storage defines the StorageBackend interface and provides a ZFS-based implementation for managing VM disk storage.
telemetry
vm Package vm implements microVM lifecycle management, OCI image pulling, rootfs creation, and Firecracker integration for ussycode.	Package vm implements microVM lifecycle management, OCI image pulling, rootfs creation, and Firecracker integration for ussycode.