Phelix
A single-binary CLI for building, running, versioning, and zero-downtime
deploying Go and Rust applications on a host, with encrypted environment
variables, health checks, Docker workflows, and optional multi-server monitoring
through a dashboard at phelix.anophel.com.
Phelix is written in Go and built with Cobra. It targets Linux, with experimental Windows support.
Why Phelix
Shipping a change to a small fleet usually means stitching together a build step, a process manager, a reverse proxy, a rollback plan, and some way to watch it all. Phelix folds that into one binary you run on the host: it compiles your app, records every build as a numbered version, and cuts traffic over to the new version only after it passes a health check, so a broken deploy never takes down the running one. When something is wrong, you roll back to any retained version.
It is offline-first: build, run, deploy, and roll back work with no account and no network. Logging in only adds dashboard sync: nothing leaves your machine until you opt in, per application.
Features
- Go & Rust application lifecycle: build, run, rebuild, start/stop/restart, status, logs.
- Versioned builds: every build is
v1,v2, … with optional--tag; binary + encrypted env are snapshotted together. - Zero-downtime deploys: blue-green and rolling via the
phelix proxy. - Canary & progressive rollouts: shift a traffic percentage, verify health and metrics against the stable baseline, auto-rollback on regression.
- Rollback: interactive picker or
--to, dry-run preview, verification window, automatic rollback on failed deploy, audited history. - Health checks: tiered deploy health gating (2xx / any-HTTP / TCP / PID).
- Docker: generate optimized multi-stage images (
dockerize), or run app instances as containers under the proxy. - Matrix builds: toolchain-version × platform cross-product, with resume, retries, per-artifact SHA-256, and release manifests.
- Build reports: automatic per-build metrics and regression alerts, offline.
- Encrypted env vars: AES-256-GCM at rest, injected at start, versioned.
- Per-instance resource limits: CPU/memory via cgroups v2 (Linux).
- Git webhook deploys: HMAC-authenticated push webhooks deploy the exact pushed commit through the normal rebuild pipeline.
- Monitoring: optional, per-app opt-in gRPC stream to the dashboard.
- Agent sessions: durable, auditable tracking of one unit of agent work across inspect → plan → apply → verify, so an interrupted agent can resume by reading state. Tracking only: it grants no authorization and executes nothing. See Agent Execution Sessions.
See the documentation index for details on any of these.
Quick Start
Install (detects OS/arch, no toolchain needed just to install):
curl -fsSL https://phelix.anophel.com/install.sh | bash
phelix version
Then, from a Go or Rust project directory:
# Initialize project config (creates phelix.yaml)
phelix init
# Build and run an app (auto-detects Go or Rust)
phelix build myapp --port 8080
# Rebuild after a change with zero downtime via blue-green
phelix rebuild myapp --blue-green
# Roll back to the previous versioned build
phelix rollback myapp
One requirement: managed apps must listen on the port given by the
PORTenvironment variable rather than hardcoding one: see The PORT Contract. Runphelix doctorto check.
Full walk-through: Quick Start.
Common Workflows
Deploy with zero downtime
phelix rebuild myapp --blue-green # or: --replicas 3 for rolling
Ship to a slice of traffic first
phelix rebuild myapp --canary 5 # 5% canary, verify, then promote
→ Canary & progressive rollouts
Roll back
phelix rollback myapp --to v7 --dry-run # preview, then run without --dry-run
→ Rollback
Build across toolchains and platforms
phelix build myapp --matrix --go-versions 1.26,1.27 --platforms linux/amd64,linux/arm64
Deploy on push
PHELIX_WEBHOOK_SECRET=… phelix webhook
Examples
Runnable, dependency-free starter projects under examples/:
- Simple Go application: the minimal
PORT-reading app. - Simple Rust application: the same, in Rust (stdlib only).
- Blue-green deployment: a zero-downtime deploy you can watch cut over.
- Docker runtime (Go): Phelix runs the app as a container.
- Docker runtime (Rust): the same, in Rust.
- Docker + compose backing services (Go): Phelix runs the app on a shared network; docker-compose owns Redis.
- Docker + compose backing services (Rust): the same, in Rust.
- Docker + compose profile (Go): app in compose for local dev, Phelix runs it on the server.
- Docker + compose profile (Rust): the same, in Rust.
- Docker image built from a compose service (Go):
deploy.docker.build: compose. - Docker image built from a compose service (Rust): the same, in Rust.
- Docker multiservice (Go): several app services, one shared backing tier.
- Docker multiservice (Rust): the same, in Rust.
Documentation
Getting Started
Guides
- Authentication
- Authorization
- MCP Adapter for Coding Agents
- Agent Execution Sessions
- Interactive Usage
- Zero-Downtime Deployments
- Canary & Progressive Rollouts
- Rollback
- Health Checks
- Environment Variables
- Build Reports
- Matrix Builds
- Docker Image Building
- Docker Runtime
- Monitoring
- Webhooks
- Resource Limits
- Security
- Troubleshooting
- Best Practices
Reference
- CLI Commands
- Configuration (
phelix.yaml) - Environment Variables
- Data Directory
- Error Codes
- Exit Codes
- Machine Contract (
--json)
Architecture
- Overview
- Deployment Engine
- State Management
- Build System
- Monitoring
- Identity
- Error Architecture
- Backend Contracts
Architecture
Phelix is a single Cobra binary: thin commands in cmd/ orchestrate domain
packages in internal/, and all runtime state lives on disk under ~/.phelix/.
your app → phelix CLI → build / deploy engine → runtime (host process or container)
│ │
▼ ▼
versioned state on disk phelix proxy (public port)
│
▼
optional gRPC monitoring → dashboard
Deploys are fail-safe by construction: a version is only promoted to current
after its health check passes, the proxy switches targets atomically, and a failed
candidate never touches the live instance. See the
architecture overview.
Security
Environment variables and registry credentials are encrypted at rest with
AES-256-GCM and never logged in plaintext; authentication is optional and
tokens are stored locally; the monitor gRPC channel uses TLS (only mode: dev
uses plaintext, for local backends); webhook secrets live only in environment
variables and signatures are verified constant-time; managed containers publish
only to 127.0.0.1. When you are not logged in, no app data, metrics, or events
leave your machine. See Security.
Support
- Documentation: phelix.anophel.com/docs
License
Phelix is source-available (not classic open source). The CLI in this
repository is licensed under the Functional Source License, Version 1.1, with
an Apache 2.0 future license (FSL-1.1-ALv2): see LICENSE. Each
released version converts to Apache 2.0 two years after its release.
You may use, study, modify, and redistribute the CLI for any purpose except a Competing Use (reselling it or offering a competing hosted/dashboard service). You are very welcome to fork it and contribute changes back.
- "Phelix" name & logo are trademarks of Mohammad Abdorrahmani: see
TRADEMARK.md. - Contributing (DCO + CLA): see
CONTRIBUTING.md. - Plain-language summary of what's allowed: see
docs/licensing.md.
The Phelix dashboard backend and frontend at phelix.anophel.com, including its
paid features, are proprietary and are not part of this repository.