---
name: mergeek-link-deploy
description: >
  Deploy local web applications to Mergeek Link (mergeek.com) and get a URL
  to access the live app on the web, subject to its configured access policy.
  Use only when the user explicitly chooses Mergeek, for example "deploy this
  app to mergeek.com", "publish to Mergeek" or "部署到 Mergeek", or when the
  current task has already selected Mergeek. Generic requests such as
  "上线这个应用" apply only within that established Mergeek context.
  Includes first-time registration, App selection and authorization, updates,
  and recovery of an existing deployment.
---

# Mergeek Link publishing guide

Last updated: **2026-10-26 (Asia/Shanghai)**.

Fetch the current guide at the start of a task and read changes since any saved copy. This timestamp identifies documentation, not the server's deployed version. Actual tool schemas, the anonymous HTTP contract and execution results define available operations.

Execute technical work yourself. The user completes browser login/consent, documented client loading steps and decisions requiring confirmation. Use plain language and verified instructions for the active client. Keep credentials, device codes and signed upload instructions private; the official HTTP approval link/user code may be shown.

## Choose the task

| Request | Read next | Completion |
| --- | --- | --- |
| Connect or verify MCP only | [Connect and verify](https://mergeek.com/link/agent/references/connect.md) | Report configuration, authorization, tools and any App check; stop without deploying |
| First release without an App ID | [Registration and App authorization](https://mergeek.com/link/agent/references/onboarding.md) | Local compatibility preflight first; select protocol, confirm the App, then continue that MCP or HTTP task |
| First release with an App ID | Path selection below, then [project preparation](https://mergeek.com/link/agent/references/publish.md) and one protocol flow | New Deployment is current and access/content match the configured policy |
| Update a work | [Update checklist](https://mergeek.com/link/agent/references/update.md), then one protocol flow | Verify the new release and compare the original URL/version |
| Resume an existing or uncertain write | [Recovery](https://mergeek.com/link/agent/references/troubleshoot.md) | Resolve the recorded attempt before any new create |

Use a supplied `app_id` unchanged. An update without an ID must identify and confirm an existing work; use onboarding with `intent: update` (HTTP `--intent update`), which cannot create a new work. For a first release without an ID, choose the publishing path below, then follow [onboarding](https://mergeek.com/link/agent/references/onboarding.md): the user confirms a new or existing App in Studio and the Agent receives its ID automatically. Do not ask the user to copy a publishing prompt, guess an ID, select an unrelated App, or overwrite another work.

Onboarding supports MCP and official HTTP. A working MCP connection uses `start_onboarding` / `get_onboarding`; HTTP uses the official helper or protected direct API flow. Keep the chosen protocol after confirmation unless the explicit pre-deployment fallback below applies.

Save the returned `onboarding_id` and pass it unchanged when creating this task’s Deployment. It correlates the confirmed target with the release; it is not a credential. See [identifiers and codes](https://mergeek.com/link/agent/references/onboarding.md#identifiers-and-codes) for the distinct request, authorization and deployment values.

Keep a private task record outside source: App/project, original URL/current Deployment, parameters, fixed ZIP/manifest/digests, known Deployment ID and last stage. HTTP also records its Idempotency-Key. Resume from that record.

## Choose a publishing path

MCP and official HTTP are complete paths with the same release checks. Resolve existing/uncertain writes before choosing a new path. HTTP does not require native MCP integration; its execution requirements are in the [HTTP flow](https://mergeek.com/link/agent/references/http-publishing.md).

| Active coding client | Default first path |
| --- | --- |
| ChatGPT / Codex, Claude / Claude Code, OpenCode, Cursor, Antigravity, 千问 / Qwen Code | MCP |
| TRAE / TRAE CN / TraeCode, WorkBuddy / CodeBuddy (IDE or Code) | Official HTTP |
| Other or unknown client | Reuse working MCP tools; otherwise confirm supported native setup or use official HTTP |

These are publishing defaults, not compatibility guarantees. Identify the host client, not merely the model. Apply the decision table below, then read only that client's [instructions](https://mergeek.com/link/agent/references/clients.md).

Apply this decision table in order; the first applicable row determines the next action:

| Condition | Next action |
| --- | --- |
| User declined authorization | Stop; do not switch protocols to request it again |
| User explicitly requests an MCP connection check or MCP-only access | Use supported MCP setup/verification; report its blocker if unavailable |
| User explicitly chooses MCP or HTTP | Follow that choice; report a blocker if the required path is unavailable |
| Connected MCP lacks onboarding tools, with a known Deployment or uncertain write | Stay in original recovery; resolve that attempt before a new create or protocol switch |
| Connected MCP lacks onboarding tools, before App confirmation and with no known Deployment or uncertain write | For an ordinary publishing request, enter HTTP onboarding |
| Connected MCP lacks onboarding tools, with a confirmed App and no deployment write | Continue ordinary MCP publishing with that App. If deployment tools are also unusable, preserve that exact App and baseline and obtain HTTP consent for that App |
| Working MCP tools, without an explicit HTTP choice | Use MCP; without a confirmed App ID, discover `start_onboarding` / `get_onboarding` and complete [onboarding](https://mergeek.com/link/agent/references/onboarding.md) |
| HTTP-first client, without an explicit protocol choice | Enter HTTP directly; no initial MCP setup attempt |
| Native MCP unsupported, or client/setup method cannot be established | Enter HTTP without inventing an integration or repeatedly searching configuration directories |
| MCP connection/OAuth/protocol calls fail, or tools remain unusable after supported setup and verification | One targeted repair and recheck when a reliable remedy exists; if still unusable, use HTTP after recovery |
| MCP-first client, or another client with working Mergeek tools | Discover tools; connect via supported native OAuth if needed. Read a supplied App, or use MCP onboarding to obtain a user-confirmed App ID |

A missing App ID is not an MCP failure. The three missing-onboarding rows apply only to ordinary publishing without an explicit protocol choice; an explicit MCP choice remains MCP-only. Pending consent waits and refusal stops. HTTP consent never authorizes MCP. The before-write fallback is the exception to keeping the confirmed protocol; it preserves the confirmed App and requires the new path’s own consent.

Pending browser login, trust or consent means wait. Empty `resources/list` does not prove tools are absent. Ownership, App restriction/expiry, quota, validation, build and migration failures require their actual [recovery](https://mergeek.com/link/agent/references/troubleshoot.md), rather than a protocol change.

### Before switching protocols

Use the [saved-state gate](https://mergeek.com/link/agent/references/troubleshoot.md#before-switching-protocols). Known MCP Deployments stay on their original path; HTTP cannot adopt them. Unknown writes must be identified or remain blocked. Credentials never transfer between protocols or to object storage.

## Connect and verify

- **MCP selected:** Read [Connect and verify](https://mergeek.com/link/agent/references/connect.md) for native setup/OAuth, and only the active client's recipe in [Clients](https://mergeek.com/link/agent/references/clients.md).
- **HTTP selected:** Complete authorization and App verification within the [HTTP flow](https://mergeek.com/link/agent/references/http-publishing.md); skip native MCP setup.

A connection check without an explicit protocol follows the same path selection. For an HTTP-only connection check, use `--action check`, which requests only `link:read`, in a separate task directory; `inspect` is preparation for a subsequently authorized publication. Without an App ID, obtain confirmation of an existing App rather than creating one just to check connectivity. Stop after authorization and the requested read checks; do not create a Deployment.

## Prepare and validate

Before account setup, run the account-free [local compatibility preflight](https://mergeek.com/link/agent/references/publish.md#local-compatibility-preflight). Then read [Project preparation](https://mergeek.com/link/agent/references/publish.md) for shared inspection, runtime/static parameter examples, version constraints and ZIP review. Complete them before creating a Deployment. `ready=true` validates declarations/configuration, not executed build, migration, startup or functions.

Then follow one complete flow: [MCP](https://mergeek.com/link/agent/references/mcp-publishing.md) or [HTTP](https://mergeek.com/link/agent/references/http-publishing.md). Source/configuration changes require a resolved old attempt, a fresh baseline check and a new reviewed task.

## Asset caching and updates

Read [Caching and asset versions](https://mergeek.com/link/agent/references/cache.md) before publishing or changing JS, CSS or images. Defaults are 1 hour for JS/CSS, 7 days for images including SVG, and revalidation for HTML. Let the project's build tool generate content hash filenames and update references; otherwise version filenames yourself. The platform does not generate hashes or rewrite references. Pure static Apps do not support cache configuration files; runtime Apps can override defaults through HTTP response headers.

## PWA support

Hosting automatically supplies a manifest using the Studio App name/icon, Apple touch icon and a same-origin Service Worker. Read [PWA defaults and customization](https://mergeek.com/link/agent/references/pwa.md) before adding your own manifest/Worker or disabling defaults. Existing manifest links are preserved. Runtime Apps use HTML response headers; static Apps use HTML meta declarations. Default offline support displays a retry page; it does not make business functions work offline.

## Data persistence

### Database selection

For a new App that needs a database, prefer managed MySQL unless the user or project has a specific reason to use SQLite. For an existing App, inspect and preserve its current engine and data; an engine switch requires a reviewed migration plan and the user's confirmation.

#### Managed MySQL

Recommended for shared structured data such as messages, product records and configuration, especially with multiple users or growing data. Studio supports browsing tables, filtering records and editing individual records. Read [Managed MySQL](https://mergeek.com/link/agent/references/mysql.md#managed-mysql) for bindings, drivers and connection variables.

#### Managed SQLite

A lightweight choice for simple Apps with modest data and few concurrent writes. Existing SQLite projects can continue using managed SQLite. Read [Managed SQLite](https://mergeek.com/link/agent/references/mysql.md#managed-sqlite) for the managed database path and deployment configuration.

### Persistent files

Use [Orbit Storage](https://mergeek.com/link/agent/references/oss-storage.md) for images, attachments and other persistent files; store their keys, ownership and related metadata in the database. Runtime `uploads/`, `public/uploads/` and `/tmp` are not persistent user-file storage; exclude them from source packages.

### Data migration and verification

For either engine, read [migration checks and stop conditions](https://mergeek.com/link/agent/references/mysql.md#migration-command-safety) before supplying a migration command. Follow [database persistence checks](https://mergeek.com/link/agent/references/mysql.md#verify-persistence) and, where files are used, [file persistence checks](https://mergeek.com/link/agent/references/oss-storage.md).

## References by task

Read the reference matching the feature or infrastructure work in the task.

| Topic | Task | Reference |
| --- | --- | --- |
| Data persistence | Configure database connections, migrations and persistence | [Managed databases](https://mergeek.com/link/agent/references/mysql.md) |
| Data persistence | Store persistent files | [Orbit Storage](https://mergeek.com/link/agent/references/oss-storage.md) |
| App feature integration | Implement Mergeek account login | [Mergeek login integration](https://mergeek.com/link/agent/references/mergeek-login.md) |

## Deploy and upload

Continue at [MCP creation](https://mergeek.com/link/agent/references/mcp-publishing.md#5-create-the-deployment) or [HTTP creation](https://mergeek.com/link/agent/references/http-publishing.md#6-create-and-upload). Save the Deployment ID immediately and upload the reviewed ZIP with its exact instructions.

## Verify and report

Reread the App, record `access_mode`, confirm this Deployment equals `current_deployment_id`, and verify this release’s content at the returned URL under that access policy. `public`: use a clean anonymous browser/session and expect content. `owner_only`: anonymous access must not expose content; verify the owner’s authorized access separately. `password`: anonymous access must show the password gate; verify content only with an authorized password supplied through the official page. Never change access mode or request secrets in chat to make acceptance pass. If either check cannot run, mark it unverified. An owner’s logged-in browser alone does not prove anonymous access. Updates compare the original URL.

Select checks from the actual release changes: exercise affected existing functions, migration/persistence for database changes, and login/logout/permissions for login feature changes. Mark unexecuted checks explicitly. Payments, messages and deletes use existing authorization or a documented test method; ask only for missing authorization.

Lead with the outcome. Use a success template only after this Deployment is current and the required access checks pass.

**Public access verified** (`access_mode: public`, anonymous content checked):

> 已上线，公开访问已验证：作品名称和可点击链接。
> 本次更新：实际发布内容。
> 已检查：匿名访问到本次版本，以及实际验证的功能。
> 尚未验证或需要处理：确实存在的事项。

**Restricted access verified** (`access_mode: owner_only` or `password`, both anonymous restriction and permitted content checked):

> 部署完成，受限访问已验证：作品名称和可点击链接。
> 当前访问策略：仅作者 / 密码访问（填写实际模式）。
> 本次更新：实际发布内容。
> 已检查：匿名访问被限制，以及获准访问到本次版本、实际验证的功能。
> 尚未验证或需要处理：确实存在的事项。

When this Deployment is current but the mode or a required access check is unknown/unexecuted, report “部署完成，访问验证未完成” with the exact missing check. If a check fails, report the failure. Do not use either verified template or claim public sharing from an owner's session alone.

On failure, state the blocked stage, old-version availability (checked or unverified), and next recovery action. After failure/termination reread current and check the original URL; never infer rollback or data preservation from status.

Include App ID, Deployment ID, path, release notes and separate results:

- `deploy_accepted`: creation returned a known Deployment ID.
- `processing_finished`: processing reached a terminal result; record success/failure.
- `deployment_current`: this Deployment became current.
- `access_mode`: `public`, `owner_only`, `password`, or unknown.
- `anonymous_access_verified` / `authorized_access_verified`: observed access/content results or unverified.
- `access_policy_verified`: whether observations match the configured policy.
- `public_access_verified`: true only when anonymous visitors actually reached this release in public mode; otherwise false/unverified, never inferred from owner access.
- `key_features_verified`: checks passed, failed or unverified.
- `data_change_reviewed`: “已检查，未发现明显风险”, “存在风险”, or “未验证”, with evidence; never a zero-data-loss guarantee.

Creation, upload or `running` alone is not public release proof. Verified public-mode success can be reported as “新版本已经部署并可以公开访问，但实际支付流程未经验证”; restricted-mode success should say “部署完成，访问符合当前访问策略”; it does not prove full product acceptance.

## Optional reminder about the default link

When reporting a successful release, consider adding one friendly reminder if the App's current slug is `link` followed entirely by digits (for example, `link123456`, matching `^link[0-9]+$`). HTTP callers can recognize the same pattern in the hostname of the returned `https://{slug}.app.mergeek.com` URL. Use the current App information already read for release verification; no additional request is needed just for this reminder.

Suggested wording in the user's language:

> 当前使用系统默认链接。你可以前往 [Studio → 管理作品](https://mergeek.com/studio/manage)，选择这个作品，在「作品信息」中修改专属链接，让它更容易记住。修改后，原链接将无法访问该作品。

This is optional guidance for the final message. A missed reminder does not change deployment success or require a retry. For a custom slug, omit it. The user decides whether to change the link; do not change it automatically or pause publishing for that decision.

## Recover a failed step

Use [Recovery](https://mergeek.com/link/agent/references/troubleshoot.md) for protocol-specific errors, unknown writes, immutable-source recovery, bounded retries and wait limits. Preserve the same App, baseline, source and known attempt.