Find the next step for your application. Follow a guide, look up a tool or troubleshoot an operation on your own server.

Try private Git agent updates php_composer

Platform overview and existing reference

Concepts, setup steps, deployment examples and integration details.

What is Impreza Host

Impreza Host runs your apps on dedicated VPSes you own — not shared multi-tenant hosting and not opaque managed-cloud. You get:

A real VPS with root access. Use it for the apps Impreza deploys + anything else.
A daemon (the agent) we install on your VPS that takes app-deploy commands from the control plane.
A REST API + CLI + MCP server for issuing those commands from your laptop, your CI, or your favorite AI.
Automatic HTTPS via Let’s Encrypt + optional Tor v3 hidden services for any deployment.
No KYC, crypto payment accepted, decentralized infrastructure across every continent we can reach — offshore and non-offshore jurisdictions side by side.

Quickstart (60 seconds)

Path A — From an AI tool (Claude Code, Cursor, Codex, Continue, Zed)

Prefer zero install? Add https://mcp.imprezahost.com/mcp as a remote connector in Claude or Codex CLI and authorize — OAuth, no key, full deploy power (see AI tools (MCP)). The steps below are the local install, needed only to upload a project folder straight from your machine.

Generate an API key + secret in the Impreza clientarea. Pick an IP mode — or pair with a code so there’s no secret to copy.

Get the MCP config snippet for your AI tool:

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

Paste the printed JSON into your AI tool’s MCP config, fill in IMPREZA_API_KEY and IMPREZA_API_SECRET, restart the tool. Then in chat:

You: "Deploy this project to my Impreza VPS, expose via .onion."
AI: → calls impreza_deploy_custom → tarballs cwd → uploads →
       creates a deployment → prints the URL.

Path B — From the terminal

# One-time setup
npm i -g impreza-mcp     # or use directly via npx
# (the CLI ships as a single static binary — see GitHub Releases of impreza-devkit)
impreza login            # prompts for API key + secret, verifies against /v1/account

# Per-project
cd ~/my-app              # any directory with a Dockerfile
impreza deploy --agent agt_xxxxxxxxxxxx --follow
# → Packaging → Uploading → Deploying → ✓ Deployed at https://my-app-3f7c9a.imprezaapps.com

Don’t have an agent yet? Three steps in order: Get a VPS → Install the agent (10-min token from My Apps → + Add another server) → Generate API keys (IP whitelist optional). ~5 minutes total.

Got “no servers on your account” from the AI? It means you have a VPS but the agent isn’t installed yet. Open My Apps, click + Add another server, copy the curl one-liner, run it on the VPS within 10 minutes (full flow here). The token expires after 10 min — regenerate if you miss the window.

Concepts

Term	Means
VPS / server	A virtual machine you own (rented from Impreza, or your own external box). Has a public IP + root access.
Agent	A small Go daemon installed on the VPS. Polls the Impreza control plane for deploy commands + reports back. ID format `agt_xxxxxxxxxxxx`.
Catalog	A curated set of apps we’ve packaged + verified — WordPress, PrestaShop, n8n, OpenClaw, Vaultwarden, Nextcloud, Matrix, Gitea, SearXNG, Memos, Uptime Kuma, Activepieces, Jellyfin, PhotoPrism, MinIO, Mattermost, Open WebUI, RustDesk, Evolution API, plus managed databases (PostgreSQL, MySQL, MariaDB, MongoDB, Redis), …
Network mode	How a deployment is reached. `http` (default) → URL with HTTPS via Caddy + Let’s Encrypt; the app’s own port stays on the server’s loopback, so a bare IP is refused as the domain. This is every app except the ones in the next two modes. `host_ports` → raw TCP/UDP on fixed ports (RustDesk, future game/VPN/DNS); the deployment carries `connection_info: {ip, ports, public_key}` and clients connect to `IP:port`. `hybrid` → both at once (raw protocol ports AND an HTTP admin UI on a subdomain).
Custom deploy	An app that’s not in the catalog — your own code, an arbitrary public image, or a manifest you wrote.
Deployment	One running instance of an app on one agent. ID format `dpl_xxxxxxxxxxxx`. Tracks its container(s), routes, status.
Source mode	How a custom deploy gets its code: `image` (public registry URL), `dockerfile` (local Dockerfile uploaded as a tarball, OR a git URL — public or private), or `manifest` (full docker-compose YAML).
Route / domain	The public hostname the app responds on. Auto-allocated under `imprezaapps.com` if you don’t bring your own (shared namespace — names are first-come-first-served, released on uninstall).
Onion / .onion	Optional Tor v3 hidden service published alongside any deployment. Set `onion: true`.

1. Get a server

Impreza apps need a server to run on. Three ways to get one:

Buy a VPS from Impreza

Provisioned in ~3 minutes via the Proxmox panel. Multiple continents available — pick offshore or non-offshore based on your needs. See plans →

Buy a dedicated server from Impreza

Bare-metal hardware in our datacenters. Provisioning is manual (24–48h while we rack the box). Our team installs the Impreza agent on your behalf — when the server arrives in your client area, it’s ready to deploy to from My Apps. Dedicated servers → · Offshore dedicated →

Bring your own (BYO)

Already have a server elsewhere? Any Debian / Ubuntu / RHEL / Alpine works. Install the agent (next section) and we treat it like any other.

At checkout: pick what to install

When you order a VPS or a dedicated server from Impreza, the cart shows a tile picker. Pick whichever matches your intent — what you choose decides what runs on the box. The first three install the Impreza agent (the difference is what, if anything, runs alongside it); the last two do not:

Impreza Agent (recommended for power users): just the agent. Use this if you plan to deploy your own apps later — your own Docker images, git repos, manifests, or anything from the catalog via the panel / CLI / API.
Agent + MCP for AI tools (recommended for AI-first workflows): same as above, but the post-provision email includes a 3-step MCP quickstart so Claude / Cursor / Codex / Continue / Zed can deploy directly to your server via tool calls.
One of the catalog apps (WordPress, PrestaShop, n8n, Nextcloud, OpenClaw, Vaultwarden, Gitea, RustDesk, …): agent plus that specific app, auto-installed. HTTP apps land at a free imprezaapps.com subdomain with HTTPS; non-HTTP apps like RustDesk (self-hosted remote desktop) land at IP:port with the connection info (including the auto-captured public key) shown on the My Apps card. Fastest path if you know exactly which app you want.
No app: bare server, agent not installed. You can install it later from My Apps → click the Custom App tile (which only appears when you have no agent yet).
A control panel (aaPanel, CyberPanel, CloudPanel, or cPanel/WHM): the panel takes over the whole server — no Impreza agent and no Docker app catalog. Choose this for a classic hosting control panel instead of the agent-managed workflow. See Control panels below.

For dedicated servers the same picker shows the same options; the only difference is timing — our team installs whatever you picked manually after the hardware is racked, then the agent shows up in your My Apps panel as if it were a VPS.

Control panels (instead of the agent)

Prefer a classic hosting control panel over the agent + Docker workflow? Pick one at checkout and it takes over the whole server — you manage sites, databases, email, DNS and SSL from the panel's own UI. This is an exclusive mode: a control-panel server runs no Impreza agent, and the Docker app catalog is disabled on it.

aaPanel — free, lightweight; optional one-click web stack (nginx + PHP 8.4 + MariaDB) at install time, or add components later from the panel store.
CyberPanel — free, OpenLiteSpeed-based (LSCache, one-click WordPress, PHP, MariaDB, DNS, email, SSL).
CloudPanel — free, modern nginx panel for PHP, Node.js and Python sites with free SSL.
cPanel/WHM — license not included: we install it, then you log in to WHM as root and either start the free 15-day trial or apply your own cPanel license (purchased separately and bound to the server's IP).

Each panel needs a supported, freshly-installed OS — the cart checks this for you and, if your server's OS isn't compatible, asks you to reinstall it with a supported one first. On a VPS the panel installs automatically a few minutes after payment; on a dedicated server our team provisions it once the hardware is ready.

When it's ready, the panel appears on your My Apps page with its login URL and credentials — username plus a click-to-reveal password. For cPanel/WHM there's no separate password: you log in to WHM with your server's root account.

2. Install the agent

Every Impreza deployment runs on an agent — a small daemon installed on the VPS that takes commands from the control plane and runs them locally via docker compose. Without an agent, nothing can be installed — the AI, the CLI, and the REST API will all return “no server found on this account”.

When do I need this?

You bought a VPS from Impreza and did not opt into auto-install during checkout.
You brought your own server from another provider (BYO).
You reinstalled an Impreza VPS and the previous agent was wiped.

If you bought a VPS from Impreza and selected auto-install, the agent is already on the VPS by the time you reach the panel — skip to step 3 (API keys).

The 4-step install flow

Sign in to portal.imprezahost.com and open My Apps.
Click + Add another server. The panel generates a one-time bootstrap token (valid for 10 minutes) and prints a one-liner that looks like this:
```
curl -fsSL https://raw.githubusercontent.com/imprezahost/agent-public/main/install.sh \
  | IMPREZA_BOOTSTRAP=<token-from-panel> sh
```
Run that command on the VPS as root (or via sudo). Two paths:
- You do it: SSH into the VPS, paste, hit enter.
- The AI does it: grant the AI assistant SSH access (give it the hostname / IP / port / user / credentials) and paste the one-liner into the chat. The AI runs it on your behalf.
Within ~10 seconds the agent appears in My Apps with status: online. You’re ready to deploy.

The bootstrap token expires in 10 minutes. If you can’t get to the VPS shell in that window, the curl command will fail with BOOTSTRAP_EXPIRED. Just click + Add another server again to generate a fresh one.

What the install script does on your VPS:

Detects OS + architecture (amd64 / arm64).
Installs Docker engine if missing (the agent uses docker compose for every deployment).
Installs git if missing (used for git-URL deploys).
Downloads the agent binary to /usr/local/bin/impreza-agent.
Installs the systemd unit + hardening (ProtectHome=yes, NoNewPrivileges, …).
Consumes the bootstrap token, receives the agent’s permanent credentials, persists them to /etc/impreza-agent/credentials.toml (mode 0600).
Starts the impreza-agent.service systemd unit.

Keep your agent up to date

Existing servers update only when you choose. Follow the agent update guide to check versions, apply an update while deployments are idle and confirm the next heartbeat. The portal and MCP server listing provide the update command.

3. Generate API keys (IP whitelist now optional)

The AI assistant, the CLI, and any custom integration all authenticate to Impreza with an API key + secret. The agent uses a different credential issued at bootstrap (above) — these steps are for customer-realm calls (the ones your laptop, your AI, your CI make).

Generate the key

Sign in to portal.imprezahost.com and open Impreza API.
Type a label (something like laptop, ci, or claude) and click Generate New Key.
Copy the secret immediately. The full secret is shown once — if you close the modal you can’t retrieve it again, you’ll have to delete + recreate. The imp_… key prefix stays visible.

Choose the key’s IP mode (the 403 is now opt-out)

When you generate a key you pick how its second factor (IP) behaves — per key:

Whitelist (default) — you add the allowed public IP(s) on the IP Whitelist tab; calls from anywhere else get 403 IP_NOT_WHITELISTED. Add your laptop’s IP (running the impreza CLI or the local impreza-mcp), a VPS IP (only if it curls the API), or rarely the AI provider’s outbound IP. Tip: curl https://api.ipify.org, or click Add my current IP.
Trust on first use — the first successful call auto-pins that IP; later calls must match. No manual whitelist step. Reset the binding to re-pin from a new location.
Key only — skips the IP factor entirely (key + secret alone authenticate). For dynamic-egress callers like CI. (Availability is set by the operator.)

Pick Trust on first use or Key only and there’s no whitelist step at all. The classic Whitelist mode is unchanged, so existing keys keep working exactly as before.

Pair instead of paste (no secret to copy)

Don’t want to copy a secret into a config file? In Impreza API → Connect an AI assistant, pick what the assistant may do (read / deploy / manage) and generate a one-time pairing code. Then on the tool’s machine:

npx -y impreza-mcp login --code <code-from-clientarea>

The CLI exchanges the code for a key stored in ~/.impreza/credentials.json (mode 0600) — the secret is never printed, and the MCP server reads it automatically.

Why per-IP / per-scope?

Defense in depth. A leaked API secret is far less useful to an attacker if it’s also bound to an IP you added (or limited to a read-only scope). Pair that with fast rotation (generate a fresh key + delete the old one) and a compromised credential is recoverable without losing data. Prefer no credentials at all? Use the remote OAuth connector.

4. Deploy apps

Four ways to get code running:

Catalog (1-click)

Browse the curated app catalog in the My Apps panel and click Install. Pick a server, pick a domain (or use a free imprezaapps.com subdomain), confirm. Done in ~30 seconds.

Same operation via API:

curl -X POST https://api.imprezahost.com/v1/platform/deployments \
  -H "X-API-Key: imp_..." -H "X-API-Secret: ..." \
  -H "Content-Type: application/json" \
  -d '{
    "app_name": "vaultwarden",
    "agent_id": "agt_xxxxxxxxxxxx",
    "domain": "vault.example.com",
    "onion": true,
    "vars": {"signups_allowed": "true"}
  }'

Deploy the same app multiple times on one server — Impreza assigns each instance its own host port automatically, so they run side by side without conflict. (Fixed-protocol apps like RustDesk are the exception — one per server.)

Public Docker image

Run any image from a public registry (Docker Hub, ghcr.io public, quay.io, …):

curl -X POST https://api.imprezahost.com/v1/platform/deployments/custom \
  -H "X-API-Key: imp_..." -H "X-API-Secret: ..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-nginx",
    "agent_id": "agt_xxxxxxxxxxxx",
    "image": "nginx:alpine",
    "target_port": 80,
    "domain": "static.example.com",
    "cpus": 0.5,
    "memory_mb": 256
  }'

Local Dockerfile (upload from your machine)

For code that lives on your laptop. The CLI tars the project directory, uploads it, and asks the agent to docker build it locally on your VPS:

cd ~/my-app                    # directory with a Dockerfile
impreza deploy \
  --agent agt_xxxxxxxxxxxx \
  --name my-app \
  --cpus 1.0 --memory-mb 512 \
  --follow

Same operation via API (two-step: upload context, then deploy):

# 1. Upload the project as a gzip tarball
tar czf - . | curl -X POST https://api.imprezahost.com/v1/platform/deployments/custom/contexts \
  -H "X-API-Key: imp_..." -H "X-API-Secret: ..." \
  -H "Content-Type: application/gzip" \
  --data-binary @-
# → returns {context_id, sha256, expires_at}

# 2. Reference that context_id in a deploy
curl -X POST https://api.imprezahost.com/v1/platform/deployments/custom \
  -H "X-API-Key: imp_..." -H "X-API-Secret: ..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-app",
    "agent_id": "agt_xxxxxxxxxxxx",
    "context_id": "ctx_xxxxxxxxxxxx",
    "dockerfile_path": "Dockerfile",
    "target_port": 8080,
    "cpus": 1.0,
    "memory_mb": 512
  }'

Git repository (public or private)

Team permissions in the browser panel explain service access, app management and operations reserved for the account owner.

From the portal: in Advanced view, open App catalog → Deploy a custom app → Git repository. Set the HTTPS URL, branch/tag, Dockerfile path and container port. Deploy PHP with Composer · Deploy Python with pip · Require a healthy start · Node health checks · Public build variables · Apps in project subfolders · Static npm sites · Node.js without a Dockerfile · Analyze project configuration · Step-by-step Git deployment guide · Preview settings and variable isolation. Private github.com/gitlab.com repositories accept a read-only personal access token in the same form. For SSH, choose Private — SSH deploy key, use the SSH clone URL, then copy the generated public key from the app card Git connection into your repository’s read-only Deploy keys. After the first attempt finishes, redeploy.

Point at a git URL — the agent does a shallow clone (git clone --depth=1 --branch=<ref>) and builds the Dockerfile from the cloned tree. No local upload needed. Public repos need no auth; for private repos set git_auth_method (see the note below):

curl -X POST https://api.imprezahost.com/v1/platform/deployments/custom \
  -H "X-API-Key: imp_..." -H "X-API-Secret: ..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-app",
    "agent_id": "agt_xxxxxxxxxxxx",
    "git_url": "https://github.com/your-user/your-repo",
    "git_ref": "main",
    "dockerfile_path": "Dockerfile",
    "target_port": 8080,
    "cpus": 1.0,
    "memory_mb": 512
  }'

Private repositories are supported — set git_auth_method:

deploy_key — use an SSH URL (git@host:owner/repo.git). The create response returns a generated git_auth.public_key; add it to your repository as a read-only Deploy Key (GitHub / GitLab / Gitea) or Access Key (Bitbucket), and the agent clones over SSH. Works with any host that supports SSH deploy keys — GitHub, GitLab, Bitbucket, Gitea or self-hosted.
pat — keep the https URL and pass git_pat (a repo-scoped read token: a GitHub fine-grained PAT or a GitLab access token). The agent clones over HTTPS. Supported for GitHub and GitLab; for Bitbucket, use a deploy key instead.

The credential is encrypted at rest and never returned again. Public repos on any host need no auth (git_auth_method defaults to none).

Inspect an upload and save a plan

Inspect uploaded project files, save the final configuration for review and apply it with safe retries through My Apps or MCP. Project plans, configuration review and safe retries.

Upload and reuse source versions

Upload an archive from My Apps or a local folder through MCP, then select immutable source versions for creation and redeploy. Reuse the current archive or choose another version while keeping the app identity and build recipe. Upload, retention and redeploy guide.

Import a Compose stack

Paste or select a Compose file in the custom-app form, review its services and variables, and choose the HTTP service for your domain. Public images, private service networks and deployment-specific named volumes are supported. MCP uses impreza_prepare_compose followed by impreza_deploy_custom with mode: "compose". Supported configuration, review and deployment guide.

Runtime health and deployment results: agent 0.6.4 reports recent container health separately from the last operation. Missing, old or disconnected observations remain unknown.

Cancel a deployment: stop queued work or request cancellation before container replacement; distinguish request from agent confirmation.

Deployment progress and agent restarts: read the last reported step, recover saved results, wait for supervised preparation or replacement after an agent restart and reconcile verified outcomes without executing a deploy again.

Deployment preparation safety

Available with agent 0.6.0 and later: the updated executor prepares images before replacement and can automatically restore a previously healthy version after startup failure. Portal deployment history and the deployment API show the failed attempt and its recovery separately. Existing installations can follow the agent update guide; it is not a zero-downtime or database rollback guarantee. History, recovery limits and integration tests.

Auto-deploy on git push

Once a deployment is created with git_url, you can connect its repo’s push webhook so every commit to the watched branch redeploys the app automatically — no extra command, no polling. It works with any provider (GitHub, GitLab, Bitbucket, Gitea, self-hosted, even a CI job) against a single per-deployment secret. Enable it from the My Apps panel (Advanced view → 🔗 Connect git for auto-deploy), an AI assistant (impreza_git_webhook_connect / _status / _disconnect), or the REST API.

GitHub — one-click. Paste a Fine-grained GitHub PAT and we install the webhook for you:

curl -X POST https://api.imprezahost.com/v1/platform/deployments/custom/dpl_xxxxxxxxxxxx/git-webhook/connect \
  -H "X-API-Key: imp_..." -H "X-API-Secret: ..." \
  -H "Content-Type: application/json" \
  -d '{"github_pat": "github_pat_..."}'

GitLab, Bitbucket, Gitea, self-hosted, CI — manual. Connect with no token; we return a payload_url and a webhook_token. Add a push webhook in your repo to that URL, sending the token as the GitLab Secret token, or as the X-Impreza-Token header / ?token=… query param for everything else:

curl -X POST https://api.imprezahost.com/v1/platform/deployments/custom/dpl_xxxxxxxxxxxx/git-webhook/connect \
  -H "X-API-Key: imp_..." -H "X-API-Secret: ..." \
  -H "Content-Type: application/json" -d '{}'
# → { "payload_url": "https://api.imprezahost.com/v1/webhooks/git/dpl_xxxxxxxxxxxx",
#     "webhook_token": "…" }   ← add both to your provider's webhook settings

Generate the PAT at github.com/settings/personal-access-tokens/new with scope Repository → Webhooks: Read and write on the target repo (and nothing else). We validate the token, install the webhook, then discard it — we only keep the webhook id (to delete later) and a fresh per-deployment HMAC secret (to verify incoming push payloads). Pushes get redeployed via the same smart-replace path used by every redeploy: re-clone at the new HEAD, rebuild, restart in place.

Disconnect works the same way — with a PAT supplied we also delete the hook from your repo on GitHub’s side; without it, we only flip our local switch and pushes 200-noop on our receiver. GitHub eventually marks the hook as failing in its UI either way.

AI tools (MCP)

Impreza speaks MCP (Model Context Protocol), so AI tools can call it directly — no copy-pasting URLs, no leaving the chat. There are two ways to connect, both additive (the classic key + secret + whitelist still works unchanged).

Easiest — remote connector + OAuth (no install)

If your AI client supports remote MCP connectors (e.g. Claude), add this URL as a custom connector and click Authorize — you sign in to your clientarea and approve a scoped, revocable token. No install, no API key, no IP whitelist.

https://mcp.imprezahost.com/mcp

The client registers itself automatically and can reach the full toolset — app deploy + lifecycle, domains & DNS, VPS power/backups/reinstall, and crypto balance top-ups. What it's allowed to do is gated by the scopes you grant on the consent screen (read / deploy / manage; destructive + financial actions opt-in). Manage or revoke connected apps under clientarea → Impreza API → Connected Apps.

For coding agents — local `impreza-mcp`

For coding agents (Claude Code, Cursor, Codex CLI, Continue, Zed), install the local impreza-mcp server. Loaded once into your AI tool, the AI gains the full toolset it can call autonomously (and it can upload a local project folder, which the hosted connector can't):

Tool	Does
Apps & deployments
`impreza_list_servers`	List the customer’s VPSes + agents
`impreza_list_apps`	Browse the catalog
`impreza_list_deployments`	What’s currently running
`impreza_deploy_custom`	Deploy code from cwd (image / dockerfile / manifest)
`impreza_deploy_catalog_app`	Install a catalog app
`impreza_uninstall_deployment`	Tear down a deployment
`impreza_restart_deployment`	Restart a deployment’s containers
`impreza_redeploy_deployment`	Rebuild a custom deployment in place (domain + URL preserved)
`impreza_get_logs`	Tail the last N lines of container logs
`impreza_change_domain`	Re-route a running deployment to a new hostname
`impreza_add_onion`	Provision a Tor mirror for an existing deployment
`impreza_git_webhook_status`	Inspect the auto-deploy connection of a git-backed deployment
`impreza_git_webhook_connect`	Install a GitHub push webhook so every commit auto-redeploys
`impreza_git_webhook_disconnect`	Disable auto-deploy (optionally also delete the hook on GitHub)
Account & balance
`impreza_account_info`	Profile, account status, currency + current balance
`impreza_list_services`	List billable services (VPS / hosting / domains) + their IDs
`impreza_topup`	Create a balance top-up invoice in BTC / XMR / USDT / TRX
`impreza_topup_status`	Poll a top-up invoice until it’s paid
`impreza_topup_payment`	Wallet address + exact crypto amount to pay a top-up
Domains & DNS
`impreza_domain_check`	Check availability + price for one or more domains
`impreza_domain_details`	Status, expiry, nameservers, registrar-lock state
`impreza_list_dns`	List a domain’s DNS records
`impreza_add_dns_record`	Add an A / AAAA / CNAME / MX / TXT / … record
`impreza_update_dns_record`	Change an existing DNS record
`impreza_delete_dns_record`	Remove a DNS record
`impreza_set_nameservers`	Replace a domain’s authoritative nameservers
VPS lifecycle (Proxmox)
`impreza_vps_status`	Power state + live CPU / memory / disk / uptime
`impreza_vps_list_backups`	List available backups
`impreza_vps_list_templates`	List OS templates (to pick one for reinstall)
`impreza_vps_power`	Start / shutdown / reboot / stop
`impreza_vps_create_backup`	Trigger an on-demand backup
`impreza_vps_reinstall`	Wipe + reinstall from an OS template (erases all data)

Setup (one command)

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

The wizard prints the ready-to-paste JSON config block + the exact file path for the target tool (e.g. ~/Library/Application Support/Claude/claude_desktop_config.json on macOS). Paste, fill in IMPREZA_API_KEY + IMPREZA_API_SECRET, restart the AI tool.

Manual config for JSON clients

For Codex CLI configuration in TOML and remote OAuth setup, follow Connect an AI tool. The JSON example below is for clients that use mcpServers.

{
  "mcpServers": {
    "impreza": {
      "command": "npx",
      "args": ["-y", "impreza-mcp"],
      "env": {
        "IMPREZA_API_KEY": "imp_...",
        "IMPREZA_API_SECRET": "..."
      }
    }
  }
}

Source: github.com/imprezahost/impreza-mcp · npm: impreza-mcp

CLI `impreza`

Single static binary in Go. Mac (amd64/arm64), Linux (amd64/arm64), Windows (amd64).

# Setup (one-time)
impreza login

# Deploy your project (Dockerfile in cwd)
impreza deploy --agent agt_xxxxxxxxxxxx --follow

# Re-deploy with the same name (uninstalls old + creates new)
impreza deploy --agent agt_xxxxxxxxxxxx --name my-app --follow --force

# Browse + manage
impreza platform servers list
impreza platform apps list
impreza platform deployments list
impreza platform deployments show dpl_xxxxxxxxxxxx
impreza platform deployments logs dpl_xxxxxxxxxxxx
impreza platform deploy vaultwarden --agent agt_... --domain vault.example.com

# Multiple accounts? Named contexts.
impreza context create work --key imp_... --secret ...
impreza context use work

Source: github.com/imprezahost/impreza-devkit (cli-go/). Releases publish prebuilt binaries.

REST API

Every Impreza Host operation has a REST endpoint. Use it directly with curl, the SDK Go, or the official Python impreza-sdk.

Base URL: https://api.imprezahost.com
Auth: X-API-Key + X-API-Secret headers (rotate via clientarea → API keys)
IP factor (per key): whitelist (default) / tofu (trust-on-first-use) / keyonly; keys can be scoped (read/deploy/manage) + expiring
Envelope: {success, data, error, meta: {request_id, timestamp}}
Rate limits: 60 req/min/key default — raise per-key in clientarea

Full reference: api.html (interactive Swagger UI over the OpenAPI 3.1 spec) · machine-readable: openapi.yaml

Endpoint surface (high-level)

Path prefix	What it covers
`/v1/platform/servers`	Managed servers + agent bootstrap tokens
`/v1/platform/apps`	Curated app catalog
`/v1/platform/deployments`	Catalog deployments (create, list, show, uninstall, restart, logs, change-domain, add-onion)
`/v1/platform/deployments/custom`	Custom deployments (image / dockerfile / git / manifest) + context upload
`/v1/agent/*`	Used by the agent daemon — bootstrap, poll, report, deploy-result, logs, DNS-01 challenge proxy
`/v1/account, /v1/domains, /v1/email, /v1/vps, /v1/dedicated, /v1/orders, /v1/invoices, /v1/webhooks`	The rest of the customer surface — managing the products you buy from Impreza

SDK Go

The official Go SDK — used by the CLI + the agent + the MCP server. Same source repo as the CLI: github.com/imprezahost/impreza-devkit (sdk-go/).

import sdkclient "github.com/imprezahost/impreza-devkit/sdk-go/client"

c, _ := sdkclient.New(sdkclient.Context{
    Key: "imp_...", Secret: "...",
})
servers, _ := c.PlatformListServers(context.Background())
for _, s := range servers.Servers {
    fmt.Println(s.AgentID, s.Hostname, s.Status)
}

A Python SDK (impreza-sdk) exists with the same surface — see pypi.org/project/impreza-sdk.

Tor (.onion)

Every deployment can publish a Tor v3 hidden service alongside its clearnet URL — just pass onion: true. The agent runs a Tor sidecar container, provisions a fresh ed25519 keypair (persists it under the deployment’s state dir), and emits the .onion address back via the deploy result.

Pure-onion deploys (no clearnet) are supported — set onion: true and omit domain. The agent will back-fill DOMAIN + DOMAIN_URL in the container env with the published .onion so apps that need to know their own URL get the right value.

Authentication

AI client ↔ remote MCP: OAuth 2.1 at https://mcp.imprezahost.com/mcp — consent in your clientarea, the client gets a scoped, revocable token (no key or secret leaves Impreza). Revoke under Impreza API → Connected Apps.
Customer ↔ API: X-API-Key (imp_…) + X-API-Secret headers. Generate in clientarea → Impreza API. IP factor per key (whitelist/tofu/keyonly); keys can be scoped + expiring; or pair with a code.
Agent ↔ API: X-Agent-Id (agt_…) + X-Agent-Secret headers, issued once at bootstrap and persisted to /etc/impreza-agent/credentials.toml.

Limits + abuse

Cgroups: every custom deploy gets --cpus + --memory applied at container start. Defaults are 1 CPU / 512 MB if you don’t specify. Override via cpus + memory_mb in the deploy body, clamped against the VPS’s reported memory.
Build context size: tarball uploads cap at 100 MB per context. Pack a leaner build context (use a .dockerignore on your end) — the CLI bakes in the usual exclusions (.git, node_modules, __pycache__, …).
API rate limit: 60 req/min/key default. Raise per-key in clientarea.
Trust model: we trust the customer — the VPS is yours, the agent runs your code, cgroup ceilings prevent runaway containers. We do not currently scan images or Dockerfiles.

Open source

Repository	What it is	License
impreza-devkit	SDK Go + CLI + agent source + Caddy DNS provider	—
impreza-mcp	MCP server (Node TypeScript) — npm: `impreza-mcp`	MIT
agent-public	Public agent installer + prebuilt binaries (amd64 / arm64)	—

Help

Clientarea — billing, services, API keys, app management
support@imprezahost.com — support
imprezahost.com — main site

For AI tools: a structured index at /llms.txt and a single-file dump of all docs at /llms-full.txt — paste either into your AI’s context to brief it on the whole platform in one shot.

Access Impreza through Tor

Use these official addresses directly in Tor Browser or a Tor-capable client. No initial visit to the .com services is required.

Service	Direct onion address
Customer portal	https://portal.imprezareshna326gqgmbdzwmnad2wnjmeowh45bs2buxarh5qummjad.onion/clientarea.php
REST API base URL	http://api.imprezareshna326gqgmbdzwmnad2wnjmeowh45bs2buxarh5qummjad.onion
Hosted MCP endpoint	http://mcp.imprezareshna326gqgmbdzwmnad2wnjmeowh45bs2buxarh5qummjad.onion/mcp
Documentation	http://docs.imprezareshna326gqgmbdzwmnad2wnjmeowh45bs2buxarh5qummjad.onion/

The portal uses HTTPS; API, MCP and docs use HTTP inside the Tor onion connection. For proxy configuration and OAuth requirements, see official Tor addresses and connection guidance.