Deploy any app to your own VPS — by AI, by CLI, or by API.

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)

1. Generate an API key + secret in the Impreza clientarea. Whitelist your laptop’s public IP on the key.
2. Get the MCP config snippet for your AI tool:

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

3. 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

Concepts #

1. Get a VPS #

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

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

1. Sign in to portal.imprezahost.com and open My Apps.
2. 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

3. 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.
4. Within ~10 seconds the agent appears in My Apps with status: online. You’re ready to deploy.

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.

3. Generate API keys (+ IP whitelist) #

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

1. Sign in to portal.imprezahost.com and open Impreza API.
2. Type a label (something like laptop, ci, or claude) and click Generate New Key.
3. 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.

Whitelist the IPs that will call the API

Required. Without this the API rejects every call with 403 IP_NOT_WHITELISTED. From the Impreza API page, open the IP Whitelist tab and add:

• Your laptop’s public IP — needed if you’ll run the impreza CLI locally, or the impreza-mcp MCP server inside Claude Desktop / Cursor / Continue / Zed (those tools spawn the MCP server on your machine, not on your VPS).
• Your VPS’s public IP — needed if you’ll curl the API from the VPS itself, or run anything API-calling there (an Impreza CLI on the server, a CI runner, …). You don’t need this for the agent itself — the agent has its own credential.
• Your AI provider’s outbound IP (rare) — only when the AI invokes the API directly from its own infrastructure rather than via an MCP server running on your machine. Most modern AI tools (Claude Code, Cursor, Codex CLI) use the local-MCP path, so this row is usually not needed.

Why per-IP whitelist (and not just per-key)?

Two layers of defense. A leaked API secret alone doesn’t let an attacker call the API — they also need to be sending requests from an IP you explicitly added. Pair that with rotation (generate a fresh key in seconds + delete the old one) and a compromised credential is recoverable without losing data.

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"}
  }'

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
  }'

Public git repository

Point at a public https 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:

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
  }'

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. Three ways to enable it:

• From the My Apps panel (Advanced view): expand 🔗 Connect GitHub for auto-deploy on the deployment card, paste a Fine-grained GitHub PAT, confirm. Done.
• From an AI assistant: the MCP tools impreza_git_webhook_connect, impreza_git_webhook_status, and impreza_git_webhook_disconnect cover the full lifecycle.
• From the REST API:

  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_..."}'

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.

AI tools (MCP) #

impreza-mcp is the Model Context Protocol server that lets AI tools call Impreza Host directly — no copy-pasting URLs, no leaving the chat. Loaded once into your AI tool, the AI gains 13 tools it can call autonomously:

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 (Claude Code shown — same shape for Cursor and Codex CLI)

{
  "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 whitelist: every key has an allow-list; whitelist the caller’s public IP before use
• 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)

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 #

• Customer ↔ API: X-API-Key (imp_…) + X-API-Secret headers. Generate in clientarea → API Keys. Whitelist your IP.
• 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 #

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.