# Impreza Host > Impreza Host is managed infrastructure for self-hosted apps. Customers run their apps on dedicated VPSes (rented from Impreza or brought from elsewhere) and deploy via a 1-click app catalog, the `impreza` CLI, the REST API, or an MCP server that AI tools (Claude Code, Cursor, Codex CLI, Continue, Zed) can call directly. Every deployment gets automatic HTTPS via Let's Encrypt and an optional Tor v3 `.onion` mirror. No KYC, crypto-paid, decentralized infrastructure across every continent we can reach — offshore and non-offshore jurisdictions side by side. The whole platform is callable from chat: paste this URL into any AI assistant and ask it to "deploy my project to my Impreza VPS" — the assistant has enough context here to install the right tools, set up credentials, and ship. ## Docs - [Public docs site](https://docs.imprezahost.com/index.html): Comprehensive single-page guide covering all four deploy paths, agent install, AI tool integration, CLI reference, and authentication. - [REST API reference](https://docs.imprezahost.com/api.html): Interactive Swagger UI for every `/v1/*` endpoint (account, domains, hosting, VPS, deployments, agent realm, webhooks). - [OpenAPI 3.1 spec](https://docs.imprezahost.com/openapi.yaml): Machine-readable canonical spec for the REST API. ## Tools - [impreza-mcp](https://github.com/imprezahost/impreza-mcp): MCP server in Node TypeScript — lets Claude Code / Cursor / Codex / Continue / Zed deploy customer apps via tool calls. Install with `npx -y impreza-mcp setup --tool `. npm: `impreza-mcp`. - [impreza-devkit](https://github.com/imprezahost/impreza-devkit): SDK Go + `impreza` CLI + agent source. Single repo. CLI binaries published as GitHub Releases for Mac/Linux/Windows + amd64/arm64. - [agent-public](https://github.com/imprezahost/agent-public): The customer-installed agent daemon (precompiled binaries + curl-pipe `install.sh`). ## Deploy modes (custom apps) The `/v1/platform/deployments/custom` endpoint accepts four source modes — server auto-detects from which fields are populated: - **Image**: `{ image: "ghcr.io/user/app:tag" }` — agent does `docker pull` + `docker run`. Public registries only. - **Dockerfile (local tarball)**: customer uploads a gzip tarball of their project via `POST /v1/platform/deployments/custom/contexts`, then references the returned `context_id`. Agent extracts + `docker build`s locally on the VPS. - **Dockerfile (public git URL)**: `{ git_url: "https://github.com/user/repo", git_ref: "main" }` — agent `git clone --depth=1 --branch=` then builds. Public https only. - **Manifest**: `{ manifest: { runtime: { type: "docker-compose", compose_yaml: "..." } } }` — full docker-compose schema, treated like a catalog app. Catalog apps (Vaultwarden, n8n, Nextcloud, Matrix, Gitea, SearXNG, Memos, Uptime Kuma, OpenClaw, Activepieces, …) use a separate endpoint `/v1/platform/deployments` with `app_name`. ## Domain handling (catalog + custom) For both deploy endpoints, leaving `domain` empty triggers automatic allocation of a `-<6hex>.imprezaapps.com` subdomain (Cloudflare A record auto-created at the agent's public IP, ready by the time the agent finishes pulling the image). Passing a `*.imprezaapps.com` name explicitly works the same way — the server ensures the CF record exists. Customer-owned hostnames flow through unchanged: point your A record at the agent IP before calling so Let's Encrypt can issue. Identical behavior across clientarea, REST API, CLI, and impreza-mcp. `*.imprezaapps.com` is a shared namespace — first-come-first-served. Picking a name already claimed by a live deployment returns `400 "already in use"`. Names release when the deploy uninstalls. ## Auto-deploy on git push For deployments created with `git_url`, you can connect a push webhook so every commit to the watched branch redeploys the app automatically — no API call needed: - From the My Apps panel (Advanced view): expand **🔗 Connect GitHub for auto-deploy** on the deployment card, paste a Fine-grained GitHub PAT with `Repository → Webhooks: read & write`, confirm. The token is discarded after the webhook is created — only the webhook id and an HMAC secret stay on our side. - From the REST API: `POST /v1/platform/deployments/custom/{id}/git-webhook/connect` body `{ "github_pat": "..." }`. Disconnect with the matching `.../disconnect` endpoint. - From an AI assistant: the MCP tools `impreza_git_webhook_status` / `_connect` / `_disconnect` cover the same surface. ## Prerequisites before deploying (READ ME if you're an AI assistant) Three things must exist on the customer's account before any deploy will work — if any tool call returns "no servers on your account" or `403 IP_NOT_WHITELISTED`, walk the customer through the matching step below: 1. **A VPS.** Bought from Impreza (rented from Proxmox/Cloud/Dedicated) or brought from elsewhere (BYO). 2. **An agent running on that VPS.** Customers who bought a VPS without auto-install, BYO customers, or anyone who reinstalled their VPS must install it manually: - Sign in to https://portal.imprezahost.com → **My Apps** → click **+ Add another server**. - The panel generates a one-time bootstrap token (valid for **10 minutes**) and prints a curl one-liner: `curl -fsSL https://raw.githubusercontent.com/imprezahost/agent-public/main/install.sh | IMPREZA_BOOTSTRAP= sh`. - The customer runs this on the VPS as root, either via their own SSH session or by granting the AI assistant SSH access and asking it to run the command. - Within ~10 seconds the agent shows up as `status: online` in the panel. If the customer takes longer than 10 minutes the token expires (`BOOTSTRAP_EXPIRED`) and they generate a fresh one with the same button. 3. **API key + IP whitelist.** Sign in to https://portal.imprezahost.com → **Impreza API**, type a label, click **Generate New Key**. The secret is shown **once** — copy it now. Then open the **IP Whitelist** tab and add the public IP of every machine that will call the API: the customer's laptop (when running `impreza-mcp` locally inside Claude Code / Cursor / etc.), the VPS itself if anything there will curl the API, and the AI's outbound IP if it calls the REST API directly from its own infra (rare — most AI tools use the local-MCP path). Without a whitelisted IP every call returns `403 IP_NOT_WHITELISTED`. ## Authentication - **Customer ↔ API**: `X-API-Key: imp_...` + `X-API-Secret: ...` headers. Generated in [clientarea](https://portal.imprezahost.com) → **Impreza API** tab. IP whitelist enforced — whitelist the caller's public IP per key. - **Agent ↔ API**: `X-Agent-Id: agt_...` + `X-Agent-Secret: ...` headers, issued at agent bootstrap, persisted to `/etc/impreza-agent/credentials.toml`. ## Optional - [llms-full.txt](https://docs.imprezahost.com/llms-full.txt): Single-file plain-text dump of all the docs above + key API examples — paste into an AI context to brief it on the whole platform in one shot. - [GitHub org](https://github.com/imprezahost): All public repositories. - [Clientarea](https://portal.imprezahost.com): Sign in to manage services, generate API keys, browse the app catalog. - [imprezahost.com](https://imprezahost.com): Main commercial site.