Getting Started

This guide walks you through deploying your first AI Job on HollowHost, from signing up to triggering your first run.

1. Create a HollowHost account

1. Go to app.hollowhost.com.
2. Click Get Started Free and sign up with email + password (or a social provider if enabled in your environment).
3. Confirm your email via the one-time code HollowHost emails you.

You land on the Dashboard with your free-tier token balance displayed.

2. Prepare your AI Job repository

HollowHost expects a Git repository that can be built into a container image. The minimum requirements:

• A language runtime declared. Python and TypeScript are both supported out of the box.
• An entry-point script (e.g. src/main.py, src/index.ts) that HollowHost executes top-to-bottom on every run — like python src/main.py. There is no handler(event, context) callback: your script IS the job.
• A dependency manifest:
  • Python: requirements.txt (pip) or pyproject.toml (uv).
  • TypeScript: package.json (npm / yarn / pnpm).

Configuration reaches your script through environment variables: the env vars and secrets you define in the dashboard, plus the platform-provided HH_* variables:

Variable	Content
HH_EVENT	The optional JSON event payload for this run (JSON string; absent when no payload was sent)
HH_RUN_ID	The run's unique identifier
HH_SOURCE	api (manual/API trigger) or scheduler (cron)
HH_SCHEDULED_TIME	ISO timestamp the schedule fired at (scheduled runs only)

A minimal Python example:

src/main.py

import json
import os

event = json.loads(os.environ.get("HH_EVENT", "null"))
print(f"Hello from my first HollowHost AI Job! event={event}")

requirements.txt

requests==2.32.3

Push this to a GitHub repository — public or private. If private, you will provide a GitHub Personal Access Token with repo read scope when creating the AI Job.

Reusable demo repo

Want to try without writing any code? The team maintains a ready-to-deploy weather AI Job at One-Click-Flare/ia-agent-meteo — use it as-is or fork it.

3. Create your AI Job in HollowHost

1. From the dashboard, click AI Jobs → New AI Job.
2. Step 1 — Repository:
   • Repository URL — https://github.com/<org>/<repo>.
   • Branch (optional) — the git branch to deploy. Leave empty to use the repository's default branch (shown as (default branch)).
   • GitHub token — PAT with read access (stored encrypted).
3. Step 2 — Configuration:
   • Name — human-friendly label (e.g. daily-weather).
   • Description — short summary of what this AI Job does.
   • Python dependency manager — pip or uv (only for Python projects).
   • Sub-path (optional) — for mono-repos, the sub-directory to deploy. Leave empty to deploy the repository root.
   • Entry Point — the file to run (e.g. src/main.py).
4. Click Create.

Mono-repo: Entry Point is relative to the sub-path

When you set a Sub-path, that sub-directory becomes the AI Job's root at build time, so the Entry Point stays relative to it. For an AI Job at apps/agent-meteo/src/main.py with Sub-path apps/agent-meteo, set Entry Point to src/main.py — not apps/agent-meteo/src/main.py.

HollowHost validates the repository — and, when set, the branch and sub-path existence (status VALIDATING → VALIDATED).

Mono-repo example

Repo One-Click-Flare/mono-repo, branch dev, AI Job in apps/agent-meteo: set Branch = dev, Sub-path = apps/agent-meteo, Entry Point = src/main.py. The equivalent CLI command is in the CLI reference.

4. Publish the AI Job

Once the AI Job is VALIDATED:

1. Open the AI Job detail page.
2. Click Publish.

HollowHost now:

• Builds a container image from your repository.
• Creates a dedicated, isolated execution environment for this AI Job.
• Deploys your AI Job and makes it ready to run.

Status flow: DEPLOYING → DEPLOYED (or DEPLOYMENT_ERROR — check the build logs from the AI Job page if so).

5. Configure env vars and secrets (optional)

From the AI Job's Settings tab:

• Environment variables — non-sensitive config (e.g. LOG_LEVEL, TIMEZONE). Injected into your AI Job at runtime.
• Secrets — sensitive values (e.g. API keys). Stored encrypted and injected at runtime. Secrets never leave the AI Job's isolation boundary.

Changes take effect on the next run.

6. Trigger your first run

From the AI Job page:

• Manual run — click Run now. To attach a JSON event payload, trigger the run from the CLI (hollowhost ai-jobs run <id> --event '{...}') or the API — your code receives it as the HH_EVENT environment variable.
• Scheduled run — switch to the Schedule tab, enter a cron expression (e.g. 0 9 * * * for every day at 09:00 UTC), and save. HollowHost will trigger the AI Job on the specified cadence.

Once a run completes (or fails), you'll see it in the Runs list with its duration, status, token usage, and a link to the full logs.

Event payload format

An event payload lets you parameterize a single run — same deployed code, different input — without touching the AI Job's configuration (backfill a specific day, process one item, retry a failed batch…).

API contract — POST /agents/{id}/runs with a JSON body:

{"event": <any JSON value>}

• The event key can hold any JSON value: object, array, string, number, boolean or null. Objects are recommended — they stay extensible.
• Maximum request body size: 128 KB. Larger payloads, non-JSON bodies, or a body that is not a JSON object envelope are rejected with 400 {"code": "INVALID_EVENT_PAYLOAD"} and no run is created.
• The payload is ephemeral: relayed to that single run, never stored in the database. Omitting the body (or the event key) simply runs without a payload.
• From the CLI: hollowhost ai-jobs run <id> --event '{...}' or --event-file event.json (the CLI wraps your JSON in the envelope for you).

Runtime delivery — your script reads it from the environment:

Variable	Content
HH_EVENT	The event value, serialized as a JSON string. Unset when the run was triggered without a payload — always handle the absent case.
HH_RUN_ID	Unique identifier of this run
HH_SOURCE	api (manual/API/CLI) or scheduler (cron)
HH_SCHEDULED_TIME	ISO 8601 timestamp the schedule fired at (scheduled runs only)

PythonTypeScript

import json, os

event = json.loads(os.environ.get("HH_EVENT", "null"))
if event is None:
    event = {}  # no payload — fall back to defaults
day = event.get("day", "today")

const event = JSON.parse(process.env.HH_EVENT ?? "null") ?? {};
const day = event.day ?? "today";

No secrets in events

Event payloads are request data, not a secret store: they can appear in your own calling code, shell history, and client-side tooling. Keep API keys and credentials in the AI Job's Secrets — never in an event.

7. Iterate

Push new commits to your GitHub repo, click Publish again — HollowHost rebuilds the image and updates the AI Job. Previous versions remain available for rollback.

---

Next steps

• Set up token budgets and plan limits from your Account settings to control spend.
• Read the security model overview to understand the per-AI Job isolation guarantees.

Got stuck? File an issue on the GitHub repo or reach out to the HollowHost team.