# Jylus Migrate

**Assess Chroma Cloud, approve a record copy, verify it and compare retrieval.**

Run the ready-built container on your own machine. Source credentials stay local.
The default assessment makes no Jylus writes and needs no Jylus API key.

[Docker Hub](https://hub.docker.com/r/jylus/jylus-migrate) · [Website guide](https://jylus.ai/tools/chroma) ·
[Technical guide](docs/TECHNICAL-GUIDE.md) · [Qualification and limits](TESTING.md)

This is a **preview record-copy evaluation**, not a drop-in Chroma vector-search
replacement. Original embeddings remain in the private local export. External
dense-vector indexing, equivalent similarity metrics, fork lineage and specialised
hybrid search are not supported. Hosted Chroma Cloud acceptance is still open.

## 1. Configure local credentials

Install Docker with Linux containers. This release is qualified for Linux amd64;
ARM and other SDK versions are not certified. No source download or local build
is needed. Create `secrets/` and `work/` in a new local directory.

Save `secrets/chroma.json` using your own Chroma Cloud credentials:

```json
{"api_key":"YOUR_CHROMA_CLOUD_KEY","tenant":"YOUR_TENANT","database":"YOUR_DATABASE","region":"us"}
```

Use `eu` for the supported European endpoint. Tenant/database may be omitted when
CloudClient can infer them. Use a source key permitted to read the collection.
The tool never creates, updates, deletes or forks your source collection.

Create `migrate.env` with **paths only**:

```dotenv
CHROMA_CREDENTIALS_FILE=/run/secrets/chroma.json
JYLUS_API_KEY_FILE=/run/secrets/jylus.key
```

On Linux/macOS, set `chmod 600 secrets/chroma.json`. Keep keys, exports and the
work directory out of source control. Do not create `jylus.key` for assessment.
Only approved transfers need that separate key with `events:read` and
`events:write` for a Jylus evaluation workspace.

## 2. Discover and assess

**macOS / Linux**, after creating the secret files:

```sh
mkdir -p work
docker run --rm --platform linux/amd64 --pull missing --read-only --memory=768m --cpus=1 --pids-limit=128 \
  --cap-drop=ALL --security-opt=no-new-privileges --tmpfs /tmp:rw,size=128m \
  --user "$(id -u):$(id -g)" --env-file ./migrate.env \
  --mount "type=bind,src=$PWD/secrets,dst=/run/secrets,readonly" \
  --mount "type=bind,src=$PWD/work,dst=/work" \
  docker.io/jylus/jylus-migrate:0.1.1 chroma-cloud
```

**PowerShell**, after creating the same files:

```powershell
New-Item -ItemType Directory -Force -Path work | Out-Null
docker run --rm --platform linux/amd64 --pull missing --read-only --memory=768m --cpus=1 --pids-limit=128 `
  --cap-drop=ALL --security-opt=no-new-privileges --tmpfs /tmp:rw,size=128m `
  --env-file ./migrate.env `
  --mount "type=bind,src=$($PWD.Path)/secrets,dst=/run/secrets,readonly" `
  --mount "type=bind,src=$($PWD.Path)/work,dst=/work" `
  docker.io/jylus/jylus-migrate:0.1.1 chroma-cloud
```

Docker pulls the published image automatically. The command discovers up to
1,000 collections and assesses the first 20, with coverage reported. Add
`--collection "your-collection"` to assess a particular collection. You receive
compatibility findings, sampled storage estimates and a reviewable assessment.
Estimated bytes are not a bill or an index/RAM/replication capacity guarantee.

## 3. Approve a copy

Keep the application on its existing system. Select an intentionally frozen
evaluation collection and review its assessment. Create `secrets/jylus.key`
with your separate evaluation-workspace key; protect it like the source key.
Choose the workspace retention and review its storage cap before transferring.

Append these arguments to the same Docker command, after `chroma-cloud`:

```text
--collection your-frozen-collection --execute --approve REVIEWED_SHA256 --record-storage-only --frozen-source
```

Only explicit approval enables Jylus writes. Compatible text, original IDs,
metadata and provenance go through the public `/api/v1/events` endpoint, at most
100 events and 900,000 encoded bytes per batch. Original vectors remain local.
The tool does not activate extra charges, change your plan or switch traffic.

## 4. Verify, resume and compare

Progress reports verified records. A checkpoint commits only after a durable
receipt, matching integrity digest and exact record readback. Ctrl+C preserves
progress. Resume the same approved command with `--resume`, keeping the same
work directory, target key and batch size. Stable identifiers and idempotency
keys prevent another logical copy within the same job.

Use `--queries /work/queries.json` for representative original-ID and retrieval
comparisons; the [technical guide](docs/TECHNICAL-GUIDE.md) provides the format.
Chroma receives saved source query vectors; Jylus receives the original question
as text. No embedding/model provider is called. Different engines can return
different rankings. Supplied independent relevance judgments are optional, and
missing judgments remain unknown. A successful record copy is not vector parity.

Count verification requires a complete native aggregation, with a 50,000-record
scan bound. Partial counts stay explicitly unverified. The source remains
untouched; reports never automatically approve application cutover.

For the interruption acceptance check, append `--stop-after-batches 1` to the
approved command; exit 75 is expected. Repeat without that option, adding
`--resume`, and confirm counts and integrity. A fresh directory starts a new
evaluation, not a retry of the existing job.

## Support and compatibility

Only Chroma Cloud is currently implemented. Pinecone, Qdrant, pgvector and
Elasticsearch are planned investigations after hosted Chroma acceptance passes.
They are not advertised as available connectors.

See [TESTING.md](TESTING.md) for the 69-test Linux qualification, official SDK
HTTP-fixture limits and 1,001-record real-Jylus interruption/resume evaluation.
Those results do not certify hosted Chroma Cloud or vector-search equivalence.

Report issues at [this repository](https://github.com/jylusAus/jylus/issues), omitting keys and customer
records. Security concerns: see [SECURITY.md](SECURITY.md).

The Apache 2.0 licence covers this migration client only. Required Qdrant
attribution is in [NOTICE](NOTICE). The proprietary Jylus engine is not included
or licensed by this repository or container.