Getting Started

This guide walks you through deploying your first AI agent 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 agent 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 agent!")
    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 agent.

Reusable demo repo

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

3. Create your agent in HollowHost

1. From the dashboard, click Agents → New Agent.
2. Fill in:
   • Name — human-friendly label (e.g. daily-weather).
   • Description — short summary of what this agent does.
   • Repository URL — https://github.com/<org>/<repo>.
   • GitHub token — PAT with read access (stored encrypted).
   • Python dependency manager — pip or uv (only for Python projects).
3. Click Create.

HollowHost validates the repository (status VALIDATING → VALIDATED).

4. Publish the agent

Once the agent is VALIDATED:

1. Open the agent detail page.
2. Click Publish.

HollowHost now:

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

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

5. Configure env vars and secrets (optional)

From the agent's Settings tab:

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

Changes take effect on the next run.

6. Trigger your first run

From the agent 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 agent 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 agent. 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-agent isolation guarantees.

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