Quickstart

Create a workspaceCopy Anchor Link

On Workspaces of your team, click Create workspace and fill in the dialog:

• Start from: Empty.
• Name: hello.
• Base image and IDE plan: keep the preselected ones.
• Availability: Sleeps when idle. The workspace sleeps when nobody uses it and wakes when you open it.
• Visibility: Private. Only members of your team can open its URLs.

Click Create workspace. The console opens the workspace; after a few seconds to about a minute the editor appears and the status bar says "Workspace is running".

Write a small appCopy Anchor Link

Every workspace has mise, which installs Node.js for you. In the terminal panel at the bottom, click Open a terminal; it opens in /data/app. Create the two files of the app:

cd /data/app
printf 'node 22\n' > .tool-versions
cat > server.js <<'EOF'
const http = require("node:http");
const port = Number(process.env.PORT || 3000);
http
  .createServer((req, res) => {
    res.writeHead(200, { "content-type": "text/html; charset=utf-8" });
    res.end(`<h1>Hello from Harthelm</h1><p>Workspace ${process.env.HART_WORKSPACE_ID}, path ${req.url}</p>`);
  })
  .listen(port, () => console.log(`listening on ${port}`));
EOF

Describe the landscapeCopy Anchor Link

harthelm.yml tells Harthelm how to prepare your code and which services run it. Create it in /data/app, next to server.js:

schema: harthelm/v1

prepare:
  - name: Install Node
    run: mise install node@22

services:
  web:
    type: steps
    steps:
      - name: Serve
        run: node server.js
    env:
      PORT: 3000
    ports:
      - port: 3000
        routes:
          - path: /
    health:
      port: 3000
      path: /

The prepare stage installs Node once, before the services run. The service web runs node server.js; its port 3000 gets the route / of the dev URL, and Harthelm counts it as ready once / answers. The editor knows the file's schema: hover a key to read what it means. Every key is in the harthelm.yml reference.

SyncCopy Anchor Link

Sync creates the services that harthelm.yml describes.

Prepare and RunCopy Anchor Link

If web shows Failed, open its Logs: the output of node server.js says why. The most common cause is a skipped prepare; run it, then Run again.

Open the appCopy Anchor Link

Click the link / in the row of web. A new tab opens the dev URL, https://<id>-3000.<workspace domain>/, and shows "Hello from Harthelm".

The dev URL is private: signed-in members of your team can open it, other visitors are sent to the sign-in. When nobody uses the workspace for a while (60 minutes by default), it sleeps; the next visit wakes it, and your files are kept.