Import and export

Export a source directory as an OVPack, import it under a new parent or into another OpenViking service, and verify files, metadata, and retrieval.

Connect to the service

Configure the CLI with a user or admin API key supplied by your administrator to connect to OpenViking. OVPack import and export require API Key authentication with server.root_api_key configured on the server.

To set up a local service, use a separate configuration file and storage directory, configure the models, set server.auth_mode to api_key, and configure server.root_api_key. Start the service, create an account, and add the returned user_key to the CLI configuration. See API Key setup and CLI basics for the steps. When using a new account, import the sample sources below into that account first.

Prepare a source

Connect to the service and complete the import step in Resource retrieval. This example uses viking://resources/onboarding-en-v1. You need read access to the source and write access to the target parent.

ov tree viking://resources/onboarding-en-v1
ov export viking://resources/onboarding-en-v1 ./lighthouse.ovpack

The package contains the selected directory's source files, semantic sidecars, and portable index scalars. This tutorial uses the default export and recomputes vectors on import, calling the destination's embedding model. See OVPack reference for full-account backup and restore.

Import into a new location

ov mkdir viking://resources/onboarding-transfer-v1
ov import ./lighthouse.ovpack viking://resources/onboarding-transfer-v1 --vector-mode recompute

The second argument is the target parent. Save the actual root URI returned by import and use it below. This example normally produces viking://resources/onboarding-transfer-v1/onboarding-en-v1.

The default conflict policy is fail. If the target root exists, choose a new demo parent. overwrite replaces an existing root; skip preserves it. A new directory makes repeat runs easy to compare.

Verify content and indexing

ov tree viking://resources/onboarding-transfer-v1/onboarding-en-v1
ov read viking://resources/onboarding-transfer-v1/onboarding-en-v1/project/project.md
ov read viking://resources/onboarding-transfer-v1/onboarding-en-v1/meeting/meeting.md
ov wait

Compare the four relative source paths, their text, and preserved abstracts and overviews. Vector processing may continue after import returns. Use ov wait to wait for queued processing; it may also wait for other queued work on the service. If the request times out, check ov status and retry later. Search once processing completes without related errors.

ov find "What must be prepared before the Lighthouse pilot?" --uri viking://resources/onboarding-transfer-v1/onboarding-en-v1

Completion means source content matches, required metadata is readable, and relevant material can be retrieved from the new directory. Ranking and scores may vary with destination models and indexing; check whether retrieved sources support the question.

Migrate between services

For example, move the Lighthouse sources from development service A to test service B. The computer running the CLI transfers the data: download an .ovpack from A, then upload it to B. The two services do not need a direct connection.

This example transfers a selected resource directory and keeps the original data in A. Configure B's models, accounts, and credentials separately. See OVPack reference for full-account backup and restore.

Configure both connections

Prepare two services with OVPack support and the authentication setup described above. The account on A needs source read access; the account on B needs target-parent write access. B also needs a working Embedding model. Confirm that B supports the package format exported by A, and pause edits to the sample directory during export so its contents can be compared.

Create two CLI configuration files in one local working directory. Enter each service's actual URL and its account's API key. The following addresses are examples:

ov-a.conf:

{
  "url": "https://openviking-a.example.com",
  "api_key": "your-service-a-user-key"
}

ov-b.conf:

{
  "url": "https://openviking-b.example.com",
  "api_key": "your-service-b-user-key"
}

In a macOS / Linux terminal, use OPENVIKING_CLI_CONFIG_FILE to select the connection for each command. Restrict access to the configuration files, then check connectivity to both services:

chmod 600 ./ov-a.conf ./ov-b.conf
OPENVIKING_CLI_CONFIG_FILE=./ov-a.conf ov health
OPENVIKING_CLI_CONFIG_FILE=./ov-b.conf ov health

Run the remaining commands from this working directory. Keep these files in a controlled local location because they contain access credentials.

Export from A

Confirm that A contains the Lighthouse sources, then download the directory to your computer:

OPENVIKING_CLI_CONFIG_FILE=./ov-a.conf ov tree viking://resources/onboarding-en-v1
OPENVIKING_CLI_CONFIG_FILE=./ov-a.conf ov export viking://resources/onboarding-en-v1 ./lighthouse-a-to-b.ovpack

On success, lighthouse-a-to-b.ovpack appears in the current directory. If you use a different computer to connect to B, transfer this file to it; keep A's credentials on the original computer.

Import into B

Create a new migration parent in B and import the local package:

OPENVIKING_CLI_CONFIG_FILE=./ov-b.conf ov mkdir viking://resources/from-a-v1
OPENVIKING_CLI_CONFIG_FILE=./ov-b.conf ov import ./lighthouse-a-to-b.ovpack viking://resources/from-a-v1 --on-conflict fail --vector-mode recompute

With recompute, B generates vectors using its own Embedding model, accommodating different model configurations across environments. Import calls B's model and incurs its associated costs. If the target root already exists, choose a new parent and retry.

Record the actual root URI returned by import. This example normally produces viking://resources/from-a-v1/onboarding-en-v1, which the commands below use.

Verify in B

Inspect the directory and source text, then wait for background vector processing on B:

OPENVIKING_CLI_CONFIG_FILE=./ov-b.conf ov tree viking://resources/from-a-v1/onboarding-en-v1
OPENVIKING_CLI_CONFIG_FILE=./ov-b.conf ov read viking://resources/from-a-v1/onboarding-en-v1/project/project.md
OPENVIKING_CLI_CONFIG_FILE=./ov-b.conf ov wait

ov wait waits for queued processing and may also be affected by other queued work on B. If the request times out, inspect B's status:

OPENVIKING_CLI_CONFIG_FILE=./ov-b.conf ov status

Wait again later if processing continues. For errors, inspect B's model and storage configuration and server logs. Once processing completes without related errors, search in B:

OPENVIKING_CLI_CONFIG_FILE=./ov-b.conf ov find "What must be prepared before the Lighthouse pilot?" --uri viking://resources/from-a-v1/onboarding-en-v1

Check	Success criterion
Files and text	The four source files in B have the same relative paths and text as in A
Abstracts and overviews	Semantic sidecars preserved in the package are readable in B
Retrieval	Relevant preparation material is found, and the source at each result URI can be read
References and integration	Absolute URIs, service addresses in the text, and the agent's search scope have been checked against their actual locations in B

After verification, update the application or agent with B's service URL, credentials, and resource search scope. Ask the same question and check the answer and citations to confirm that the application uses B's data. Keep the original directory in A for comparison and any later cutover arrangements.

Package and conflict checks

The manifest records files, sizes, and checksums. Missing files, checksum mismatches, or unsupported format versions cause import to fail. Export again and check the transfer if needed. See OVPack reference for vector compatibility, auto/require modes, and archive validation.

Keep the package for comparison if useful. To clean up, identify the imported root under the new parent in Studio and delete the demo content. The original source remains available.