Hakopod

English · 简体中文 · 日本語 · Español · Português · Deutsch

Your apps. Your rules. Hakopod is an open-source platform for deploying and
running your apps on servers you own: push from Git, import a docker-compose.yml
or pick a template, review what will change, then deploy with TLS on your domain.

curl -fsSL https://hakopod.com/scripts/installer.sh | sudo sh

One fresh Ubuntu or Debian server with 4 GiB RAM is enough to start. Hakopod is in
alpha; read what is and isn't verified yet before you trust
it with production work. Website and guides: hakopod.com.

What you can stop paying for

Each row is a template in the catalog that you can deploy
from the dashboard today. The catalog records each template's verification status
and limits, so check it before relying on one.

Why Hakopod

• Kubernetes underneath, no YAML on top. Hakopod runs on K3s from the first
  server, so growing to a second machine means enrolling a worker, not migrating.
  You describe an application and its services; Hakopod writes the manifests.
• See the change before it ships. Every deployment starts as a plan showing
  what will change. Rollback creates a new, auditable revision.
• Bring your Compose file. Paste a docker-compose.yml, review the converted
  configuration and the plan, then deploy.
• Give agents a key, not your cluster. The CLI and MCP endpoint use scoped,
  short-lived machine keys. CI and agents never need Kubernetes credentials.
• Private by default. Services share a private network; only the ones you
  mark public get an address.

How it compares

Coolify, Dokploy and Openship are good tools, and if you want the most mature
option today, Coolify has the largest community. This is how the approaches
differ, based on each project's own documentation in October 2026:

K3s costs memory, which is why Hakopod asks for more than Docker-based tools. In
return, scheduling across servers and rolling updates come from Kubernetes
rather than from code we wrote ourselves.

How we build it

We build Hakopod with help from AI coding agents; you'll find their instructions
in AGENTS.md. Every release runs the installer on fresh amd64 and
arm64 GitHub runners before it's published, and docs/milestones.md records
what we've verified on real clusters and what we haven't. If something breaks,
open an issue and tell us your
version, OS and what you tried.

Under the hood

Hakopod combines a Go API and reconciler, a small CLI, PostgreSQL durable state,
and a TanStack Start dashboard over K3s and HAProxy. This repository includes the
deployment engine and the dashboard: human accounts, team roles, source builds,
templates, live service monitoring, searchable logs, container and host terminals,
custom domains, encrypted backups, registry credentials, TLS controls and worker
enrollment. See the cockpit guide.

Open source and Cloud

Hakopod is licensed under Apache-2.0. Hakopod Cloud
is a hosted extension of this open-source engine and dashboard. Code contributed
here may be used in both the self-hosted edition and the commercial Cloud
service under Apache-2.0. Contributors retain copyright; Cloud-specific code
outside this repository may have separate terms. See Contributing.

Install on a Linux server

On a fresh dedicated Ubuntu 24.04/26.04 or Debian 12/13 server, with amd64 or
arm64 and at least 4 GiB RAM and 30 GiB free disk:

curl -fsSL https://hakopod.com/scripts/installer.sh | sudo sh

Already root? Use | sh. The script selects the newest complete stable release,
or the newest complete prerelease when no stable release is available. Hakopod
currently remains an alpha for evaluation; read the release notes
before installing. The script asks for your settings and shows a plan before
installing Hakopod. It installs missing prerequisites, K3s and prebuilt binaries. Choose
managed PostgreSQL or supply a dedicated existing database; external connections
require verified TLS. No Go or frontend compilation runs on the server.

First setup lets you choose the administrator. Public signup stays disabled in
self-hosted binaries; Free teams can enroll explicitly invited members.
See the installer guide for reviewing the script,
requirements and noninteractive configuration, and the
verification record for tested
behavior and remaining limits.

Trying Hakopod for the first time? We welcome feedback on installation and your
first deployment. Open an issue
with your Hakopod version, server OS and architecture, what you tried and what
happened. Remove credentials and private application data from any logs you share.

Run locally

Requires Docker, Go 1.26.8, Python 3, kubectl, Helm 3, Node >=22.12 and pnpm.
The development script pins and verifies its local k3d download. It creates an
isolated hakopod-dev cluster without changing your Kubernetes default context.

python3 scripts/ui-source.py restore  # public component sources; no private repo access
./scripts/local-up.sh
make build
make api                       # leave running in this terminal

In another terminal:

pnpm --dir web install --frozen-lockfile
make dashboard

Open the dashboard. On first installation, choose your
administrator name, email and password. The installer proof is saved in the
restricted .local/setup-secret file; no default human account is created.
Fresh installations then queue a labelled, removable shop sample. Existing
accounts and applications are preserved when the server restarts or upgrades.
The local API is on port 8080; application HTTP ingress is
on port 18080. Local HTTP is explicitly a loopback development configuration.
Dashboard production startup, HTTPS origin and session-secret settings are
documented in web/README.md.

Deploy the real public web/private API example using the same Go API:

source .local/env
export HAKOPOD_API_URL=http://127.0.0.1:8080
bin/hakopod login --project demo --environment development
bin/hakopod validate --file examples/shop/hakopod.toml
bin/hakopod plan --file examples/shop/hakopod.toml --project demo --environment development
bin/hakopod deploy --file examples/shop/hakopod.toml --project demo --environment development --wait

For CI, create a named project/environment-scoped key through the dashboard or
hakopod key-create; store it in the CI secret store as HAKOPOD_API_KEY with
HAKOPOD_API_URL. CI needs no browser session or Kubernetes credentials.
The bootstrap command remains an explicit machine-credential recovery/development
tool. Dashboard sign-in uses human accounts.

The GitHub deployment action adds a step for existing
applications, with selected services, image digests and optional environment
changes:

- uses: hakopod/deploy@v1
  with:
    api-url: ${{ vars.HAKOPOD_API_URL }}
    api-token: ${{ secrets.HAKOPOD_API_TOKEN }}
    application-id: ${{ vars.HAKOPOD_APPLICATION_ID }}
    services: '["api", "worker"]'

The action is maintained in its own repository and published on
GitHub Marketplace.
Pin a full reviewed release commit SHA in production workflows. It keeps saved
images unless you provide a digest-pinned image, and waits for deployment
success by default.

Build release artifacts

Developers can build the server, dashboard and installer kit locally:

python3 release/build.py
python3 release/build-installer.py

Transfer the resulting kit to a fresh dedicated Linux server and use the
installer guide to review its configuration and checksums.
The public installation command above downloads the verified release instead.

Cloud deployments

AWS, GCP and Azure provisioning for the planned Bring Your Own Cloud managed
service lives in the private hakopod/hakopod-cloud repository. That repository includes this public engine as its engine
submodule; the public engine never depends on private Cloud source. It starts with one Ubuntu server and the same installer on
amd64 or arm64. See cloud deployments for scope,
access and the remaining cloud acceptance tests.

Customer-owned BYOC uses the self-hosted feature set. Hakopod Cloud is the
planned shared hosting service for Git deployments, HTTP/HTTPS, custom domains
and private service networking. Public SMTP, SFTP and other custom TCP listeners
stay on self-hosted installations, whether Free or licensed. See
product modes for the enforced boundary and remaining
Cloud launch requirements.

The initial private Cloud beta supplies a control dashboard for one node you
bring. It includes no compute and is limited to allowlisted testers. Its service
lives in the private repository and reuses this engine’s authentication and
PostgreSQL storage primitives. Real hosted deployment acceptance is pending.

Accounts, licensing and components

Deployment and operational tools stay available in Free. Team creation,
invitations and fixed shared project roles are included in Free. Advanced paid
capabilities require explicit signed entitlements. The
dashboard shows the feature catalog and activation state; the Go API and durable
workers enforce it. Expiry preserves accounts, application data and running
workloads. See paid features for the exact behavior.

Public self-hosted binaries keep signup closed; the installer claims the first
owner and explicit invitations enroll other members. Cloud builds require
managed-cloud mode and HAKOPOD_SIGNUP_ENABLED=true to open public registration.
Email verification and password recovery use configured SMTP; GitHub, GitLab and
Google use the configured OAuth clients. See accounts.

Server startup settings can live in a strict, versioned TOML file selected by
HAKOPOD_CONFIG_FILE. Environment values still override it, and credentials stay
in restricted files or the environment. See operator configuration.

The Hatch design system is a separate
shadcn/Radix component repository at packages/ui, with its consumer package at
packages/ui/packages/ui. The public source bundle in third_party/ui/ makes
ordinary builds independent of submodule hosting. The license issuer and
commercial cloud toolkit are separate private submodules, excluded from public
release artifacts. Submodule URLs resolve to sibling repositories in the Hakopod
GitHub organization.
The shared template catalog is a public
submodule at templates/. Initialize it with git submodule update --init templates
before building. Public contributors should restore the UI bundle without recursively fetching
private repositories. See submodule development.

The logs and terminals guide explains SQL-style filters,
live resource observations, terminal permissions and bounds, and GitLab source sync.
Application logs covers how logs outlive pods, retention, gaps and upgrades.
Security advisories explains advisory matching, notifications and fixes. Runtime alarms covers the dashboard inbox, unhealthy-resource
and recovery notifications, scoped settings, and optional SMTP delivery.
The template catalog records each preset's credentials,
storage, memory and verification limits. Binding reliability
explains automatic connection-setting rollouts and tests from an application pod.
Application lifecycle covers deployment jobs, configuration files, connection bindings, multiple HTTP endpoints and capacity checks. Backups explains
S3-compatible destinations, schedules, recovery keys and restores into fresh
database names. A management backup covers the logical database, not the whole
host or Kubernetes cluster.

One application, several services

schema_version = 1
name = "shop"

[services.web]
image = "ghcr.io/your-org/web:1.0.0"
port = 3000
public = true

[services.web.env]
API_URL = "http://api:8080"

[services.api]
image = "ghcr.io/your-org/api:1.0.0"
port = 8080

This illustrative configuration uses placeholder images. The runnable
shop example uses public multi-architecture images.
Services share a private network by default; only public=true creates an
Ingress. Browser code calls the public web server, which proxies to the private
API. A background worker can omit its port entirely.

The Go API owns strict TOML validation, staged diff, expected-revision checks,
digest resolution and durable deployment execution. Accepted work survives
client disconnection and management restarts. Rolling updates wait for the
new pod template to be ready, and failed groups attempt recovery to the last
healthy release. Explicit rollback creates a new auditable revision.

Keep it small

The default profile runs no Redis, retained logging stack, Prometheus or external
secret service. Deployment concurrency is two in one Go process with a 192 MiB
soft memory target; streams, API pages, query caches and connection pools are bounded.
The same process runs one backup or restore at a time with a reusable 8 MiB upload
buffer. Optional agent and model workloads run only when deployed; browsing their
templates does not start them or download their images.
Application pages use a 512 KiB specification/observation budget; deployment
history is metadata-only, with full revisions fetched on demand.

Local limits are 2304 MiB for the K3s node including its pods, 256 MiB for
PostgreSQL, and 64 MiB for the forwarding helper. An idle pre-application
measurement was roughly 717 MiB across those three containers. This is an
observed development snapshot, not a minimum hardware or load guarantee.
Allow at least 4 GiB for Docker plus capacity for applications and rollout surge.
Stop development infrastructure without deleting data using
./scripts/local-down.sh; stop API/dashboard terminals separately.

Verify and extend

make check
source .local/env
HAKOPOD_TEST_DATABASE_URL="$HAKOPOD_DATABASE_URL" go test ./internal/api ./internal/store
python3 scripts/acceptance.py

See the local guide, architecture,
threat model, TOML reference,
Terraform provider,
TypeScript SDK,
OpenAPI contract, and contributor instructions.
The project uses Apache-2.0 for original code; dependencies retain their own
licenses and notices.

Build and release workflows: framework setup, MCP, schedules, previews, recovery and build secrets.

Service execution: node placement, serverless HTTP functions and containers,
predefined jobs, and sandbox sessions (under native qualification).