Migrate from previous-generation Bytesafe

Review your current Bytesafe setup

The migration goes smoothly when you know what you are replacing, so start with a short inventory. For each Bytesafe registry, note:

• the ecosystem and what the registry is for,
• which packages are private or internal,
• which policies and plugins are enabled, and what each one is meant to achieve,
• upstreams and who owns their credentials,
• users, teams, and CI tokens,
• everywhere clients point at Bytesafe: search for your <workspace>.bytesafe.dev URL in client config files committed to repositories, CI configuration, and build images.

The policies and plugins list becomes your worksheet for the mapping step. Capture the intent behind each one, not just its settings: some are replaced by a different mechanism with the same outcome.

Create your firewalls

A firewall replaces a Bytesafe registry as the thing clients talk to. It holds configuration only, so creating one takes a minute.

Create at least one firewall per ecosystem. Create more when different teams or environments need different rules, for example production and experimentation.

In the dashboard, create a firewall, name it, and pick the ecosystem. The ecosystem's public registry is added as an upstream automatically, so the firewall proxies public packages right away.

For additional firewalls, two fields in the create dialog save repetition:

• Inherit configuration from keeps the new firewall in sync with a parent: rules, exceptions, and upstreams from the parent apply automatically, also when the parent changes later. See Share configuration across firewalls.
• Template copies another firewall's upstreams, rules, and exceptions once, as a starting point you then change freely.

Connect your repository manager

The firewall is not a package store, so private packages are served by your repository manager through the firewall. Skip this step if you have no private packages and fetch directly from public sources.

The standard setup keeps the firewall in front: developers and CI talk to the firewall, and the repository manager is one of its upstreams. On the firewall's Upstreams tab, add the manager's repository URL and credentials, then:

• Enable Internal registry on the upstream if it hosts your internal packages. This replaces the internal flag in Bytesafe: when an internal upstream knows a package name, the firewall serves that name only from internal upstreams, which prevents dependency confusion.
• Set the upstream as the publish target if developers or CI publish through the firewall.

Details, including per-vendor instructions and other layouts such as keeping the repository manager in front, are in Integrate with repository managers.

Move private packages out of Bytesafe

Your repository manager becomes the home of your private packages, so packages stored only in Bytesafe need to move there. Bytesafe pushes stored packages to a configured upstream directly from the UI, which makes this the easy part.

First add the repository manager's hosted repository as an upstream of the Bytesafe registry, with publish credentials. Then push at whichever level fits:

• A whole registry: on the registry's Packages tab, select Push all. Pick the target upstream, and enable Push internal packages only to skip public packages, which the firewall can fetch from the public registry anyway.
• One package: open the package and select Push all versions.
• One version: open the version and select Push.

Versions that already exist at the target are skipped, so a push is safe to run again. Start with one test package, check that it installs from the repository manager, then push the rest and compare package counts.

Keep the Bytesafe registry as it is for now; it stays your fallback until after the switch.

Recreate policies and plugins as rules

This is the heart of the migration. A rule has three parts: which packages it matches, where it applies (version resolution, download, or publish), and what happens on a match (block, log, or both). When a rule blocks something you need anyway, an exception waives it for that package, with a reason and an optional expiry.

Create rules on the firewall's Rules tab. Each linked guide shows the exact settings. Every Bytesafe policy has a replacement:

Plugins map the same way. Most become rules with a selector function: they match what is known about a package rather than its name:

The mapping above only covers what Bytesafe could do. While you are here, also look at the controls that are new: malware blocking, secrets scanning on publish, and trust downgrade detection for npm releases published with weaker provenance than earlier versions, the pattern of an account takeover. And everything is visible: every rule decision lands in the firewall log with the package, rule, and requester, every configuration change in the audit log, and webhooks push both to your own systems.

Move developers and CI

Clients authenticate to the firewall with access tokens, and each install is logged under the identity behind the token. Create Personal Access Tokens for developers and Service Access Tokens for CI systems, one per system so logs stay attributable. GitHub Actions can skip long-lived tokens with Trusted Builders.

Then point each client at the firewall endpoint, shown on the firewall's Setup tab, in the form https://eu-sov-1.bytesafecloud.eu/v1/<namespace-id>/npm/<firewall-id>/ for npm. The ecosystem guides walk the exact configuration per package manager.

Sweep your repositories, CI configuration, and build images for old Bytesafe registry URLs so nothing keeps installing around the firewall.

Test before switching

Run a pilot team or a copy of a real CI pipeline against the new firewall while production still runs on Bytesafe.

When you are unsure what a rule will hit, create it with only Log enabled and Block off. It records every match in the firewall log without failing a single build. Review the matches, add exceptions where needed, then enable Block.

Check that:

• a public package installs through the firewall, and a private one installs from the repository manager,
• each migrated rule fires once and the log entry names the rule, package, and requester,
• a blocked install shows an error with a request ID,
• an exception lets through exactly its package and nothing else.

Switch over

Push any packages added to Bytesafe since your first migration run, then switch developer and CI configuration to the firewall endpoints. Watch the firewall log and your builds for the first days: missing packages and authentication errors show up immediately and are usually a credential or URL detail.

Keep the Bytesafe registry untouched for an agreed period as a fallback. Once the new setup has proven itself, retire the old endpoints and tokens. Do not leave the fallback in place indefinitely: the previous generation is being decommissioned during 2026.