✨ Features
- Zero-collision codes — atomic SQLite counter + Sqids: non-sequential, bijective, no retry loops
- Custom aliases — bring your own slug (
/my-link); charset isolation prevents collision with generated codes - URL expiration — configurable TTL with lazy expiry on read + hourly background cleanup; update expiry via
PATCH - Batch creation —
POST /api/v1/urls/batchaccepts up to 100 URLs; per-item success/failure - QR codes —
GET /api/v1/urls/{code}/qr?format=png|jpeg|svgreturns a QR code for any short link in three formats - Link previews —
titleanddescriptionauto-fetched on create (fail-open, private-IP blocked) - Spam detection — optional Google Safe Browsing v4 integration; unsafe URLs rejected with 422 (fail-open)
- Switchable cache —
none | memory | redisat config time; cache-aside with TTL capped to remaining expiry - API key auth — constant-time comparison; per-IP token bucket rate limiting
- CLI client —
goshort-clifor shorten, list, stats, delete from the terminal - Public shorten endpoint —
POST /api/v1/urls/public: no auth, 5 req/min rate limit, 30-day expiry; powers the landing page widget - Landing page — goshort.ngockhoi96.dev: Astro static site on Cloudflare Workers with live shorten widget
- MCP server — AI agents (Claude Code, Cursor) can shorten, list, and manage URLs via Model Context Protocol
- Prometheus metrics + structured logs —
/metricsendpoint,slogthroughout, no extra dependencies - Self-documenting API — OpenAPI 3.1 spec + interactive Scalar UI at
/docs
🏗️ Architecture

Full architecture diagrams: high-level, request flow, layer boundaries.
🛠️ Tech Stack
🚀 Quick Start
a. Docker Compose (recommended)
curl -O https://raw.githubusercontent.com/anIcedAntFA/goshort/main/docker-compose.yml
curl -O https://raw.githubusercontent.com/anIcedAntFA/goshort/main/goshort.toml
docker compose up -d
Caddy handles TLS automatically. Edit goshort.toml to set your base_url and api_key.
b. Binary (GitHub Releases)
curl -L https://github.com/anIcedAntFA/goshort/releases/latest/download/goshort_linux_amd64.tar.gz | tar xz
./goshort
Grab goshort_darwin_arm64, goshort_windows_amd64, etc. from the releases page.
c. go install
go install github.com/anIcedAntFA/goshort/cmd/server@latest
goshort
📡 Usage
Create a short URL:
curl -s -X POST http://localhost:8080/api/v1/urls \
-H "Content-Type: application/json" \
-H "X-API-Key: your-api-key" \
-d '{"url": "https://example.com/very/long/path", "expires_in": "30d"}'
{
"short_code": "k7Xm2p",
"short_url": "http://localhost:8080/k7Xm2p",
"original_url": "https://example.com/very/long/path",
"expires_at": "2025-08-01T00:00:00Z"
}
Redirect:
curl -L http://localhost:8080/k7Xm2p
# → 302 to https://example.com/very/long/path
💻 CLI
# Install
go install github.com/anIcedAntFA/goshort/cmd/cli@latest
# Shorten a URL
goshort-cli shorten https://example.com/long --alias my-link --expires 7d
# List all URLs (paginated)
goshort-cli list --page 1 --per-page 20
# Inspect a short code or alias
goshort-cli stats k7Xm2p
# Delete a short URL
goshort-cli delete k7Xm2p
Config file (~/.goshort.toml):
server_url = "http://localhost:8080"
api_key = "your-api-key"
Per-command overrides (precedence: flag > env > config):
🤖 MCP (AI Agent Integration)
GoShort ships an MCP server so AI agents like Claude Code and Cursor can shorten, list, and manage URLs directly.
Local — stdio
make build
Create .mcp.json in your project root:
{
"mcpServers": {
"goshort": {
"command": "./bin/goshort",
"args": ["--mcp"],
"env": { "GOSHORT_STORAGE_SQLITE_PATH": "./data/goshort.db" }
}
}
}
Remote — Streamable HTTP
The /mcp endpoint is served on the main port alongside the REST API. No separate server needed.
# Connect Claude Code to deployed instance
claude mcp add goshort-remote \
--transport http \
https://goshort.app/mcp \
--header "X-API-Key: your-api-key"
Tools
Resources
Prompts
⚙️ Configuration
[server]
port = 8080
base_url = "https://short.yourdomain.com"
[auth]
api_key = "your-secret-key" # empty = no auth
[cache]
driver = "none" # none | memory | redis
[shortener]
default_expiry = "0" # "0" = no expiry; or "7d", "30d", "365d"
Every key maps to GOSHORT_<SECTION>_<KEY> env var — e.g., GOSHORT_AUTH_API_KEY=secret. Full reference: goshort.toml.
📋 API
Auth: X-API-Key: <key> header. Redirect codes: 302 Found, 404 Not Found, 410 Gone (expired).
POST /api/v1/urls body:
Interactive docs at goshort.app/docs. Landing page at goshort.ngockhoi96.dev.
📁 Project Structure
See docs/DESIGN.md for the full architecture, layer boundaries, and design rationale.
🧑💻 Development
git clone https://github.com/anIcedAntFA/goshort
cd goshort
lefthook install # install git hooks (once after clone)
make help # list all targets
Run make help for the full list of targets. See CONTRIBUTING.md for the full development workflow including Redis integration tests and git hooks.
🚢 Deployment
See docs/DEPLOYMENT.md for comprehensive guides.
Docker Compose — GoShort + Caddy (auto-TLS):
docker compose up -d
Fly.io — API + redirects + MCP at goshort.app:
fly launch && fly deploy
Landing page — goshort.ngockhoi96.dev (Cloudflare Workers, static Astro build):
make website/build && cd website && wrangler deploy
Bare VPS — Nginx + systemd + Certbot (see DEPLOYMENT.md)
🗺️ Roadmap
Each phase ships a working, deployable product.
⭐ Star History
📄 License
MIT — see LICENSE.