Bidirectional Server Data Migration

Direct server-to-server migration of workspaces, projects, environments, and secrets between the default AgentSecrets Server and Self-Hosted AgentSecrets Server instances.

Overview

AgentSecrets provides a direct, zero-touch server-to-server data migration protocol across all deployment models:

• Default Server to Self-Hosted: Migrate workspaces, projects, and secrets from the default AgentSecrets Server (https://api.agentsecrets.tech/api) to a private on-premises or VPC instance.
• Self-Hosted to Default Server: Consolidate private instances into the managed platform.
• Self-Hosted to Self-Hosted: Migrate data between staging, production, or multi-region self-hosted clusters.

The Direct Server-to-Server Protocol

Migration is handled directly between the two server instances using an ephemeral cryptographic handshake:

┌───────────────────────────────┐               ┌───────────────────────────────┐
│     Source Server Instance    │               │  Destination Server Instance  │
│ (Default or Self-Hosted)      │               │ (Default or Self-Hosted)      │
└───────────────┬───────────────┘               └───────────────┬───────────────┘
                │                                               │
 1. User calls  │                                               │
    /token/     │                                               │
 ◄──────────────┤                                               │
 (gets token)   │                                               │
                │                                2. User calls  │
                │                                   /import/    │
                │                                   (source_url │
                │                                   + token)    │
                │                               ├───────────────►
                │                               │               │
                │ 3. POST /api/migration/export/│               │
                │    (Bearer <MIGRATION_TOKEN>) │               │
                │ ◄─────────────────────────────┤               │
                │                               │               │
                │ 4. Streams unwrapped bundle   │               │
                │    (client ciphertexts intact)│               │
                │ ─────────────────────────────►│               │
                │                               │ 5. Re-wraps   │
                │                               │    with local │
                │                               │    Fernet key │
                │                               │    and saves  │

The Zero-Knowledge Guarantee During Migration

At no point during transport or import are secret values decrypted:

1. Client-Side Envelope Preservation: Secrets remain encrypted under their original workspace AES-256-GCM / NaCl SealedBox keys.
2. Server-Side Fernet Layer Swap: The source server strips its outer database encryption layer, and the destination server immediately re-encrypts the ciphertext using its own ENCRYPTION_KEY.
3. No Private Keys on Servers: Neither server ever holds or receives user private keys.
4. Transparent Client Handshake: When users switch their CLI to the destination server, their local OS keychain decrypts their workspace keys seamlessly.

Step-by-Step Migration Walkthrough

1Generate a Migration Token on the Source Server

Log in to the source server and generate an ephemeral 30-minute migration token:

# Point CLI to source server
agentsecrets server set https://api.agentsecrets.tech

# Log in to source account
agentsecrets login

# Generate 30-minute migration token
agentsecrets migrate token

Sample Output:

Migration token generated (valid for 30 minutes):
  eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

2Tender the Token to the Destination Server

Switch your CLI to the destination server and tender the token along with the source server URL:

# Point CLI to destination server
agentsecrets server set https://api.agentsecrets.yourcompany.com

# Log in to destination account
agentsecrets login

# Initiate direct server-to-server migration
agentsecrets migrate --from https://api.agentsecrets.tech --token <MIGRATION_TOKEN>

The destination server connects directly to the source server over TLS, verifies the single-use token, pulls the workspace bundle, re-encrypts the records with its local ENCRYPTION_KEY, and creates all workspaces, projects, environments, and secrets in PostgreSQL.

Airgapped / Offline Fallback (Inline Bundle)

If the source and destination servers cannot communicate directly over the network (e.g. firewalled private VPC or airgapped network), you can export and import an encrypted JSON bundle via the CLI:

# Export bundle from source
agentsecrets server set https://api.agentsecrets.tech
agentsecrets migrate export --output bundle.json

# Import bundle to destination
agentsecrets server set https://api.agentsecrets.yourcompany.com
agentsecrets migrate import bundle.json