Moving an App Between Workspaces

OSC does not provide a direct transfer mechanism for moving a My App (and its connected services) from one workspace to another. Instead, the process is a coordinated recreate-on-destination flow that you drive through your connected AI agent. The app source code stays the same; what moves is the running configuration in the destination workspace.

This guide walks through the full process step by step.

Prerequisites

  • You must be a member of both the source workspace and the destination workspace. Without membership in the destination, there is no target to provision into. If you need to join a workspace, have its owner invite you first.
  • Your AI agent (Claude Desktop, Claude Code, Cursor, or another MCP-capable client) must be connected to OSC. See Enable OSC with AI Agents.
  • The destination workspace must have a plan and token balance sufficient to run the services you intend to recreate there.

Overview

The process has four stages:

  1. Back up any data you need to preserve
  2. Remove the app and its connected services from the source workspace
  3. Switch the AI agent's active workspace to the destination
  4. Recreate the app and its connected services in the destination workspace

Step 1: Back Up Your Data

This is a recreate-on-destination flow, not a live migration. Data held in the source service instances (databases, object storage, etc.) is not transferred automatically. If you need to preserve that data, take a backup before tearing down the source.

Back up databases

Use the create-backup MCP tool or the Databases tab in My Apps:

Back up my PostgreSQL database called mydb

Back up my CouchDB instance called nosql

See Database Backups for the full guide. Backups require a paid plan.

Export from other services

For services that do not use the OSC backup system (MinIO, Valkey, etc.), use the service's own export or dump capability before proceeding.

Step 2: Detach Any Custom Domains

If your app has a custom or managed domain mapped to it, you must remove that mapping before deleting the instance. A domain mapping cannot be transferred directly; you will reattach the domain to the new instance in the destination workspace later.

Via the Web Console

  1. Go to My Apps
  2. Click the Domains tab
  3. Find the domain row for your app and click Delete
  4. Confirm the deletion

After removing the mapping in OSC, delete the corresponding CNAME record from your DNS registrar if you are using a custom domain. For managed domains (e.g., mycoolapp.apps.osaas.io), no DNS change is needed.

Via MCP (AI Agent)

The agent uses the delete-my-domain tool. Provide the service ID for your app's runtime and the instance name:

delete-my-domain
  serviceId: "eyevinn-web-runner"
  instanceName: "myapp"

Step 3: Remove the App and Its Connected Services

Do this while the agent is still connected to the source workspace.

Identify what to remove

If you are unsure which apps and service instances are running, ask the agent to list them:

List my apps

The agent uses list-my-apps (no arguments) and returns each app with its appId. For connected services such as databases, queues, and storage:

List my service instances for eyevinn-postgresql

The agent uses list-service-instances and returns instance names along with the serviceId for each.

Note the appId values and the serviceId plus name of each connected service instance before proceeding.

Delete the app

Ask the agent to delete the app by its appId:

Delete my app called myapp

The agent uses the delete-my-app tool, which takes the appId. This removes the deployment and all resources associated with that app. This action is irreversible. The agent will confirm the app name with you before executing.

Prefer suspend over delete if you want a safety net. If you want to keep the source app running temporarily while you verify the destination setup, ask the agent to "suspend" rather than "delete". Suspension is reversible; deletion is not. Once you have confirmed the destination workspace is working correctly, you can return and delete the suspended source instances.

Delete the connected service instances

Ask the agent to delete each connected service instance by name:

Delete my PostgreSQL instance called mydb
Delete my Valkey instance called mycache

The agent uses the delete-service-instance tool, which takes { serviceId, name }. It will confirm each instance name before deleting. As with the app, you can ask to "suspend" rather than "delete" if you want to preserve the source data temporarily.

Note: Deletion of service instances is irreversible through the platform. Confirm your backups are complete and your domain mapping is detached before proceeding.

Step 4: Switch to the Destination Workspace

Once the source instances are removed (or suspended), switch the AI agent's active workspace to the destination. In OSC, the active workspace is determined by the credentials used when authenticating the MCP connection.

Disconnect the current MCP connection in your AI client, then reconnect. During the OAuth flow you will be presented with a workspace picker. Select the destination workspace.

The agent now operates against the destination workspace for all subsequent actions.

Client-specific instructions

Claude Desktop: Open Settings, go to Connectors, click on the OSC connector, click Disconnect, then click Connect again. The OAuth flow will show the workspace picker; select the destination workspace.

Claude Code: Run the MCP add command again with the connection URL from the destination workspace's Settings/MCP page. The URL includes workspace-scoped credentials, so no OAuth picker is needed.

Cursor: Update ~/.cursor/mcp.json with the personal access token from the destination workspace's Settings/API page, then restart Cursor.

Other clients: Update the Authorization: Bearer header value or equivalent credential field to use a personal access token from the destination workspace.

Step 5: Recreate the App and Its Connected Services

With the agent now active in the destination workspace, provision the stack in the correct order: create any dependent services first, then create the app.

Why order matters

The create-my-app tool accepts optional arguments for a parameter store (configService) and an analytics instance (analyticsService). These must already exist in the destination workspace at the time you call create-my-app, because their names are passed as arguments during creation. Set up your databases and parameter store before deploying the app.

Create the connected services

Ask the agent to create each service instance in the destination workspace:

Create a PostgreSQL database called mydb
Create a Valkey instance called mycache

The agent uses create-service-instance for catalog services. Once the instances are running, retrieve their connection details so you can wire them into the app configuration.

Set up the parameter store

If your app uses a parameter store (App Config Service), create it in the destination workspace and populate it with the connection strings from the new instances:

Set up a parameter store for myapp with DATABASE_URL and CACHE_URL

The agent uses setup-parameter-store to provision a Valkey-backed App Config Service and bind the keys you specify.

Deploy the app

Once dependent services are in place, ask the agent to deploy the app:

Deploy my app from https://github.com/youruser/yourrepo as a Node.js app called myapp,
using the parameter store called myapp-config

The agent uses create-my-app, which takes the repository URL, runtime type, and optional configService and analyticsService bindings.

Set up analytics (if applicable)

If the source app had analytics attached, set it up in the destination workspace:

Set up analytics for my app called myapp

The agent uses setup-analytics to provision a Umami instance and bind it to the app.

Restore your data

Once the database instances are running in the destination workspace, restore your backups:

Restore my PostgreSQL database called mydb from my most recent backup

See Database Backups for the restore flow.

Reattach your custom domain

If you had a custom or managed domain, reattach it to the new instance in the destination workspace:

Create a custom domain myapp.example.com for my app called myapp

For custom domains, the agent will return a new DNS target. Update your CNAME record at your DNS registrar to point to the new value. See Custom Domains for the full guide.

Important Considerations

This is a recreate flow, not a transfer. The running instances in the destination are new. Any state that was not explicitly backed up and restored will not be present.

The app source code stays where it is. The git repository URL does not change. Only the running instances in Kubernetes are recreated. If the repository is private, make sure your access token works from the destination workspace context.

Subscription costs apply in the destination workspace. Each workspace has its own plan and token balance. Services in the destination workspace consume tokens from that workspace's balance, independently of the source workspace.

Managed domain names are global. A managed subdomain such as mycoolapp.apps.osaas.io is reserved across all workspaces. If you removed it in Step 2, it becomes available again and you can claim it in the destination workspace. If another tenant claims it in the meantime, you will need to choose a different subdomain.

Custom domain DNS update. When you reattach a custom domain in the destination workspace, the platform may assign a different DNS target (load balancer address). Always copy the new dnsTarget value from OSC rather than reusing the old one.