vortex

module

v0.3.0 Latest Latest Go to latest Published: Jun 11, 2026 License: Apache-2.0

Details

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

Repository

github.com/vortex-run/vortex

Links

Open Source Insights

README ¶

VORTEX

One binary. Any server. Fully autonomous.

VORTEX is a self-hosted autonomous infrastructure platform: a single static Go binary that owns your edge (reverse proxy, TLS, QUIC), your security (mTLS, RBAC, OPA policy, tamper-proof audit), your observability (Prometheus, OTel), and an AI agent runtime that can read, write, and run things on your machine, build apps, run research, and manage your servers — all controlled from a terminal dashboard, a browser, or Telegram on your phone.

$ curl -fsSL https://vortex.run/install | sh
$ vortex setup        # pick an AI provider, optional Telegram
$ vortex start        # edge + security + agent runtime, one process

Screenshot / demo gif placeholder — docs/ has full walkthroughs.

What is VORTEX?

VORTEX collapses the stack you normally assemble from a reverse proxy, a secrets manager, a cert manager, an observability stack, and a pile of glue scripts into one binary with no external dependencies. It runs your internet-facing edge and an AI agent that operates the box for you — both in the same process, both configured from one vortex.cue file.

It is self-hosted and single-tenant by design: you run it on your own VPS, it stores its own state, and nothing phones home.

Features


🤖 AI Agent	Claude, DeepSeek, OpenAI, Gemini, Groq, AWS Bedrock, Azure OpenAI, OpenRouter, Ollama
🌐 Reverse Proxy	HTTP/HTTPS/TCP/UDP/QUIC with load balancing and health checks
🔒 Zero Trust	mTLS identity mesh, RBAC, OPA policy engine, edge rate limiting
📱 Telegram Control	Drive the agent and get alerts from your phone
🏗️ Autonomous Builds	VORTEX Forge builds apps + Android APKs from a prompt
🔍 Research Agent	Web search + summarize into reports (SSRF-hardened)
🖥️ DevOps Agent	SSH, Docker, Nginx management over your fleet
📊 Data Pipelines	CSV/JSON analysis + chart generation
🏥 Self-Healing	Auto-detect failures and recover, with SLO tracking
🤝 Multi-Agent	Orchestrate complex tasks across specialised agents
📟 Terminal UI	Full dashboard in your terminal (optional vim keybindings)
🌐 Web Dashboard	Browser-based management at `/dashboard/`
🔐 Encrypted Secrets	XChaCha20-Poly1305 at rest, keyed by a random master key
📋 Tamper-Proof Audit	HMAC hash-chained, compliance-report exportable
📦 Signed Releases	Ed25519-signed checksums, verified before self-update

Quick Start (30 seconds)

curl -fsSL https://vortex.run/install | sh
vortex setup
vortex start

Then open the dashboard at http://localhost:9090/dashboard/ or the terminal UI with vortex ui.

Compared to Claude Code

VORTEX does everything an AI coding agent does and operates the server it runs on:

	Claude Code	VORTEX
AI coding agent	✅	✅
Multiple AI providers	—	✅ (9 providers)
Conversation persistence	✅	✅ (SQLite + full-text search)
LSP code intelligence	✅	✅
Reverse proxy / TLS	—	✅
Secrets manager	—	✅ (encrypted at rest)
mTLS / RBAC / policy	—	✅
Telegram / phone control	—	✅
Autonomous app builds	—	✅ (Forge)
Self-healing infra	—	✅
Multi-agent orchestration	—	✅
Audit log (tamper-proof)	—	✅
Single self-hosted binary	—	✅

Installation

See docs/install.md for the full guide. In short:

Linux / macOS:

curl -fsSL https://vortex.run/install | sh

Windows: download vortex_windows_amd64.zip from the Releases page, extract vortex.exe, and run vortex service install.

Verify a release before trusting it:

vortex verify            # checks this binary against the signed release
./scripts/verify-release.sh v0.2.0

Configuration (`vortex.cue`)

VORTEX is configured by a single CUE file. A minimal working example:

cluster: { name: "my-cluster" }
tls: { provider: "internal", acme_email: "you@example.com" }
routes: [
  { name: "web", protocol: "https", listen: 443,
    backends: [{ host: "127.0.0.1", port: 8080 }] },
]
secrets: { keys: ["db_password"] }
observability: { log_level: "info" }

All options are documented in docs/configuration.md. Validate without starting:

vortex check --config vortex.cue

Agent Commands

Talk to the coordinator from the TUI, the web dashboard, Telegram, or the API. Examples:

"Build me a Flutter todo app and send me the APK."
"Research the top 3 Go HTTP routers and summarise the trade-offs."
"SSH into web-1 and restart nginx, then confirm it's healthy."
"Analyse sales.csv and chart revenue by month."
"Set up a TCP route for postgres on :5432 with mTLS."

Capabilities and examples: docs/agents.md.

Telegram Setup

Create a bot with @BotFather and copy the token.
Run vortex setup and choose to configure Telegram, or set VORTEX_TELEGRAM_TOKEN and VORTEX_TELEGRAM_DEFAULT_CHAT.
Message your bot; it drives the agent and forwards alerts.

Full steps: docs/telegram.md.

API Reference

The management API listens on :9090. Key endpoints:

Method	Path	Purpose
GET	`/health`	Liveness + config hash
GET	`/ready`	Readiness (aggregates subsystem health)
GET	`/metrics`	Prometheus metrics
GET	`/api/status`	Extended status
POST	`/api/agents/submit`	Send a message to the agent
GET	`/api/agents/history`	List conversation sessions
POST	`/api/keys`	Issue an API key (admin)
GET	`/api/audit`	Audit log entries

Full reference: docs/api.md.

Architecture

                ┌──────────────────────────────────────────────┐
   Internet ───▶│ Edge: rate limit · IP block · TLS/mTLS · QUIC │
                └───────────────┬──────────────────────────────┘
                                │
              ┌─────────────────┼─────────────────┐
              ▼                 ▼                 ▼
        ┌──────────┐     ┌────────────┐    ┌──────────────┐
        │  Proxy   │     │  Policy    │    │ Management   │
        │ (HTTP/   │     │  (OPA) +   │    │ API + TUI +  │
        │  TCP/UDP)│     │  RBAC      │    │ Dashboard    │
        └──────────┘     └────────────┘    └──────┬───────┘
                                                  │
                          ┌───────────────────────┼──────────────────┐
                          ▼                        ▼                  ▼
                   ┌─────────────┐         ┌──────────────┐   ┌─────────────┐
                   │ Agent       │         │ Secrets +    │   │ Audit (HMAC │
                   │ runtime +   │         │ keyring      │   │ chain)      │
                   │ tools (LSP, │         │ (master key) │   └─────────────┘
                   │ FS, http)   │         └──────────────┘
                   └─────────────┘

The security model — keys, mTLS, the audit chain, the agent sandbox — is explained in docs/security.md.

Building from Source

git clone https://github.com/vortex-run/vortex
cd vortex
task build      # produces ./bin/vortex
task test       # unit tests
task lint       # golangci-lint

Go 1.26+ and Task are required. Details in docs/development.md.

Contributing

Issues and PRs are welcome. CI runs build, race-enabled tests, lint, and the integration suite on every push and PR. Please run task test and task lint before opening a PR, and keep the stdlib-first, single-binary ethos. See docs/development.md.

License

Directories ¶

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

Path	Synopsis
cmd
vortex command
config Package schema exposes VORTEX's embedded master configuration schema.	Package schema exposes VORTEX's embedded master configuration schema.
internal
agents Package agents implements the VORTEX agent runtime (build plan M10): a supervised, message-passing system of autonomous sub-agents coordinated by a single user-facing coordinator.	Package agents implements the VORTEX agent runtime (build plan M10): a supervised, message-passing system of autonomous sub-agents coordinated by a single user-facing coordinator.
api Package api hosts VORTEX's management HTTP server.	Package api hosts VORTEX's management HTTP server.
audit Package audit implements VORTEX's tamper-proof audit log (build plan M3.6): an append-only, HMAC-SHA256 hash-chained record of security-relevant events.	Package audit implements VORTEX's tamper-proof audit log (build plan M3.6): an append-only, HMAC-SHA256 hash-chained record of security-relevant events.
auth Package auth implements VORTEX's authentication and authorization (build plan M3.5): a role-based access-control model (org → team → user), API-key issuance and verification, OIDC/SSO login, and the HTTP middleware that ties them together to protect the management API.	Package auth implements VORTEX's authentication and authorization (build plan M3.5): a role-based access-control model (org → team → user), API-key issuance and verification, OIDC/SSO login, and the HTTP middleware that ties them together to protect the management API.
cluster Package cluster implements VORTEX's clustering and high-availability layer (build plan M4): node identity, SWIM gossip membership (hashicorp/memberlist), Raft consensus for config replication (hashicorp/raft), and a manager that orchestrates the two.	Package cluster implements VORTEX's clustering and high-availability layer (build plan M4): node identity, SWIM gossip membership (hashicorp/memberlist), Raft consensus for config replication (hashicorp/raft), and a manager that orchestrates the two.
cmd Package cmd implements the vortex command-line interface (build plan M1.3), built on spf13/cobra.	Package cmd implements the vortex command-line interface (build plan M1.3), built on spf13/cobra.
config Package config implements VORTEX's CUE-based configuration engine (build plan M1.2).	Package config implements VORTEX's CUE-based configuration engine (build plan M1.2).
dashboard Package dashboard serves the embedded VORTEX management dashboard (build plan M7): a React single-page app, built by Vite and embedded into the binary, so the management UI ships with VORTEX and needs no separate server.	Package dashboard serves the embedded VORTEX management dashboard (build plan M7): a React single-page app, built by Vite and embedded into the binary, so the management UI ships with VORTEX and needs no separate server.
devops Package devops implements VORTEX's DevOps agent (build plan M16): SSH-based VPS management — running commands, transferring files, and driving Docker and Nginx on remote servers.	Package devops implements VORTEX's DevOps agent (build plan M16): SSH-based VPS management — running commands, transferring files, and driving Docker and Nginx on remote servers.
forge Package forge implements VORTEX Forge (build plan M13): the autonomous app builder.	Package forge implements VORTEX Forge (build plan M13): the autonomous app builder.
healing Package healing implements VORTEX's self-healing infrastructure (build plan M14): health monitoring of routes and subsystems, automatic recovery actions, a process watchdog, and SLO-breach alerting.	Package healing implements VORTEX's self-healing infrastructure (build plan M14): health monitoring of routes and subsystems, automatic recovery actions, a process watchdog, and SLO-breach alerting.
keyring Package keyring manages VORTEX's root key material.	Package keyring manages VORTEX's root key material.
messaging Package messaging implements VORTEX's messaging integration layer (build plan M11): two-way bots over Telegram, WhatsApp, and Slack, plus a unified notification router and an AI provider gateway.	Package messaging implements VORTEX's messaging integration layer (build plan M11): two-way bots over Telegram, WhatsApp, and Slack, plus a unified notification router and an AI provider gateway.
observability Package observability implements VORTEX's observability stack (build plan M5): OpenTelemetry distributed tracing, a Prometheus metrics registry, an HTTP middleware that records both, a localhost pprof profiler, and SLO/error-budget tracking.	Package observability implements VORTEX's observability stack (build plan M5): OpenTelemetry distributed tracing, a Prometheus metrics registry, an HTTP middleware that records both, a localhost pprof profiler, and SLO/error-budget tracking.
orchestration Package orchestration implements VORTEX's multi-agent orchestration (build plan M18): decomposing a goal into tasks (planner), running them with dependency + concurrency control (orchestrator), a shared key/value memory, and a dependency-aware task queue.	Package orchestration implements VORTEX's multi-agent orchestration (build plan M18): decomposing a goal into tasks (planner), running them with dependency + concurrency control (orchestrator), a shared key/value memory, and a dependency-aware task queue.
perf Package perf implements VORTEX's performance harness (build plan M9): a benchmark suite for continuous throughput/latency tracking with regression detection, OS-level tuning recommendations, and horizontal autoscale triggers.	Package perf implements VORTEX's performance harness (build plan M9): a benchmark suite for continuous throughput/latency tracking with regression detection, OS-level tuning recommendations, and horizontal autoscale triggers.
pipeline Package pipeline implements VORTEX's data pipeline agent (build plan M17): reading tabular data (CSV/JSON), transforming it (filter/aggregate/sort), rendering charts (SVG), and running scheduled jobs.	Package pipeline implements VORTEX's data pipeline agent (build plan M17): reading tabular data (CSV/JSON), transforming it (filter/aggregate/sort), rendering charts (SVG), and running scheduled jobs.
plugins Package plugins implements VORTEX's WebAssembly plugin system (build plan M6): a sandboxed wazero runtime, a request/response hook chain, WASM-backed hooks, and a plugin registry.	Package plugins implements VORTEX's WebAssembly plugin system (build plan M6): a sandboxed wazero runtime, a request/response hook chain, WASM-backed hooks, and a plugin registry.
policy Package policy provides VORTEX's authorization policy engine (build plan M3.4): it embeds the Open Policy Agent (OPA) Rego evaluator so operators can express request-authorization rules as .rego policies, hot-reloaded without a restart.	Package policy provides VORTEX's authorization policy engine (build plan M3.4): it embeds the Open Policy Agent (OPA) Rego evaluator so operators can express request-authorization rules as .rego policies, hot-reloaded without a restart.
proxy Package proxy wires VORTEX's config into running data-plane listeners (the end-of-M2 integration step): for each configured route it starts the matching TCP tunnel, UDP tunnel, HTTP/HTTPS reverse proxy, or QUIC/HTTP3 dual-stack listener, runs them under one lifecycle, and aggregates their stats.	Package proxy wires VORTEX's config into running data-plane listeners (the end-of-M2 integration step): for each configured route it starts the matching TCP tunnel, UDP tunnel, HTTP/HTTPS reverse proxy, or QUIC/HTTP3 dual-stack listener, runs them under one lifecycle, and aggregates their stats.
proxy/gateway Package proxygateway implements VORTEX's protocol gateway (build plan M2.6): it inspects each request and dispatches WebSocket upgrades, gRPC calls, and plain HTTP to the appropriate handler.	Package proxygateway implements VORTEX's protocol gateway (build plan M2.6): it inspects each request and dispatches WebSocket upgrades, gRPC calls, and plain HTTP to the appropriate handler.
proxy/http Package proxyhttp implements VORTEX's L7 (HTTP/1.1 + HTTP/2) reverse proxy (build plan M2.2): a pooled RoundTripper, request router, load balancers, the proxy handler, and the internet-facing server.	Package proxyhttp implements VORTEX's L7 (HTTP/1.1 + HTTP/2) reverse proxy (build plan M2.2): a pooled RoundTripper, request router, load balancers, the proxy handler, and the internet-facing server.
proxy/quic Package proxyquic implements VORTEX's QUIC / HTTP/3 transport (build plan M2.3) on top of github.com/quic-go/quic-go.	Package proxyquic implements VORTEX's QUIC / HTTP/3 transport (build plan M2.3) on top of github.com/quic-go/quic-go.
proxy/tcp Package tcp implements VORTEX's raw TCP tunnel engine (build plan M2.1): a bidirectional byte pump between a client connection and a backend connection, a per-backend connection pool, a weighted round-robin selector, and an accept loop that wires them together.	Package tcp implements VORTEX's raw TCP tunnel engine (build plan M2.1): a bidirectional byte pump between a client connection and a backend connection, a per-backend connection pool, a weighted round-robin selector, and an accept loop that wires them together.
proxy/udp Package proxyudp implements VORTEX's UDP tunnel (build plan M2.5): a session-tracking forwarder for connectionless UDP traffic with a per-source-IP token-bucket rate limiter.	Package proxyudp implements VORTEX's UDP tunnel (build plan M2.5): a session-tracking forwarder for connectionless UDP traffic with a per-source-IP token-bucket rate limiter.
research Package research implements VORTEX's research agent (build plan M15): web search, content fetching, AI summarization, and report generation.	Package research implements VORTEX's research agent (build plan M15): web search, content fetching, AI summarization, and report generation.
secrets Package secrets implements VORTEX's encrypted secret store (build plan M3.2): a key-value store for arbitrary secret strings (database passwords, API keys, JWT secrets) encrypted at rest with XChaCha20-Poly1305.	Package secrets implements VORTEX's encrypted secret store (build plan M3.2): a key-value store for arbitrary secret strings (database passwords, API keys, JWT secrets) encrypted at rest with XChaCha20-Poly1305.
security Package security implements VORTEX's edge protection (build plan M3.7): an HTTP-layer token-bucket rate limiter keyed per client IP, an IP allowlist/blocklist with Tor-exit and auto-ban support, and an edge middleware that composes them.	Package security implements VORTEX's edge protection (build plan M3.7): an HTTP-layer token-bucket rate limiter keyed per client IP, an IP allowlist/blocklist with Tor-exit and auto-ban support, and an edge middleware that composes them.
service Package service generates init-system integration (systemd units, OpenRC scripts) and installs VORTEX as a managed system service (build plan M1.4).	Package service generates init-system integration (systemd units, OpenRC scripts) and installs VORTEX as a managed system service (build plan M1.4).
studio Package studio implements VORTEX Studio (build plan M12): a browser-based IDE and operations console served from the binary.	Package studio implements VORTEX Studio (build plan M12): a browser-based IDE and operations console served from the binary.
tenancy Package tenancy implements VORTEX's multi-tenancy layer (build plan M8): namespaces that isolate routes, secrets, metrics, and logs per tenant, with per-namespace resource quotas enforced at the HTTP and TCP edge.	Package tenancy implements VORTEX's multi-tenancy layer (build plan M8): namespaces that isolate routes, secrets, metrics, and logs per tenant, with per-namespace resource quotas enforced at the HTTP and TCP edge.
tls Package vtls implements VORTEX's TLS layer (build plan M2.4): an encrypted certificate store, a local development CA, an ACME (Let's Encrypt/ZeroSSL) manager, and a unified entry point.	Package vtls implements VORTEX's TLS layer (build plan M2.4): an encrypted certificate store, a local development CA, an ACME (Let's Encrypt/ZeroSSL) manager, and a unified entry point.
tui Package tui implements VORTEX's full-screen terminal UI (a Bubble Tea application).	Package tui implements VORTEX's full-screen terminal UI (a Bubble Tea application).
tui/app Package app is the root Bubble Tea application for the VORTEX terminal UI.	Package app is the root Bubble Tea application for the VORTEX terminal UI.
tui/views Package views implements the individual screens of the VORTEX terminal UI.	Package views implements the individual screens of the VORTEX terminal UI.
update Package update implements VORTEX's self-update machinery: querying the GitHub releases API, downloading and verifying release archives, and atomically hot-swapping the running binary.	Package update implements VORTEX's self-update machinery: querying the GitHub releases API, downloading and verifying release archives, and atomically hot-swapping the running binary.
pkg
atomicfile Package atomicfile writes a file atomically: data is written to a temp file in the same directory, fsync'd, then renamed over the destination.	Package atomicfile writes a file atomically: data is written to a temp file in the same directory, fsync'd, then renamed over the destination.
lifecycle Package lifecycle manages VORTEX's process lifecycle: ordered startup, signal handling, and graceful shutdown (build plan M1.4).	Package lifecycle manages VORTEX's process lifecycle: ordered startup, signal handling, and graceful shutdown (build plan M1.4).
logger Package logger provides VORTEX's structured logging built on the Go standard library's log/slog (Non-Negotiable Rule #10: standard library first).	Package logger provides VORTEX's structured logging built on the Go standard library's log/slog (Non-Negotiable Rule #10: standard library first).
pidfile Package pidfile manages VORTEX's PID file: a small text file holding the running server's process ID.	Package pidfile manages VORTEX's PID file: a small text file holding the running server's process ID.
safedial Package safedial builds HTTP clients that are robust against SSRF via DNS rebinding (production audit H2).	Package safedial builds HTTP clients that are robust against SSRF via DNS rebinding (production audit H2).
web
dashboard Package dashboardui embeds the built VORTEX management dashboard (the Vite production build in dist/) so it ships inside the Go binary.	Package dashboardui embeds the built VORTEX management dashboard (the Vite production build in dist/) so it ships inside the Go binary.