Vela OS

Vela is a self-hostable, serverless Postgres development platform. Built on a high-performance distributed storage layer, it provides instant database branching, independent scaling of compute and storage, and enterprise-grade access control — all deployable in your own cloud. Enterprise-grade features and toolkit developers love in one product.

Vela Controller is the internal control plane / orchestrator that provisions and manages Vela resources (projects, branches, compute endpoints, and supporting services) across your Vela environment.

The Vela main repository is here.

---

What is Vela Controller?

Vela Controller coordinates the lifecycle of the resources that make Vela feel “Git-like” for Postgres:

• Branch lifecycle orchestration
  Create, start, stop, and delete branch/compute endpoints while tracking state and readiness.
• Separation of compute and storage
  Orchestrate compute endpoints that attach to the underlying storage layer to enable fast cloning and branching.
• Policy-aware operations
  Apply org/project policies such as access controls, quotas, and environment constraints.
• Automation hooks
  Expose primitives that Vela Studio and CI/CD workflows can use to create and tear down isolated environments.
• Observability & health
  Provide health checks and operational signals to keep deployments stable and debuggable.

Local Development

Prerequisites

• Python 3.13
• Access to a Kubernetes Cluster with the Vela fork of Autoscaling deployed.
• Cloudflare API token and zone information for DNS record provisioning

Running a local deployment

To build the local version, run the following Docker compose.

$ docker compose -f containers/compose.yml up --build

After the compose containers are up, the Vela API is available through HAproxy at http://localhost:8000/vela, while the Keycloak admin interface is available at http://localhost:8000/auth (credentials admin/admin).

The compose file mounts your local kubeconfig at (~/.kube/config), meaning, API endpoints call the Kubernetes API defined as the current default cluster. Ensure you're not working against the wrong Kubernetes cluster to prevent breaking potential deployments.

To use the API, a valid user session is required. The compose setup automatically created a testuser. A session token can be generated by running the following command. And this token expires after 5 mins.

$ export TOKEN=$(curl -s http://localhost:8000/auth/realms/vela/protocol/openid-connect/token \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "username=testuser" \
    -d "password=testpassword" \
    -d "grant_type=password" \
    -d "client_id=frontend" \
    -d "client_secret=client-secret" | jq -r '.access_token')
$ echo $TOKEN

OpenAPI Specification

The full OpenAPI specification can be retrieved straight from the running container setup:

• Interactive user interface
• JSON Specification

---

Vela Cloud (Recommended)

The easiest way to get started is through Vela Cloud.
Free tier available — no credit card required.

Get Started

Community

Find help, explore resources, or get involved with the Vela community.

Support & Contributions

• Open an Issue – Report bugs or suggest improvements
• Start a Discussion – Share feedback and feature ideas, ask questions, share ideas, and connect with other users
• Contribute Code – Submit pull requests following our contribution guidelines

We welcome contributions of all kinds — from documentation improvements and bug fixes to new features and integrations.