Operate and recover your app

Use My Apps → Advanced, the hosted MCP connector, or local impreza-mcp 0.39.0+ to review configuration changes, inspect application metrics and recover a managed PostgreSQL backup. Metrics and managed MariaDB connections require agent 0.6.17+. Update explicitly after active operations finish; installing a new MCP package does not update your server.

For an anonymous account, the initial MCP token lasts 15 minutes. Renew it with the account's REST key before continuing automation; renewal creates a new credential, so request spending ceilings and optional restrictions explicitly. Older tokens issued without a deadline expire on 16 October 2026 at 21:48 UTC. See anonymous-account renewal and privacy, including the 24-hour creation-IP window and next-cron cleanup.

Before you start

Use your own application and backup identifiers. API credentials require read for inspection/download and deploy for reviews, alert rules and apply. Configuration workflows require unrestricted account credentials. Account and resource authorization still applies to every request; a saved review does not bypass a change of ownership. Portal actions use the authenticated account's permissions and session protection.

A review is not an execution. Applying a review queues work and may interrupt the application. Follow the returned command and its final result; acceptance alone does not prove a healthy deployment or a restored database.

Enter secrets outside the chat

The secret-entry workflow is available in the portal, the hosted MCP connector and the local impreza-mcp package 0.49.0 or later (impreza_prepare_secret_entry and impreza_get_secret_entry), since 11 October 2026.

Ask the AI to prepare a link with an existing deployment_id and variable_name, or project_id, optional environment_id, and the variable name. Never send the value to the AI or in tool arguments.
Open the returned clearnet or onion portal link yourself. Sign in as the same account's owner, including over Tor. Confirm the app and variable shown on the page, then type the value there. The page uses no third-party resources.
The link expires after ten minutes and can be consumed once. Cancel it if the target is wrong. Sharing the link is unsafe, even though owner login is also required. The token stays in a URL fragment and is removed by the page; it is not sent in the HTTP URL or referrer.
The AI polls impreza_get_secret_entry with session_id. It receives only the session ID, variable name and pending, stored, expired or cancelled status. Neither the value nor a hash of it is returned.
Redeploy to apply the stored value. Group values keep their normal project → environment → app precedence. First-installation credentials of catalog apps cannot be changed with this workflow.

New secret values in recognized variable fields, declared catalog secrets, explicit password and Git-access token fields, build-secret maps and recognized nested configuration are refused by MCP with SECRET_ENTRY_REQUIRED. A stored secret can be kept with the existing keep marker; it must never be retyped in chat. For an initial app installation, private Git fetch, host password change, build-secret rotation or onion-key import, use the corresponding portal form. The runtime-variable link is not a host-password or build-secret editor.

Sealed application variables also survive Git webhook redeploys, image promotions and configuration applies. Configuration exports use {secret: true} references; keep those references in the document. To rotate the value, prepare another owner entry link. REST redeploy requests that overlay an already sealed variable are refused with SECRET_ENTRY_REQUIRED, including differently cased names.

Scope of secret protection

Secret-entry protects the value typed into its designated owner-authenticated portal form. It does not make arbitrary chat messages or uploaded source secret-safe.

Classification is not a scanner of arbitrary source code, Dockerfiles, YAML or unrecognized configuration fields. Such text can still contain a secret. Do not paste it into chat; use an authenticated upload or portal form. If you already sent a secret to an AI provider, rotate it: a tool refusal cannot erase the provider's conversation history. Platform-generated credentials returned by bootstrap, subcredential minting and onion-key export follow their existing flows and are outside this increment.

REST clients prepare with POST /v1/platform/secret-entries and poll with GET /v1/platform/secret-entries/{id}. These routes accept no value. The local MCP uses a read-only classification preflight containing identifiers only; values recognized as secrets are refused before the write request.

Version your application configuration

Call impreza_export_app_config with deployment_id. The result contains an impreza.app.v1 JSON document for an existing custom application: source, configuration, resource limits, domain and connection references. Sensitive variable names are represented by references to values stored by the platform. Review the exported document before committing it: configuration classification is not a general scanner of customer source code or arbitrary text.

Export and save the document in your repository.
Call impreza_prepare_config_apply with the same deployment_id and the edited document serialized as the document string.
Inspect the changes and expiry. Keep the returned config plan ID and digest.
Read it again with impreza_get_config_plan and config_plan_id if needed.
After approval, call impreza_apply_config_plan with config_plan_id, review_digest and confirm: true.

Reviews expire after 15 minutes. Repeating an accepted plan returns the existing receipt instead of creating a second job; a no-change document queues nothing. Secret references resolve against the existing application's stored values and missing references fail closed. Version 1 changes an existing app in place; it does not clone an app, move domains or change database bindings. Use the separate reviewed flows for those tasks. This is not a general infrastructure provisioner or an automatic multi-server migration tool.

REST paths:

Method	Path	Purpose
GET	`/v1/platform/deployments/custom/{id}/config`	Export
POST	`/v1/platform/deployments/custom/{id}/prepare-config-apply`	Review a document
GET	`/v1/platform/config-plans/{id}`	Read saved review
POST	`/v1/platform/config-plans/{id}/apply`	Apply exact digest with confirmation

Use the Python CLI or SDK

Install impreza-cli 0.6.0+ (which requires impreza-sdk 0.6.0+), configure an authenticated context, and use the same reviewed configuration workflow:

impreza config export dpl_aaaaaaaaaaaaaaaa --out app.json
impreza config apply dpl_aaaaaaaaaaaaaaaa --file app.json
impreza config plan cplan_cccccccccccccccccccccccc

Inspect the displayed changes before confirming. --yes explicitly confirms the generated review for automation. The CLI refuses an incomplete review or one for another deployment. Input must be a regular UTF-8 file of at most 64 KiB. Keep the returned plan ID to inspect the receipt after a lost response; accepted is queued, not verified healthy. A document with no effective changes returns a receipt without starting another deployment.

Python SDK: client.config.export(deployment_id), client.config.prepare(deployment_id, document_text), client.config.get_plan(plan_id), and client.config.apply(plan_id, review_digest). AsyncClient exposes the same methods with await. Keep the exact reviewed ID and digest. Config schema v1 updates an existing application; it does not create a new deployment, change its domain or move its database connection.

Inspect metrics and receive alerts

Open Metrics & alerts on the application's Advanced card. With MCP, use impreza_app_metrics with deployment_id and optional minutes (5–1440, default 120). Measurements include container state, restart count, CPU percent, memory usage/limit and estimated volume bytes. They are minute-bucketed and retained for 24 hours. CPU is an instantaneous sample, not a minute average; Docker volume accounting is an estimate. Missing reports are unknown, never proof that an application is healthy.

Create a rule with impreza_set_alert_rule:

{"deployment_id":"dpl_aaaaaaaaaaaaaaaa","metric":"memory_pct","threshold":85,"duration_minutes":3,"enabled":true}

Supported metrics are down (threshold 1), restart_loop (restart count) and memory_pct (1–100 percent of the configured memory limit). The duration is 1–60 minutes. Supply rule_id to update an existing rule. Read rules, open alerts, resolved alerts and evidence with impreza_list_alerts. Alerts are recorded in the portal even without a notification destination. For external notifications subscribe your account's webhook to deployment.alert; delivery uses bounded retry. Do not assume an arbitrary destination or onion transport is supported merely because the account has webhooks.

REST: GET /v1/platform/deployments/custom/{id}/metrics, GET .../{id}/alerts, and POST .../{id}/alert-rules. Agent reports contain measurements and state, not environment values. This feature does not collect application traces, request contents or business metrics, and it does not automatically restart apps.

Retention, CPU averaging and three more alert metrics — available since 25 September 2026. Minute points are kept for 48 hours, and a daily rollup consolidates each closed hour older than 24 hours into an hourly table retained for 90 days. Reads stay at minute resolution up to 24 hours back; asking for more merges the hourly rollup with the recent minute rows, and every point in the series marks its own resolution (minute or hourly). The accepted minutes range grows accordingly (up to 129600, about 90 days). CPU becomes the sample-weighted average of each bucket when the agent reports the optional cpu_avg_pct/cpu_samples protocol fields. No agent release reports them yet, so every current agent sends one instantaneous sample per minute (samples: 1) — a weighted average of one, so nothing changes for them. Alert metrics grow from three to six: cpu_pct (1–10000, where 100 is one full core, evaluated on the report) joins the existing three, and agent_offline plus backup_failed (threshold 1) are evaluated by the platform's minute cron tick instead of the report — an offline agent cannot report itself, and a failed backup is a fact the control plane already holds. The cron tick has a daily fallback, so the evaluation is degraded, never silently off. All six share the same open/deduplicate/resolve machinery, numeric-only evidence and deployment.alert webhook delivery. There is no Matrix or SimpleX notification channel in this increment; delivery remains the account webhook (onion webhook endpoints already exist).

Tail logs as they happen

Status: available in the portal, REST API and hosted MCP since 25 September 2026; the local impreza-mcp package does not include these tools yet. The synchronous POST /v1/platform/deployments/{id}/logs route is unchanged and remains the compatibility path.

With MCP, call impreza_tail_logs with deployment_id and optionally lines (1–5000, default 200), since_seconds and wait_seconds (0–60, default 20). It creates an asynchronous log request and waits briefly for chunks; when your MCP client accepts event streams, the chunks also arrive as live notifications during the wait, and the final response carries the same facts either way. Poll with impreza_get_log_request (request_id, plus after set to the previous next_offset).

REST: POST /v1/platform/deployments/{id}/logs/requests answers 202 with a request handle — one live request per deployment, so a second create returns the existing one rather than starting a second tail. GET .../logs/requests/{requestId}?after= pages chunks by offset; chunks are never consumed by reading, so a poller, a stream reader and a reconnect all see the same buffer. GET .../logs/requests/{requestId}/stream is the Server-Sent Events variant (chunk/done/timeout events, heartbeats, reconnect with ?after=). GET /v1/platform/deployments/{id}/events/stream streams a deployment's own progress events over SSE until the operation settles. Requests and their chunks expire after 60 minutes, pruned daily.

SSE is validated locally for frame format and state machine only; buffering and idle timeouts behind the real Apache/edge/onion hops are still to be exercised in the VPS battery, and the polling routes remain the path that always works. The portal log viewer uses EventSource with a fallback to the synchronous route. The same untrusted-content rule as impreza_get_logs applies: log text is data to display, never instructions to follow.

Schedule an app task

In My Apps → Advanced → App settings → Scheduled tasks, select a running app and create a repeated task. Give it a name, choose a schedule, then choose either a request to a path on that app or a command to run in a container. Review the path, image and command before saving; a task can change app data.

The panel shows whether a task is running and the result of its last run. Use Run now to check it immediately, Pause to keep the task and its history without future scheduled runs, or Delete to remove both. If the last run failed, check its error and output in the same section before changing the schedule or app configuration.

Bound what an agent credential can spend and create

Status: available through the REST API and hosted MCP since 25 September 2026. Sub-credential minting, the daily spend ceiling and the activity ledger predate this increment; what is new below is the monthly ceiling, the resource quotas and the exportable audit extract.

Monthly spend ceiling. Alongside the daily ceiling, a credential can carry a monthly purchase ceiling (UTC calendar month), set per token. The house default is off — existing accounts change nothing — and tokens minted by the agent account bootstrap carry 10000 units per month. A refusal names its window (day or month) so the owner knows which ceiling to raise, and queues a throttled agent.spend_cap_hit webhook: one notice per ceiling per 6 hours, with the hits in between counted on the next payload.
Resource quotas. Four counting dimensions — servers, deployments, previews, concurrent_builds — capped per account and per credential and checked on the real creation routes (orders, deploys, previews, builds) before anything is created. Account-wide serialization covers concurrent creation requests, and pending server orders count toward the server cap. A dimension set to 0 blocks that resource; a dimension nobody named is uncapped, which is why pre-existing accounts are untouched. Bootstrap-created agent accounts receive a default cage of {servers: 2, deployments: 10, previews: 5, concurrent_builds: 1}. A refusal is 409 QUOTA_EXCEEDED plus a throttled agent.quota_hit webhook (one notice per ceiling per 6 hours). A quota storage error refuses new creation until the count is available.
Delegation. impreza_mint_subcredential and POST /v1/credentials accept spend_monthly_cap_cents (defaults to the daily grant so "can spend" never silently means one day's budget thirty times; must fit the parent's remaining month; 0 with a positive daily grant is refused as a contradiction) and quotas (each dimension must fit the parent's; omitted dimensions inherit). A child can still never exceed its parent on any axis. When both the account and credential set a resource quota, the tighter number applies; a credential cannot widen the account ceiling.
Identity and audit. impreza_list_credentials and GET /v1/credentials show the human owner answerable for each credential, its monthly ceiling and its quotas. GET /v1/credentials/activity?format=csv (or impreza_agent_activity with format: "csv") exports the audit ledger — up to 1000 entries, each line with the credential's label resolved — the same scrubbed rows the JSON surface shows: identifiers kept, secrets never recorded.
Approval is never a webhook reply. Both events name the existing, already-authorized path to widen the cage (mint a wider credential from a parent that holds the budget, adjust the account quota, or act in the clientarea). Nobody approves a cap raise by responding to a webhook.

Download a backup

Use Download on a completed backup, or impreza_download_backup with backup_id. REST: POST /v1/backups/{id}/download-link. The response provides presigned URLs for the manifest and chunks in your own storage bucket, expiring after five minutes. Download every part required by the manifest. These URLs grant access to backup contents until expiry: do not commit them, put them in tickets or share them with untrusted recipients. Bucket credentials are not returned and backup bytes do not pass through the portal. Incomplete backups and unreadable manifests cannot be downloaded by this workflow; ownership and manifest-size/part limits are enforced.

Standalone database application backups

Available since 14 October 2026 for eligible standalone PostgreSQL, MySQL, MariaDB and MongoDB catalog applications. Existing deployments must meet the image and configuration requirements below; publication does not upgrade an installed database or make an older file backup consistent.

Eligible standalone PostgreSQL, MySQL, MariaDB and MongoDB catalog applications now use logical database exports instead of copying a running database data directory. A backup is successful only after its export has been restored into an isolated scratch database and checked, then uploaded to your configured storage. Queued acceptance is not verified completion: poll the backup until its terminal status.

PostgreSQL uses a custom-format export for each database plus global roles. Each database has its own snapshot; this does not promise a single transaction snapshot across databases. MySQL and MariaDB use a transaction snapshot for each InnoDB database, including routines, triggers and events. Applications containing non-InnoDB tables are refused with a clear error. Avoid schema changes while a backup is running; no cross-database snapshot is promised.

MongoDB standalone exports preserve per-document consistency. They do not provide a point-in-time snapshot across collections or databases. Pause application writers when your application requires that stronger consistency. Replica-set/oplog recovery is outside the validated standalone increment.

Restoring replaces the target database data from the export, restores customer accounts and grants, and applies the application's current administrative credential. The target application is stopped during the exchange. Wait for the restore's terminal result and required startup verification before resuming writes. A restore does not recover writes made after that backup's snapshot.

The backup uses the exact digest-pinned database image in the application's stored deployment snapshot. An older snapshot containing only a mutable image tag is refused before a new logical backup is queued. Updating the catalog does not migrate existing deployments automatically. Keep the app running and do not redeploy it from the current catalog to resolve this conflict. Ask support to pin the exact official image already running on your app, preserving its engine version and existing data. Support verifies the current container and digest, updates only the stored image reference during an authorized maintenance window, and requests no restart or database migration. Retry the logical backup or restore after this maintenance is confirmed. If the exact running digest cannot be verified, maintenance stops for investigation; a new catalog image is never substituted. Do not remove the database or change its version to resolve this error.

Existing file-format backups remain restorable. They display this warning: "This is an older hot-file backup of a database app, taken while the database was running; it may restore inconsistently. Take a fresh backup to get a verified logical dump." Keeping old backups does not establish their consistency.

This increment covers standalone catalog database applications. Applications with an internal bundled database remain outside this rollout until their separate increment is approved. Ordinary non-database application backups retain their existing file format.

Restore a managed database into a new database

Use Restore database to a new database in the completed backup's portal card, or this MCP workflow:

impreza_prepare_database_restore with backup_id; optionally provide an eligible target_binding_id belonging to your account.
Read the source, target provider, new database name, expiry and digest.
impreza_get_database_restore accepts the returned restore_plan_id.
After approval, call impreza_apply_database_restore with that plan ID, the exact review_digest and confirm: true.
Follow the resulting job and verify the recovered data before choosing any separate application cutover.

REST: POST /v1/backups/{id}/prepare-database-restore, GET /v1/database-restores/{id}, POST /v1/database-restores/{id}/apply. Reviews expire after 15 minutes. Repeated application returns the receipt. The existing database is not overwritten and the app is not automatically repointed. Pending credential rotation or cleanup prevents review. This restores a managed PostgreSQL or MariaDB dump into a provider of the same engine. MariaDB backup and restore require agent 0.6.18+ and MCP 0.40.0+ for current guidance. This completed-backup workflow does not provide point-in-time recovery, WAL replay or automatic cutover; for PostgreSQL, see point-in-time recovery. Verification here checks the dump and tables, not every application-level invariant.

MariaDB's consistent snapshot currently supports InnoDB tables only. Views, triggers, routines, events and non-transactional tables are refused. Avoid schema changes while backing up. Database and filesystem volumes do not form one atomic snapshot. The restore/verification login is temporary and restricted to the new database; it cannot access the serving database. Successful restoration removes that login and retains the new database for review through the provider administrator. No application credential is repointed or granted the recovered database automatically. A host crash can leave temporary data or an account for administrator reconciliation; do not delete unknown objects or reset ownership markers to bypass a refusal.

Point-in-time recovery for PostgreSQL

Available in the portal, the REST API and the hosted MCP connector since 25 September 2026; the local impreza-mcp package does not include these tools yet. It needs a managed PostgreSQL binding, the account's backup storage (its own Impreza S3 bucket) and agent 0.6.21 or later. Read tools require read; changes require deploy and an unconfined account credential, because physical recovery covers the whole PostgreSQL provider.

Turn it on in the PostgreSQL app's Backups & recovery section or with impreza_configure_pitr. The platform creates a replication slot and drains WAL into the bucket every 5–60 minutes (default 15), next to periodic base backups. The recoverable boundary advances only after a complete WAL segment covering that instant is stored; an empty or failed drain does not advance it, and the interval is not a promise of zero data loss.

To recover, prepare a review for a UTC instant such as 2026-09-24T12:00:00Z (impreza_prepare_pitr_restore), read the base, WAL range, binding and new database name, then apply it with the exact review_digest and confirm: true (impreza_apply_pitr_restore). Replay runs in an isolated scratch cluster without networking and restores into a new database; the serving database is not replaced and the app is not repointed. Follow impreza_get_pitr_restore until the phase is verified or failed. impreza_drill_pitr replays the newest shipped state in a scratch cluster and measures it; nothing touches the live database.

Failed automatic work retries with increasing delays and pauses after six consecutive failures; repair the cause, then save the configuration to resume. Limits, REST routes and storage generations are in the platform reference.

Static sites and Go without a Dockerfile

Select static_files or go_build in the custom-app form. The local MCP impreza_deploy_custom uses mode: "dockerfile" with a Git URL or local folder, but generates the recipe; no project Dockerfile is required.

static_files: the selected project_dir is the site. A regular index.html is required. No package manager runs. Symlinks are refused; hidden files and directories are excluded. Limits: 10,000 files and 256 MiB. static_spa defaults to false (unknown paths return 404); true serves index.html. The fixed health probe uses /index.html. No build secrets or output-directory option.
go_build: requires go.mod and, when dependencies are declared, go.sum. The pinned Go 1.25 toolchain refuses newer requirements instead of downloading another toolchain. go_package selects the main-package folder (default .). Build produces a static binary with CGO disabled; runtime is non-root. No go.work, vendoring or external replace paths. healthcheck_path defaults to /.

Both default to port 8080 (allowed 1024–65535) and support require_healthy_start. Choose a readiness endpoint that checks actual app readiness. impreza_prepare_project accepts supplied go_mod, go_sum and index_html for advisory analysis; it does not execute that source.

Review configuration, monitor apps and recover data