Skip to content

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.
  • A handler file (e.g. main.py, index.ts) exposing an entry point that HollowHost will call with an event payload.
  • A dependency manifest:
    • Python: requirements.txt (pip) or pyproject.toml (uv).
    • TypeScript: package.json (npm / yarn / pnpm).

A minimal Python example:

main.py
def handler(event, context):
    print("Hello from my first HollowHost AI Job!")
    return {"ok": True, "echo": 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. You can attach an optional JSON event payload.
  • 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.

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.