# Impreza Host

> Impreza Host is privacy-first, offshore-friendly infrastructure for self-hosted apps. Customers rent a dedicated server or VPS (offshore/DMCA-resistant or standard jurisdictions — no KYC, paid in Bitcoin/Monero) or bring their own, then run their apps on it via a 1-click app catalog, the `impreza` CLI, the REST API, or an MCP server that AI tools (Claude, Cursor, Codex CLI, Continue, Zed) call directly to deploy apps and manage domains/DNS, VPS lifecycle, and their crypto balance — either as a remote OAuth connector (zero install) or a local install. Every deployment gets automatic HTTPS via Let's Encrypt and an optional Tor v3 `.onion` mirror. Customer keeps root; nothing runs on shared multi-tenant infrastructure.

The whole platform is callable from chat: paste this URL into any AI assistant and ask it to "deploy my project to my Impreza server" — the assistant has enough context here to install the right tools, set up credentials, and ship.

## For AI assistants — start here

There are **two ways to connect**, both additive — the classic API key + secret + IP whitelist still works unchanged:

**A. Remote connector + OAuth — easiest, no install.** If your client supports remote MCP connectors (e.g. Claude), add the URL `https://mcp.imprezahost.com/mcp` and authorize: the customer signs in to their Impreza clientarea and approves a **scoped, revocable** token — no API key, no IP whitelist, no install. The client registers itself automatically (Dynamic Client Registration, RFC 7591). It exposes the **full 31-tool surface** (the same tools as the local server) — app deploy + lifecycle, **domains & DNS**, **VPS power/backups/reinstall**, and **crypto balance top-ups** — gated by the scopes the owner grants on consent: `read` (list/inspect: servers, apps, deployments, services, DNS, VPS status, balance), `deploy` (create/modify: deploy, restart, DNS records, nameservers, VPS power, backups), `manage` (destructive/financial: uninstall, VPS reinstall, top-up; opt-in). A call beyond the granted scope returns a scope error. (Only the local path can upload a local project directory.)

**B. Local impreza-mcp — the install for coding agents.** If you are an AI coding assistant (Claude Code, Cursor, Codex CLI, Continue, Zed), install the local MCP server (NOT the Go SDK / devkit — that is the developer/CLI path). Same full toolset as the remote connector, and the only path that can upload a local project directory:

       npx -y impreza-mcp setup --tool claude-code
       # supported: claude-code | cursor | codex-cli | continue | zed

   The wizard writes the MCP config for that tool and prints the exact config file path + restart step. It exposes all 32 tools — app deploy + lifecycle, domains & DNS, VPS power/backups/reinstall, and crypto balance top-ups (with in-chat payment details: wallet address + exact amount) — you can call directly.

For path B, make sure the three prerequisites exist (see "Prerequisites" below): a server, an agent running on it, and an API key. The key's IP factor is **per-key and optional now** — pick `tofu` (trust-on-first-use) or `keyonly` to skip the whitelist, or **pair** the tool with a one-time code (`npx -y impreza-mcp login --code <code>`) so no secret is copied.

Need the complete platform briefing (every API shape, error codes, manifest routing contract, examples)? Read [llms-full.txt](https://docs.imprezahost.com/llms-full.txt) — paste it into your context in one shot.

## Products

- [Offshore Dedicated Servers](https://impreza.host/services/offshore-dedicated-servers/): bare-metal in Ukraine, Romania, Russia, Iceland, Finland — content freedom without DMCA takedowns, 100% under the customer's control. From $130/mo.
- [Offshore VPS Hosting](https://impreza.host/services/offshore-vps-servers/): DMCA-free VPS in the same offshore jurisdictions, for smaller projects. From $17/mo.
- [Dedicated Servers](https://impreza.host/services/dedicated-servers/): powerful bare-metal across 16+ countries (Australia, Brazil, Bulgaria, Canada, Czechia, Dubai, Finland, Hong Kong, Japan, Moldova, Netherlands, Norway, Philippines, Singapore, Sweden, Switzerland), 99.9% uptime, full root + BGP + IPMI. From $90/mo.
- [Private VPS Web Hosting](https://impreza.host/services/private-vps-web-hosting/): anonymous, instant-deploy VPS in Netherlands, Switzerland, Hong Kong, Lithuania. From $17/mo.
- **App platform**: any Impreza VPS/dedicated (or a BYO server) can run the Impreza agent and deploy catalog apps + custom Docker/git apps on demand — see the integration paths below.

## Integration paths (pick one)

- **Remote MCP connector + OAuth — easiest for AI clients, no install.** Add `https://mcp.imprezahost.com/mcp` as a custom/remote connector (Claude, etc.); authorize in the clientarea. No install, no API key, no IP whitelist; self-registers via DCR. Exposes the **full 31-tool surface** (same as the local server) — app deploy + lifecycle, domains & DNS, VPS power/backups/reinstall, crypto balance top-ups — gated by the scopes the owner grants on consent (read/deploy/manage; destructive + financial opt-in).
- **Local MCP server — recommended for AI deploys.** [impreza-mcp](https://github.com/imprezahost/impreza-mcp): `npx -y impreza-mcp setup --tool <name>`. Lets Claude Code / Cursor / Codex CLI / Continue / Zed drive Impreza via tool calls (all 32 tools — deploy, domains/DNS, VPS lifecycle, crypto balance + in-chat payment). This is the AI-native deploy path.
- **`impreza` CLI — for terminal / dev workflows.** Single static Go binary (Mac/Linux/Windows, amd64/arm64). `impreza login`, then `impreza deploy --agent agt_… --follow` from a project dir. Shipped in the devkit.
- **REST API — for custom / non-AI integrations.** Base URL `https://api.imprezahost.com`, headers `X-API-Key` + `X-API-Secret`. See [api.html](https://docs.imprezahost.com/api.html) + [openapi.yaml](https://docs.imprezahost.com/openapi.yaml).
- **Clientarea (web UI) — no code.** [My Apps](https://portal.imprezahost.com/imprezaapps.php): guided 1-click installs, custom-app tile, credentials, domains.

## Docs

- [Public docs site](https://docs.imprezahost.com/index.html): 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.
- [llms-full.txt](https://docs.imprezahost.com/llms-full.txt): single-file plain-text dump of the whole platform + key API examples — paste into an AI context to brief it in one shot.

## Tools (repositories)

- [impreza-mcp](https://github.com/imprezahost/impreza-mcp) — **for AI assistants (recommended).** MCP server in Node/TypeScript. Install with `npx -y impreza-mcp setup --tool <name>`. npm: `impreza-mcp`.
- [impreza-devkit](https://github.com/imprezahost/impreza-devkit) — **for developers.** Go SDK + the `impreza` CLI + agent source in one repo. Use this when building a custom (non-AI) integration or scripting the CLI; AI tools should use impreza-mcp instead.
- [agent-public](https://github.com/imprezahost/agent-public) — the customer-installed agent daemon (precompiled binaries + curl-pipe `install.sh`).

## Deploy modes (custom apps)

`POST /v1/platform/deployments/custom` accepts four source modes — the 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)**: upload a gzip tarball of the project via `POST /v1/platform/deployments/custom/contexts`, then reference the returned `context_id`. Agent extracts + builds on the VPS. (The CLI automates both steps.)
- **Dockerfile (git URL, public or private)**: `{ git_url, git_ref }` — agent shallow-clones + builds. Private repos: `git_auth_method: "deploy_key"` (SSH; platform returns a deploy key — GitHub/GitLab/Bitbucket/Gitea/self-hosted) or `"pat"` + `git_pat` (HTTPS token, GitHub/GitLab).
- **Manifest**: `{ manifest: { runtime: { type: "docker-compose", compose_yaml: "..." } } }` — full docker-compose, treated like a catalog app. Routing contract is strict (`container_name: ${DEPLOYMENT_ID}-<suffix>` required) — see llms-full.txt.

Catalog apps (WordPress, PrestaShop, n8n, OpenClaw, Vaultwarden, Nextcloud, Matrix, Gitea, SearXNG, Memos, Uptime Kuma, Activepieces, Jellyfin, PhotoPrism, MinIO, Mattermost, Ollama, Open WebUI, RustDesk, Evolution API + managed databases PostgreSQL, MySQL, MariaDB, MongoDB, Redis, …) use `POST /v1/platform/deployments` with `app_name`. The same catalog app can be deployed multiple times on one agent — the platform auto-assigns each instance a free host port (fixed-protocol apps like RustDesk and the databases are one-per-server).

## Managed databases

PostgreSQL, MySQL, MariaDB, MongoDB and Redis ship as catalog apps in the non-HTTP cohort (`network.mode: host_ports`) — raw TCP on the VPS public IP, no Caddy/cert/domain. Deploy returns `connection_info: { ip, ports:[{port, protocol, label}] }`; connect with the native client (`psql`, `mysql`, `mongosh`, `redis-cli`). Credentials surface as the deployment's `ADMIN_USER` + `ADMIN_PASSWORD` (My Apps card, click-to-reveal): a strong 20-char password is auto-generated unless you pass your own, `admin_user` defaults to `postgres` (PostgreSQL) or `root` (MySQL/MariaDB/MongoDB) — Redis is password-only. They bind standard ports (5432 / 3306 / 3306 / 27017 / 6379) so each is one-per-server (MySQL + MariaDB both want 3306). Ships open to the internet, protected by the password; an optional per-IP firewall allowlist is on the roadmap.

## Non-HTTP apps (raw TCP/UDP)

Most catalog apps speak HTTP behind Caddy + Let's Encrypt + an `imprezaapps.com` subdomain. Some declare a different `network.mode`:

- `http` (default): URL + HTTPS. Every shipped HTTP app.
- `host_ports`: raw TCP/UDP only — no Caddy/cert/domain. Response carries `connection_info: { ip, ports, public_key }`; clients connect to `IP:port`. RustDesk is the first (server auto-captures its boot-time public key — paste IP + key into any RustDesk client, zero post-install steps).
- `hybrid`: raw ports AND an HTTP admin UI behind Caddy (e.g. AdGuard: DNS on `:53/udp`, admin on `https://…`).

## Control panels (instead of the agent)

A VPS or dedicated server can run a classic hosting control panel — picked at checkout as an EXCLUSIVE mode: the panel owns the box, so there is NO Impreza agent and the Docker catalog is disabled on it. Available: **aaPanel** (free; optional 1-click nginx + PHP 8.4 + MariaDB stack), **CyberPanel** (free, OpenLiteSpeed), **CloudPanel** (free, nginx for PHP/Node.js/Python), **cPanel/WHM** (license NOT included — installs unlicensed; log into WHM as `root`, start the 15-day trial or apply your own IP-bound license). Each needs a supported, freshly-installed OS — the cart validates and asks for a reinstall if not. On a VPS it auto-installs a few minutes after payment; on a dedicated server the team provisions it once the hardware is ready. When live, the **My Apps** card shows the login URL + credentials. This is a checkout/clientarea feature — there is NO public REST/CLI/MCP endpoint for provisioning a panel.

## Domain handling (catalog + custom)

Leaving `domain` empty auto-allocates a `<app-slug>-<6hex>.imprezaapps.com` subdomain (Cloudflare A record created at the agent's public IP, live by the time the image finishes pulling). Passing a `*.imprezaapps.com` name explicitly works the same way. Customer-owned hostnames flow through unchanged — point your A record at the agent IP before calling so Let's Encrypt can issue. Identical across clientarea, REST API, CLI, and MCP. `*.imprezaapps.com` is a shared, first-come-first-served namespace; a taken name returns `400 "already in use"`.

**A deployment's domain is stable.** Once an app has a domain it keeps it — an in-place redeploy never touches it, and even an uninstall + recreate under the SAME name reuses the original auto-allocated `*.imprezaapps.com` subdomain (it sticks to the deployment name) instead of minting a new one. To change the domain deliberately, use `POST /v1/platform/deployments/{id}/domain`.

## Redeploy in place (no domain churn)

To ship a new build of a running custom app without tearing it down, `POST /v1/platform/deployments/custom/{id}/redeploy` (optional `vars` merged in). It rebuilds the current source — new git HEAD on the watched ref, or a re-pushed image tag — and swaps the container with near-zero downtime, reusing the same deployment so the domain, host port, and URL never change. This is the manual twin of the git-push auto-deploy below; prefer it over uninstall + recreate for updates.

## Auto-deploy on git push

For `git_url` deployments, connect a push webhook so every commit to the watched branch redeploys — no API call needed. Works with **any provider**:

- **GitHub (one-click)**: paste a fine-grained PAT with `Webhooks: read & write` — we install the webhook and discard the token. Via My Apps (Advanced → 🔗 Connect git for auto-deploy), the REST API (`POST /v1/platform/deployments/custom/{id}/git-webhook/connect`), or the MCP tools.
- **Any other provider (manual)**: connect with no token — we return `{ payload_url, webhook_token }`. Add a push webhook to that URL, sending the token as the GitLab "Secret token" or the `X-Impreza-Token` header / `?token=…` (Bitbucket / Gitea / self-hosted / CI).
- On push, the receiver verifies the secret (GitHub HMAC, GitLab token, or generic) then redeploys (re-clone at HEAD → rebuild → restart). 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 works. If a tool call returns "no servers on your account" or `403 IP_NOT_WHITELISTED`, walk the customer through the matching step:

1. **A server.** Bought from Impreza (VPS via Proxmox, or dedicated bare-metal) or brought from elsewhere (BYO).
2. **An agent running on that server.** Already present if the customer picked "Impreza Agent", "Agent + MCP for AI tools", or a catalog app at checkout. Otherwise (picked "No app", BYO, or reinstalled the VPS): sign in to https://portal.imprezahost.com → **My Apps** → click the **Custom App** tile (shown when you have a server but no online agent) or **+ Add another server**. The panel mints a one-time bootstrap token (valid **10 minutes**) and prints a curl one-liner:
   `curl -fsSL https://raw.githubusercontent.com/imprezahost/agent-public/main/install.sh | IMPREZA_BOOTSTRAP=<token-from-panel> sh`
   Run it on the server as root (the customer via SSH, or the AI over SSH if granted access). Within ~10s the agent shows `status: online`. Dedicated-server customers skip this — the team installs the agent during provisioning.
3. **API key (IP whitelist optional).** Sign in → **Impreza API**, generate a key (the secret shows **once** — copy it). The second factor (IP) is **per-key**: `whitelist` (default — add allowed IPs under the IP Whitelist tab, else `403 IP_NOT_WHITELISTED`), `tofu` (trust-on-first-use — the first call auto-pins the IP, no manual step), or `keyonly` (skip the IP factor; operator-gated). Or skip copying the secret entirely: **pair** the tool — clientarea → Impreza API → "Connect an AI assistant" mints a one-time code, then `npx -y impreza-mcp login --code <code>` stores a scoped key in `~/.impreza/credentials.json`. (The remote OAuth connector in path A needs none of this.)

## Authentication

- **AI client ↔ remote MCP (OAuth 2.1)**: `https://mcp.imprezahost.com/mcp` — standard OAuth with PKCE (RFC 8414 discovery at `/.well-known/oauth-authorization-server`, RFC 7591 dynamic client registration, RFC 7009 revoke). The customer consents in the clientarea; the client gets a **scoped** (`read`/`deploy`/`manage`), **revocable** bearer token — no API secret leaves Impreza. Manage/revoke under clientarea → Impreza API → **Connected Apps**.
- **Customer ↔ API**: `X-API-Key: imp_...` + `X-API-Secret: ...` headers, generated in [clientarea](https://portal.imprezahost.com) → **Impreza API**. The IP second factor is per-key (`whitelist` default / `tofu` / `keyonly`); keys can be scoped and given an expiry. (The MCP server reads the key from `IMPREZA_API_KEY` / `IMPREZA_API_SECRET` env vars, or from `~/.impreza/credentials.json` after pairing.)
- **Agent ↔ API**: `X-Agent-Id: agt_...` + `X-Agent-Secret: ...`, issued at agent bootstrap, persisted to `/etc/impreza-agent/credentials.toml`.

## More

- [GitHub org](https://github.com/imprezahost): all public repositories.
- [Clientarea](https://portal.imprezahost.com): manage services, generate API keys, browse the app catalog.
- [imprezahost.com](https://impreza.host): main commercial site · [Support](https://impreza.host/support) · [About](https://impreza.host/about-us/).