Workspace environment
The paths, HART_ variables, preinstalled tools and the user that the editor, steps and services of a workspace see.
The editor, the terminals, the steps of prepare and test, and every service of a landscape run in pods of the workspace. They share its volume and see the same paths, user and built-in variables. This page lists them as of v1.5.0.
Paths
| Path | What it holds | Kept when the workspace sleeps or restarts |
|---|---|---|
/data/app | Your code: the repository, or the files of an empty workspace. Terminals and steps start here, and harthelm.yml lives here. | Yes, on the workspace's volume |
/data/tools | Tools you install: mise's runtimes (/data/tools/mise) and the editor's settings and extensions. | Yes |
/nix | The Nix store and your Nix profile. Read-only in service pods. | Yes |
/home/harthelm ($HOME) | Your home directory: shell history, caches (~/.cache), hart's contexts file. At most 2 GiB. | No. It starts empty with every new pod. |
/run/harthelm | Harthelm's agent and its sockets. | No |
Keep everything you need in /data/app or /data/tools. Anything else is lost when the workspace goes to sleep, is
moved to another node or restarts after an upgrade.
The size of the volume is the workspace plan's storage; see Limits › Plans.
User
Every process runs as one user ID of group 0, with the user name harthelm and the home directory
/home/harthelm. The user ID is the volume's owner, set by the installation (1001 by default), and it is the same in
the editor, the steps and the services. Do not rely on its number: it can differ between installations.
There is no sudo and no root. Install tools without root: with mise, with Nix, or into /data/tools.
A container service runs as the same user ID, whatever USER its image names, unless your team may set
runAsUser. Files the image needs to write must be writable for group
0. See Run a container image.
Built-in variables
Harthelm sets these in every pod of the workspace. Names starting with HART_ are reserved: harthelm.yml cannot set
them (reserved-name).
| Variable | Value | Where |
|---|---|---|
HART_WORKSPACE_ID | The workspace's id, for example 42. | Everywhere |
HART_TEAM_ID | The team's id. | Everywhere |
HART_DEV_DOMAIN | The dev URL, https://<id>-3000.<workspace domain>. | Everywhere |
HART_DATA | /data/app | Everywhere |
HART_USER | harthelm | Everywhere |
HART_SERVICE | The service's name; ide in the editor's pod. | Everywhere |
HART_REPLICA | The pod's name, unique per replica. | Everywhere |
HART_STAGE | prepare, test or run. | In steps |
HART_API | The API's address inside the cluster. hart uses it. | Editor and services |
HART_CONSOLE_ORIGIN | The console's address, for example https://console.example.com. | Editor and services |
HART_INTERNAL_CA_FILE | /etc/harthelm/internal-ca/ca.crt, the installation's internal CA, when in-cluster TLS is on. Trust it to reach a managed service over TLS. | Editor and services |
Your own variables come on top:
- Workspace variables (Environment variables on the rail, or
hart env) are set in the editor, the terminals, the steps and every service. - A service's
envinharthelm.ymlis set only in that service, and wins over a workspace variable of the same name. It can use templates such as${{ workspace.devDomain }}and${{ secrets.API_KEY }}; see the env keys. - Secrets reach only the services that reference them. Prepare and test never see secrets.
A changed variable or secret reaches the services at the next Sync.
Write $HART_WORKSPACE_ID in a step, not ${{ workspace.id }}: templates work only in env values, managed services
and forward targets.
Tool settings
These are set for the tools, so that their caches stay in $HOME and their data on the volume:
| Variable | Value |
|---|---|
HOME | /home/harthelm |
PATH | starts with /home/harthelm/.nix-profile/bin |
MISE_DATA_DIR | /data/tools/mise |
XDG_CACHE_HOME | /home/harthelm/.cache |
MISE_CACHE_DIR, NPM_CONFIG_CACHE, PIP_CACHE_DIR, UV_CACHE_DIR, GOCACHE, GOMODCACHE | below /home/harthelm/.cache |
Your administrator may add proxy and mirror settings (HTTP_PROXY, HTTPS_PROXY, NO_PROXY, NIX_CONFIG,
NPM_CONFIG_*, PIP_*, GOPROXY and others), for example on an installation without internet access. A service's own
env wins over them.
Preinstalled tools
The default base image is Ubuntu 26.04 with:
| Tool | Use |
|---|---|
| mise | Installs language runtimes per project: mise install node@22, or a .tool-versions file. |
| Nix | Any other package: nix profile install nixpkgs#jq. Flakes are on; nixpkgs is pinned to one revision per release. |
git, git-lfs | Version control. The workspace's repository is set up as origin; fetches and pushes go through Harthelm, which signs them in for you. |
hart | Harthelm's command line, already pointed at this installation, team and workspace. |
bash, curl, less, openssh-client, procps, ripgrep, tar, tmux, unzip, xz-utils | The basics. |
The editor is code-server (VS Code in the browser) with YAML support that
knows the schema of harthelm.yml. Extensions you install are kept in /data/tools.
Your installation may offer more base images; Create workspace lists them.
hart inside a workspace
hart in a workspace knows its installation, team and workspace from the variables above. Sign in once per start of
the workspace:
hart login --codeThe key is stored in $HOME, so it is gone when the pod restarts, and every editor of the workspace can read it while
it runs. Sign out when you are done:
hart logoutSee hart login.
Network
| From the workspace | Reachable |
|---|---|
| Other services of the same workspace | Yes, as ws-<id>-<name>:<port>, for example http://ws-42-api:8080; or through the dev URL's routes |
| A managed service of the landscape | Yes, through ${{ services.<name>.host }} and the other connection fields |
| The internet | Usually yes; your installation may route it through a proxy or block it |
| Private addresses of your network | No, unless your administrator allows a mirror |
| Other teams' workspaces | No |
Ports 7777 (Harthelm's agent) and 3000 (the dev URL's entry, routed by path) have fixed uses; see URLs and routing.