README.md
Rama main · réplica de lectura del repositorio original.
# Hakopod
English · [简体中文](docs/i18n/README.zh.md) · [日本語](docs/i18n/README.ja.md) · [Español](docs/i18n/README.es.md) · [Português](docs/i18n/README.pt-BR.md) · [Deutsch](docs/i18n/README.de.md)
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.
[](https://hakopod.com/media/your-apps-your-terms/film.mp4)
<sub>Watch the [one-minute tour](https://hakopod.com/media/your-apps-your-terms/film.mp4).</sub>
```sh
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](docs/milestones.md) before you trust
it with production work. Website and guides: [hakopod.com](https://hakopod.com).
## What you can stop paying for
Each row is a template in the [catalog](docs/templates.md) 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.
| Instead of | Run |
| --- | --- |
| Vercel, Heroku, Render | Your own apps, from Git, a Dockerfile or Compose |
| Sentry | GlitchTip |
| Google Analytics | Umami |
| Zapier | n8n |
| Pingdom, Better Stack | Uptime Kuma |
| Airtable | NocoDB |
| A shared password manager | Vaultwarden |
| ChatGPT team seats | Open WebUI with your own model keys |
| Managed Postgres and Redis | PostgreSQL, Valkey, Redis |
## 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:
| | Hakopod | Coolify | Dokploy | Openship |
| --- | --- | --- | --- | --- |
| Runs apps on | K3s (Kubernetes) | Docker | Docker, Swarm for multiple servers | Docker, K3s for clusters |
| Written in | Go | PHP (Laravel) | TypeScript | TypeScript |
| Shows what will change before each deploy | Yes, a plan per deployment | — | — | Review step in the deploy wizard |
| Preview environments | Manual, from a built image, 1–72 hours | Per pull request | Per pull request (GitHub) | From a Git branch |
| IP allow and deny lists, rate limits, country rules | In the dashboard | — | — | From the CLI |
| Limit the dashboard and API to your networks or a VPN | Allow list, firewall, built-in WireGuard server, Tailscale, OpenVPN, IPsec (Pro) | API IP allow list | — | — |
| Passkeys / TOTP | Yes / Yes | No / Yes | Yes / Yes | Yes / Yes |
| Scale idle apps to zero | Yes | — | — | Yes |
| MCP for AI agents | Yes | Yes | Yes | Yes |
| Official Terraform provider | Yes | — | Community only | — |
| Managed databases | PostgreSQL, MySQL, MongoDB, Redis, ClickHouse, Vitess, Oracle Free | PostgreSQL, MySQL, MariaDB, MongoDB, Redis, ClickHouse | PostgreSQL, MySQL, MariaDB, MongoDB, Redis, libSQL | PostgreSQL, MySQL, MongoDB, Redis |
| Ready-to-deploy templates | 68 | 300+ | 500+ | 42 |
| Audit log | Yes; history export is Pro | Yes | Enterprise | Yes |
| License | Apache-2.0 | Apache-2.0 | Apache-2.0, plus a proprietary directory | Apache-2.0 |
"—" means we found no mention of it in that project's own documentation, not
that it can't be done there. Tell us if a cell is out of date.
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](AGENTS.md). Every release runs the installer on fresh amd64 and
arm64 GitHub runners before it's published, and [docs/milestones.md](docs/milestones.md) records
what we've verified on real clusters and what we haven't. If something breaks,
[open an issue](https://github.com/hakopod/hakopod/issues/new) 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](docs/cockpit.md).
## Open source and Cloud
Hakopod is licensed under [Apache-2.0](LICENSE). [Hakopod Cloud](https://cloud.hakopod.com)
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](CONTRIBUTING.md#contributions-and-hakopod-cloud).
## 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:
```sh
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](https://github.com/hakopod/hakopod/releases)
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](installer/README.md) for reviewing the script,
requirements and noninteractive configuration, and the
[verification record](docs/prebuilt-installation-verification.md) for tested
behavior and remaining limits.
Trying Hakopod for the first time? We welcome feedback on installation and your
first deployment. [Open an issue](https://github.com/hakopod/hakopod/issues/new)
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.
```sh
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:
```sh
pnpm --dir web install --frozen-lockfile
make dashboard
```
Open [the dashboard](http://127.0.0.1:4173). 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](web/README.md).
Deploy the real public web/private API example using the same Go API:
```sh
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](https://github.com/hakopod/deploy) adds a step for existing
applications, with selected services, image digests and optional environment
changes:
```yaml
- 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](https://github.com/marketplace/actions/deploy-to-hakopod).
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:
```sh
python3 release/build.py
python3 release/build-installer.py
```
Transfer the resulting kit to a fresh dedicated Linux server and use the
[installer guide](installer/README.md) 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](docs/cloud-deployments.md) 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](docs/product-modes.md) 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](docs/paid-features.md) 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](docs/accounts.md).
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](docs/operator-configuration.md).
The [Hatch design system](https://github.com/hakopod/hatch-ui) 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](https://github.com/hakopod/templates) 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](docs/submodules.md).
The [logs and terminals guide](docs/observability.md) explains SQL-style filters,
live resource observations, terminal permissions and bounds, and GitLab source sync.
[Application logs](docs/application-logs.md) covers how logs outlive pods, retention, gaps and upgrades.
[Security advisories](docs/security-advisories.md) explains advisory matching, notifications and fixes. [Runtime alarms](docs/alarms.md) covers the dashboard inbox, unhealthy-resource
and recovery notifications, scoped settings, and optional SMTP delivery.
The [template catalog](docs/templates.md) records each preset's credentials,
storage, memory and verification limits. [Binding reliability](docs/database-binding-reliability.md)
explains automatic connection-setting rollouts and tests from an application pod.
[Application lifecycle](docs/application-lifecycle.md) covers deployment jobs, configuration files, connection bindings, multiple HTTP endpoints and capacity checks. [Backups](docs/backups.md) 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
```toml
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](examples/shop/README.md) 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
```sh
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](docs/local-development.md), [architecture](docs/architecture.md),
[threat model](docs/threat-model.md), [TOML reference](docs/toml.md),
[Terraform provider](docs/terraform.md),
[TypeScript SDK](packages/sdk/README.md),
[OpenAPI contract](api/openapi.json), and [contributor instructions](CONTRIBUTING.md).
The project uses Apache-2.0 for original code; dependencies retain their own
[licenses and notices](docs/licenses.md).
Build and release workflows: [framework setup, MCP, schedules, previews, recovery and build secrets](docs/engine-workflows.md).
Service execution: [node placement](docs/node-placement.md), [serverless HTTP functions and containers](docs/serverless.md),
[predefined jobs](docs/job-invocations.md), and [sandbox sessions](docs/sandbox-sessions.md) (under native qualification).