Desktop sync with Cloud or a company server

Mockarty Desktop keeps projects local first. A named Cloud or company profile can synchronise supported project resources when the connection returns. Each profile has its own credential, Space or namespace, cursor and conflict history; switching profiles never reuses those values.

Before you start

Create or select a named connection profile in Mockarty Desktop → Connection. For Cloud, finish browser device approval and explicitly choose a Space. For a company server, sign in using the method provided by your administrator.

For a Cloud profile, Desktop renews write access automatically while it can reach Cloud. A confirmed period lasts no more than 24 hours and cannot outlast a paid subscription. If the connection or renewal is unavailable, your local data remain readable; changes in the Cloud-bound Space pause when the current period ends. Reconnect to receive the renewed access. A pending renewal request alone does not extend that period.

Enter the company server’s final address, including https:// when it uses HTTPS. Desktop does not follow redirects while signing in or sending its session: if the address redirects, ask your administrator for the destination address and enter that instead.
Check the address and enter your password in Desktop on this computer. The company-server probe, password sign-in and second-factor confirmation only accept requests from this computer. Cloud device-approval polling also requires the Desktop page’s own browser origin, not another local website or phone; phone pairing is a separate feature.

During company-server sign-in, Desktop verifies the returned user against the server and binds the profile to that server’s TLS identity. If the server certificate or key later changes, Desktop stops the connection instead of silently trusting the new identity. Confirm the planned rotation with your administrator and reconnect the profile. Private RFC1918 and IPv6 ULA company addresses are supported by the local setup wizard; loopback, link-local and metadata addresses are rejected.

What a company Desktop can use

Connected to a company server, Desktop works as a client of that server: it opens the modules your administrator granted you on the server, within the company’s Mockarty licence. Cloud plans and Cloud limits do not apply in this mode; the account chip reads Company licence. Desktop keeps working with these modules for up to 7 days without the server — after that it asks you to reconnect. When the administrator signs you out or removes your access, the modules close as soon as Desktop next reaches the server.

Allow Desktop sign-in on a company server

A Mockarty server does not accept Desktop sign-in by default. An administrator enables it once: set MOCKARTY_DESKTOP_AUTH_ROUTES=1 in the admin node’s environment (Helm: admin.env.MOCKARTY_DESKTOP_AUTH_ROUTES: "1"; Docker Compose: the mockarty service environment) and restart the node. Until it is enabled, the Desktop’s connection step says “The server is reachable but does not accept Mockarty Desktop yet”. If the server does not answer, the Desktop says so — check the address and the network.

The embedded interface always uses a separate local, HttpOnly session. The company session is written directly to the operating-system credential vault and is added to remote requests only by Desktop’s local broker. It is not stored in browser cookies or Web Storage. Reauthentication rotates that vault credential for the same server without resetting the profile’s sync or MCP settings. If the broker or vault is unavailable, remote account and namespace views stop with an unavailable state instead of showing local data as if it came from the company server.

Connecting a profile does not upload local data. Under Project sync consent, explicitly enable sync, tick the Projects to cover, select the object types, and save the scope. The Projects are offered as a checklist of this Desktop’s own projects, and a first consent starts with all of them ticked — untick what should stay local. Saving without a Project or without an object type is refused with a hint. For Cloud, the destination is the Space you approved when signing in; the field shows its name and cannot be changed here — connect or activate another profile to use another Space. Right after your first Cloud sign-in, Desktop offers Set up sync, which opens this consent directly. For a company server, enter the destination namespace ID (UUID) before saving.

The running Desktop applies the saved scope at once — no restart is needed. Then press Preview exact batch. The preview shows the exact object, byte and deletion counts plus excluded objects. Only Approve and sync sends that retained batch; after the consent is activated, Desktop immediately receives existing work from the selected Cloud scope. If that inbound request is temporarily unavailable, Desktop keeps the consent and sent local work, shows a warning, and retries through Sync now and the background controller. Cancel, close or restart before approval uploads nothing and advances no cursor. After a successful exchange, the profile status shows the time of that synchronisation; before the first successful exchange it says so instead of showing a time.

The selection belongs to one named profile and has its own revision. A signed-in Cloud profile stays bound to the Space approved during sign-in: a sync-selection request for another Space is rejected without changing the profile or its pending preview. Use another connection profile for another Cloud Space. Changing the allowed scope invalidates the previous preview and resets that profile’s sync cursors. A stale browser window cannot approve a newer selection.

Local execution remains local and consumes zero Cloud IU. The preview’s object and byte totals are also the pre-dispatch limits for the retained batch; Desktop does not allocate a larger remote sync operation and then trim it after sending.

Cloud mock capacity belongs to the billing account that hosts the selected Space. Personal Free allows 10 live mocks across all of that account’s Spaces; Personal Pro allows 250. An invited collaborator’s own plan does not increase the host’s allowance. A mock present in both Cloud and the shared runtime counts once. Editing, deleting, or replaying an existing mock does not consume another place. If a plan ends with more mocks than its new allowance, the existing mocks remain available for editing and deletion, while new mocks wait until capacity is free. A rejected sync change remains local and can be retried after capacity is available. Deleting a mock on the shared Mockarty node gives its place back the same way — see Shared Mockarty.

Connection secrets stay in the operating-system credential vault. Provider keys and tokens, browser cookies, local session tokens, private keys, vault values and LLM profiles are never included in project sync. Environment values also stay local until Mockarty provides an explicit shareable-variable reference. An object containing any of these sensitive values is excluded as a whole instead of being partially copied.

Environment definitions are a separate choice in the object types. Selecting them asks for an extra confirmation, and only definitions travel: the environment name, variable names, scope and flags. Values never leave the device that typed them — the other device shows the variable as empty and asks you to enter the value there.

An API collection is synchronised as one consistent unit: its collection-level scripts, ordered folders, requests, request scripts and protocol settings move together. This is also the shape produced by Postman, Insomnia and Bruno imports. A clean installation therefore restores the usable request tree, not an empty collection shell. If a request embeds Authorization, a password, token, API key, private key, provider credential or a secret query parameter, the complete collection stays local and appears as excluded in the preview. Replace the literal with a local variable before synchronising.

Unsaved API Tester request drafts and the Recorder’s last target URL stay in the current Desktop installation; they are not copied through browser UI-state sync. That channel shares only navigation and non-secret display settings. Save a collection and review the project-sync preview when you want to use it on another device.

Team modules: tracker, wiki, boards and messenger

A Team subscription includes the tracker, the wiki, boards and the messenger on the Desktop, and they work offline. To share them with your team, connect a Cloud profile to the Team Space and, in the Team modules part of Project sync consent, tick what you want to sync: Tracker projects and issues, Wiki pages, Boards, Discussions of issues, pages and boards. The section appears only when your plan includes the Team modules, and only for a Cloud profile — a company server does not sync them.

What you write while offline reaches the team once you are back online, and their changes reach you:

• Each object keeps the newest version. If you and a teammate both changed the same object since you last synced, the conflict appears under Sync status and you choose which version to keep, as for mocks.
• An issue created offline keeps its identity. If a teammate created an issue with the same key in the meantime, yours gets the next free number in the project; links to it keep working.
• A tracker project arrives before its issues, and a conversation before its messages, so a new device receives complete data.
• Discussions sync with the team — the messages under issues, wiki pages, boards and other objects.
• Open channels (anyone in the Space can join) sync with the team together with their history. On another member’s Desktop such a channel appears in Discussions: press Channels (find and join open channels) — join it there to read and write. If the channel’s owner makes it invite-only or approval-only, only its members keep receiving it; on the other devices the copy moves to the archive and keeps the messages it already has.
• Direct messages and invite-only or approval channels reach only their members — on each member’s Desktop, with their history. Saved messages reach only your own devices. When a member is added, they receive the history; a removed member stops receiving new messages. Agent rooms stay on the device where they were created.
• Teammates appear on your Desktop by name: on their messages and tasks, and in the people list when you start a direct message or add someone to a channel. A person who has just joined the Space appears within about ten minutes.
• A single object larger than 256 KiB — a very large board or wiki page — stays on this device and is listed in the preview as too large to sync.

A personal Space does not include the Team modules: its sync refuses them with a message that names the module.

Offline work and recovery

You can keep editing local projects while offline. After the connection returns, Desktop resumes from the cursor stored for that profile. A failed page does not advance the cursor, so a restart retries it instead of losing changes.

Remote deletions of selected mocks, API collections, UI-test definitions and fuzz configurations are applied by entity type. A deletion is checked against the local owner or namespace and modification time before it is committed. If you have an unsent local edit of that object, Desktop keeps it and opens a sync conflict instead of deleting it. Replaying the same deletion after a restart is safe. Desktop advances the profile cursor only after every local change on the page has committed.

Deleting a connection profile removes its credential, session metadata and profile-scoped sync conflict history. It does not delete local projects. Before removing the Desktop installation or its data directory, check that every item you need exists on another device or in your connected Space. The selective ZIP export below is not a complete backup or a restore mechanism.

Local deletions of the same selected resource types are also sent as stable deletion records. This includes resources removed through their normal editor and resources moved to the recycle bin as part of a larger cleanup. A failed upload is retried with the same identity; it does not turn the deleted resource back into a live copy.

If the local object is newer, the remote object type is unsupported, or a payload cannot be applied safely, Desktop records the object and reason under Connection → Sync conflicts. The entry remains after restart until you review it; the cursor remains at the previous safe point. Revoking a Cloud device credential or losing the network stops future remote sync for that profile without deleting local projects or affecting another profile.

For a supported selected object, choose Use local, Use remote, Merge or Skip. Desktop first previews the exact action, payload size and SHA-256 fingerprint. The decision is bound to the exact local revision that you reviewed. A concurrent local edit is never overwritten: Desktop stops that decision and leaves the newer revision queued for a fresh comparison. A merged object passes through the same Project and sensitive-data boundary as an ordinary sync batch.

If you edited an object locally while it was deleted in Cloud, the conflict is marked Deleted in Cloud. The Cloud panel shows only the last snapshot for comparison; it is not a live version. Choose Keep local and restore in Cloud to try sending your local copy through normal sync permissions, or Accept Cloud deletion to remove the local copy. Merging is unavailable for a deletion. If the Cloud version or your local edit changes while the decision is open, Desktop keeps your work and asks you to review the new conflict. Skip leaves the conflict unresolved; it does not mean the two devices agree.

After Cloud accepts Use local or Merge, Desktop saves a recovery record before changing the local database. If the local commit is interrupted, retry the same confirmation after restart; Desktop resumes the local half without sending the accepted Cloud change again. A durable local receipt also makes a retry safe if the final conflict status could not be written. If the recovery record itself could not be saved immediately after Cloud accepted the change, inspect both copies before choosing again because the Cloud copy may already have changed.

Compare changes without editing JSON

Choose Merge to open the local, result and server panels. Select each
difference and use Previous difference / Next difference without losing
your choices. Review entire result shows the complete object. Continue to
confirmation only after selecting every difference. Closing the window or
choosing Cancel does not apply a decision.

A common base snapshot for automatic three-way merging is not stored yet.
Changes with unknown ancestry require your choice. Requests with stable IDs and
unchanged ordering can be compared field by field. Reordered arrays, duplicate
headers and protocol changes stay together instead of being merged by line
number. Owner, space and sharing permissions remain unchanged. Missing snapshots
or values that cannot be represented safely prevent structural merging.

If the recorded conflict changes while you review it, reopen the comparison.
Desktop checks the reviewed snapshots before preparing confirmation and checks
the retained conflict again before committing the decision.

When changes arrive

After consent, Desktop sends new and changed objects by itself a few seconds after you save them. Work from your other devices and your teammates arrives:

• when you come back to the Desktop window and the last sync is more than two minutes old;
• when you press Sync now in the account panel (top right), which also shows when this Desktop last synced or why the last sync failed;
• in the background every 30 minutes.

An open list refreshes when new work arrives. An object you received is not sent back as your own change.

Sync status and recovery actions

If the server reports rejected changes without identifying the affected objects
unambiguously, Desktop stops confirming that batch and keeps the local changes
pending. For a mixed result, only accepted exact revisions leave the local
queue. Each rejected revision stays in the durable outbox, is shown in Sync
conflicts after restart, and is withheld from automatic retries until you make
an explicit conflict decision. A newer local revision of the same object remains
independent and can be synchronised. A connection error alone is not proof of
delivery.
For a Company server error, Desktop shows the HTTP status and only a recognised,
fixed refusal identifier. It does not copy the server’s free-form error text or
raw response body into the interface or local logs. A failed push is not
proof that the server did or did not receive the batch; keep the local outbox
until a later sync confirms exact revisions.

Synchronising an API collection does not transfer its ownership or move an
existing collection into another space. If its identifier belongs to another
owner or space, the update is rejected and the existing collection is retained.

If Cloud rejects an upload because its sync authorization is stale, that attempt ends with an error and the local changes remain queued. Desktop does not silently obtain new authorization and resend the write inside that same attempt.

For Cloud, Use local and Merge apply to the remote version recorded in the conflict. If that version has changed meanwhile, Desktop leaves the conflict unresolved instead of overwriting the newer work. It does not automatically retry the decision against a newer version.

Use remote, Merge, Use local and Skip also verify that the local outbox still contains the exact reviewed revision. A newer local edit invalidates the old decision instead of being replaced or silently acknowledged. Open the newly synchronised conflict and compare again.

If a received Cloud object cannot be applied locally, its conflict retains the received version and copy of the object after a restart. Further incoming changes to that object wait for an explicit conflict resolution; Desktop keeps the cursor before the page so those changes can be fetched again afterward.

When Desktop has received a signed read-only Team grant, a warning also appears above the workspace. If the device was offline when access changed, it can only show the new state after reconnecting; Cloud still refuses uploads until the right is restored.

The connection panel distinguishes a final transfer that is pending, partly confirmed, in conflict, retrying, or expired from one Cloud has confirmed and closed. A successful incoming refresh or a count of zero pending changes is not confirmation that an outgoing transfer finished. If the panel says changes remain on this device, keep the Desktop installation and renew write access; do not treat Sync now as proof of an upload. Final transfer is only available when Cloud explicitly admits it for the selected Space; Personal read-only access does not grant it.

A read-only Cloud profile cannot start new local or shared runs in its selected
Space. Runners connected through this Desktop stop claiming new queued jobs
while the read-only Cloud profile is selected; existing results remain visible.
Switch to a separate Local profile if you need to keep working independently
while Cloud access is restored.

Package update state is not synchronised. Checking or importing a Desktop
update neither creates a project batch nor advances a profile cursor. Likewise,
reconnecting sync never installs a package or dismisses update recovery.

Safe local export

In the native Desktop application, choose File → Export mocks and tests… and select a new .zip file. The export currently includes local mocks, API collections, UI-test definitions and fuzz configurations owned by the Desktop user. It works after a Cloud profile is revoked because those items remain local. It does not include every kind of Desktop data, and Desktop cannot restore this ZIP automatically yet.

The archive never includes connection profiles, server addresses or pins, credential references, licences, update state, logs, sessions or raw conflict records. Every JSON file is listed in manifest.json with its byte size and SHA-256 digest. The manifest identifies the active profile kind and, for Cloud, its Space when one is still bound.

Desktop refuses to overwrite an existing destination. It also refuses unsafe paths, duplicate archive entries, unsupported data domains, sensitive field names and recognised live-credential shapes. If one selected object fails these checks, the whole transaction is rejected and no partial destination is retained. Replace embedded credentials with secret references, then export again.

Automation surface

The raw Cloud sync transport is Desktop plumbing, not a customer automation workflow. Its Cloud endpoints are documented in OpenAPI for transport verification, while the local consent controls are available only inside Desktop. Both are intentionally absent from the SDKs, CLI and MCP tools. Use normal project APIs for supported user automation.