-
Notifications
You must be signed in to change notification settings - Fork 1
User Guide: 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.
- 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.
The process has four stages:
- Back up any data you need to preserve
- Remove the app and its connected services from the source workspace
- Switch the AI agent's active workspace to the destination
- Recreate the app and its connected services in the destination workspace
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.
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.
For services that do not use the OSC backup system (MinIO, Valkey, etc.), use the service's own export or dump capability before proceeding.
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.
- Go to My Apps
- Click the Domains tab
- Find the domain row for your app and click Delete
- 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.
delete-my-domain
serviceId: "eyevinn-web-runner"
instanceName: "myapp"
Ask your AI agent to delete the app and any service instances that were created for it in the source workspace. Do this while the agent is still connected to the source workspace.
Example prompt:
Remove my app called myapp and its connected services from this workspace.
The connected services are: a PostgreSQL database called mydb and a Valkey instance called mycache.
The agent will use the relevant MCP tools to delete each instance. If you are unsure which services are connected, ask first:
What services are connected to my app called myapp?
The agent can list your active instances and help you identify the ones to remove.
Note: Deletion is not reversible through the platform. Confirm your backup is complete and your domain mapping is detached before proceeding.
Once the source instances are removed, 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. To switch:
- Disconnect the current MCP connection in your AI client
- Reconnect to
https://mcp.osaas.io/mcp - During the OAuth flow, select the destination workspace when prompted
The agent now operates against the destination workspace for all subsequent actions.
Claude Desktop: Open Settings, go to Connectors, click on the OSC connector, click Disconnect, then click Connect again and authenticate selecting 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.
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.
With the agent now active in the destination workspace, ask it to set up the same stack:
Deploy my app from https://github.com/youruser/yourrepo as a Node.js app called myapp,
create a PostgreSQL database called mydb and a Valkey instance called mycache,
and wire the connection URLs into the app config.
The agent will provision fresh instances in the destination workspace using the same source repository. All instance names, runtime type, and configuration are set during this step.
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.
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.
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.
- Enable OSC with AI Agents — Connect your AI agent to OSC
- AI-Assisted App Management — What the AI agent can do in My Apps
- Database Backups — Back up and restore database instances
- Custom Domains — Attach and detach domain names
- Managing Custom Apps — Restart, rebuild, HA mode, and configuration