# agentic-hosting

> Self-hosted PaaS for AI agents. One Go binary (`ah`) + Docker + gVisor + Traefik + Nixpacks + SQLite. Agents operate it over JSON REST `/v1/` with `Authorization: Bearer keyID.secret`. No GUI required.

agentic-hosting is designed so an agent can install the control plane on a Linux server, register a tenant with a bootstrap token, deploy from git or a Docker image, provision Postgres or Redis, and read logs — using only curl. Canonical facts come from `internal/api/server.go`. Do not invent fields.

Key facts that older docs get wrong: builds take `source_type` / `source_url` / `source_ref` (not `git_url` / `branch`); bootstrap validate is `POST /v1/system/bootstrap-token/validate` with body `{"token"}` and always returns `200 {"valid":true|false}`; reactivate is `POST /v1/tenants/{tenantID}/reactivate`; disk warn 80% / block 90%; idempotency TTL is 10 minutes; runtime logs exist at `GET /v1/services/{id}/logs`; `image` is required on create (git flow uses placeholder `"pending"`); `PATCH /v1/tenant` updates `name` only; errors are `{"error":"..."}` with no `code` field; binary and paths are `ah` / `/var/lib/ah` / `/etc/default/ah` (`AH_BOOTSTRAP_TOKEN` lives in that env file). `AH_ADMIN_TOKEN` (send `X-Admin-Token`) is required for recover / reactivate / quota patch once set; bootstrap tokens then get 403 on those routes. Register with the bootstrap token, then deploy, then `POST /v1/databases` for postgres or redis.

Start here: fetch this file, then the operator skill, then `llms-full.txt` if you need the complete docs dump. Set `AH_URL` and `AH_KEY` before calling the API. Production `ah` listens on `127.0.0.1:8080` behind Traefik and requires `X-Forwarded-Proto: https` from loopback (or `--dev`).

## Onboarding

- [Give this to your agent](https://dennisonbertram.github.io/agentic-hosting/for-agents/): shareable URLs for llms.txt and the skill
- [Operator skill](https://raw.githubusercontent.com/dennisonbertram/agentic-hosting/main/skills/agentic-hosting/SKILL.md): standalone Agent Skills file — install the server, register, deploy, databases, logs, API
- [Full docs dump](https://raw.githubusercontent.com/dennisonbertram/agentic-hosting/main/llms-full.txt): every docs-site page plus the API reference in one markdown file
- [Install & quickstart](https://dennisonbertram.github.io/agentic-hosting/install/): Docker, gVisor, Nixpacks, Traefik, systemd `ah.service`
- [Registration & API keys](https://dennisonbertram.github.io/agentic-hosting/auth/): bootstrap token → tenant → `api_key` (shown once)

## Operate

- [Deploy from git](https://dennisonbertram.github.io/agentic-hosting/deploy/): `POST /v1/services` then `POST .../builds` with `source_type=git`
- [Postgres & Redis](https://dennisonbertram.github.io/agentic-hosting/databases/): `POST /v1/databases` + connection-string + env + restart
- [REST API](https://dennisonbertram.github.io/agentic-hosting/api/): every `/v1/` route from `internal/api/server.go`
- [Env vars & secrets](https://dennisonbertram.github.io/agentic-hosting/env/): AES-256-GCM at rest; POST merges; forbidden PATH / LD_*
- [Reconciliation](https://dennisonbertram.github.io/agentic-hosting/reconciliation/): 30s loop, crash-loop circuit (5 / 10 min)
- [Crash-loop & disk guards](https://dennisonbertram.github.io/agentic-hosting/guards/): 80% warn, 90% block
- [Rate limits](https://dennisonbertram.github.io/agentic-hosting/rate-limits/): 100/200 tenant, 500/1000 global, register 5/IP/hr
- [Backups](https://dennisonbertram.github.io/agentic-hosting/backups/): `ah backup` → `/var/lib/ah/backups/`
- [Troubleshooting](https://dennisonbertram.github.io/agentic-hosting/troubleshooting/): HTTPS required, circuit open, CGO, gVisor

## Optional

- [Overview](https://dennisonbertram.github.io/agentic-hosting/): what the control plane is
- [Why it exists](https://dennisonbertram.github.io/agentic-hosting/why/): agents vs human dashboards
- [Architecture](https://dennisonbertram.github.io/agentic-hosting/architecture/): ah, Docker, gVisor, Traefik, Nixpacks, SQLite
- [Security model](https://dennisonbertram.github.io/agentic-hosting/security/): HMAC API keys, gVisor, loopback API
- [Claude Code slash commands](https://dennisonbertram.github.io/agentic-hosting/claude-code/): `/ah-deploy` `/ah-status` `/ah-db` `/ah-logs` `/ah-register` `/ah-snapshot`
- [In-repo Claude skill](https://raw.githubusercontent.com/dennisonbertram/agentic-hosting/main/.claude/skills/agentic-hosting/SKILL.md): same operator flows used by Claude Code
- [API reference (skill)](https://raw.githubusercontent.com/dennisonbertram/agentic-hosting/main/.claude/skills/agentic-hosting/references/api-reference.md): endpoint shapes
- [Server setup (skill)](https://raw.githubusercontent.com/dennisonbertram/agentic-hosting/main/.claude/skills/agentic-hosting/references/server-setup.md): bare-metal install
- [Roadmap](https://dennisonbertram.github.io/agentic-hosting/roadmap/): what the code does not do yet
- [GitHub repository](https://github.com/dennisonbertram/agentic-hosting): source and issues
- [Corrections](https://raw.githubusercontent.com/dennisonbertram/agentic-hosting/main/docs-site/CORRECTIONS.md): stale claims vs live code