How Harthelm works
The parts you meet: the console, the API, the router, workspace pods and the platform database.
Harthelm runs inside one Kubernetes cluster. You never need to touch Kubernetes to use it, but knowing which part does what helps when something is slow or refused.
The parts
| Part | What it does for you |
|---|---|
| Console | The web app at <console>: workspaces, the IDE, the Run panel, members, domains, settings |
| API | Everything the console does goes through the REST API under /api/v1. hart and your scripts use the same API with an API key |
| Router | Serves every workspace address: dev URLs, public ports and custom domains. It checks who may open a private address, wakes sleeping workspaces and services, and sends each path to the right service |
| Workspace pod | Your workspace: the VS Code editor, terminals and the prepare and test stages, with your code on the workspace's own volume |
| Service pods | The services of your landscape. A steps service runs your commands; a container service runs your image |
| Managed services | Databases and other services from the catalog, run by Harthelm next to your workspaces |
| Platform database | A PostgreSQL database that holds the state of the installation: teams, workspaces, landscapes, secrets (encrypted) |
The console, the API and the background work are one server, called core. Core is the only part that changes Kubernetes: it turns what the database says into pods, volumes and routes.
What happens when you…
…create a workspace. Core creates a volume and a workspace pod in your team's part of the cluster. If you start from a repository, the pod clones it through Harthelm's Git proxy with your Git connection; your token never reaches the workspace.
…Sync. Core reads harthelm.yml from the workspace, checks it against the schema, your team's quota and the
installation's plans, shows you the review, and then creates or changes the service pods, managed services and routes.
Nothing starts yet.
…Run. Every replica of every steps service runs its steps in order; the last step is the server. The router sends
requests to a replica once its health check passes.
…open a dev URL. The router checks that you are a signed-in member of the team (for a private workspace), wakes the workspace's services if they sleep, holds your request until they are ready, and forwards it.
…leave it alone. After the idle timeout (60 minutes by default) the router and the workspace report no more activity, and core scales the IDE and the services to zero. The volume, env vars and secrets stay. The next request wakes them.
Where your things live
| Thing | Where |
|---|---|
| Your code | /data/app on the workspace volume. Tools installed with mise or Nix live on the same volume, outside /data/app |
| Your home directory | Emptied when the workspace restarts or wakes. Do not keep anything there |
| Env vars and secrets | The platform database; secrets encrypted, and never shown again once set |
| Landscape state | The platform database: what was synced, which profile, which services run |
| Database data | The managed service's own volume, dumped every night |