Deprun

Agent-native self-hosted deployment platform.

Deploy and manage projects on your own VPS from your terminal, Claude Code, or Codex — without SSH.

What is Deprun?

Deprun is a self-hosted deployment control plane. You install it on a server, register your VPS once, then deploy projects using the CLI, MCP tools, or dashboard. The agent handles Docker builds, routing, SSL, and healthchecks automatically.

Why Deprun?

• No manual SSH — Deploy from local or AI agents via a structured API
• AI-first — Native MCP tools for Claude Code and Codex
• Self-hosted — Your server, your data, no vendor lock-in
• Multi-stack — Next.js, Vite, Node, Docker, Docker Compose
• Secure by design — Encrypted secrets, JWT auth, token scoping
• GitHub ready — Webhook-triggered deployments

Current Maturity

Alpha (0.3.0-alpha) — Core deployment loop implemented and verified. The following are verified working:

• User auth (JWT + bcrypt)
• Rate limiting on auth endpoints
• CORS enforcement with explicit origins
• Webhook signature verification (HMAC-SHA256)
• Project CRUD + stack detection
• Server/agent registration + heartbeat
• Agent Docker execution loop (build → run → healthcheck → activate)
• CLI deploy/logs/rollback (fully implemented)
• Dashboard login (JWT wired to API)
• MCP server (22 tools implemented)
• Docker Compose deployment
• Rollback via release activation
• Traefik dynamic config generation

Not yet production-ready:

• Fresh VPS install never tested on clean Ubuntu
• Real deployment never executed end-to-end
• MCP not tested with real Claude Code
• Backup/restore never executed
• Observability stack not deployed

See report_final/ for full honest status.

Architecture

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│  Developer  │     │ Claude Code │     │   GitHub    │
│    CLI      │     │    MCP      │     │  Webhooks   │
└──────┬──────┘     └──────┬──────┘     └──────┬──────┘
       │                   │                   │
       └───────────────────┼───────────────────┘
                           ▼
               ┌───────────────────────┐
               │    Go Fiber API       │
               │   Control Plane       │
               └───────────┬───────────┘
                           │
         ┌─────────────────┼─────────────────┐
         ▼                 ▼                 ▼
┌─────────────┐   ┌─────────────┐   ┌─────────────┐
│ PostgreSQL  │   │    Redis    │   │    Agent   │
│  (storage)  │   │  (tokens)   │   │  (executes) │
└─────────────┘   └─────────────┘   └──────┬──────┘
                                          │
                              ┌──────────┴──────────┐
                              ▼                     ▼
                       ┌───────────┐        ┌───────────┐
                       │  Docker   │        │  Traefik  │
                       │  Engine   │        │  (proxy)  │
                       └───────────┘        └───────────┘

Quick Start

1. Install on your server

curl -sSL https://get.deprun.dev | bash

2. Install CLI locally

curl -sSL https://get.deprun.dev/cli | sh

3. Authenticate

deprun auth login

4. Deploy a project

cd my-nextjs-app
deprun deploy

CLI Example

# Login
deprun auth login --email admin@example.com --password mypassword

# List projects
deprun project list

# Deploy
deprun deploy myapp --stack nextjs

# View logs
deprun logs myapp --follow

# Rollback
deprun rollback myapp --to v1.2.3

# Domain management
deprun domain add myapp --domain myapp.example.com --ssl

MCP Example

You: "Deploy my Vite app to production"
Claude Code → MCP tools:
  - deploy(project="vite-app", branch="main", confirm=true)
  - check_deployment_status(deploymentId="dep_xxx")
  - get_logs(project="vite-app", tail=50)

Full MCP tool reference in docs/MCP_REFERENCE.md.

Supported Stacks

Stack	Auto-detected	Dockerfile	docker-compose
Next.js	✅	—	✅
Vite	✅	—	✅
Static HTML	✅	✅	✅
Node.js	✅	✅	✅
Dockerfile	—	✅	✅
Docker Compose	—	—	✅

Roadmap

Phase	Goal	Status
Phase 1-4	Core foundation	✅ Complete
Phase 5	Production hardening	🔜 In progress
Phase 6	Deprun Cloud (paid tier)	Planned

Phase 5 priorities

1. Rate limiting on auth endpoints
2. CORS + webhook signature verification
3. Agent Docker execution
4. Dashboard API wiring
5. Test execution

Security Model

• Passwords — bcrypt hashed (12 rounds)
• Tokens — JWT (15min access) + refresh token rotation
• Agent auth — Per-agent token with heartbeat
• API tokens — SHA256 hashed, scoped per-resource
• Secrets — AES-256-GCM encrypted at rest
• Secret masking — Values redacted in all logs
• Command allowlist — Agent only runs pre-approved Docker commands
• Docker isolation — No privileged mode, read-only root where possible

Full security documentation in docs/.

Files

.
├── apps/
│   ├── api/          # Go Fiber REST API
│   ├── agent/        # Go deployment agent
│   ├── cli/         # Go CLI (Cobra)
│   ├── dashboard/   # React dashboard
│   └── mcp-server/   # NestJS MCP server
├── packages/
│   └── sdk/          # TypeScript SDK
├── architect/         # Architecture decision records
├── docs/             # User documentation
├── docs/diagrams/    # Mermaid architecture diagrams
├── infra/            # Infrastructure as code
├── report_final/     # Phase 4 honest status reports
└── templates/        # Project templates

License

MIT