---
title: Code Registry
description: Use Cuitty Code Registry for npm, Cargo, OCI, and PyPI packages.
section: Code
order: 20
updatedAt: 2026-05-24
slug: code/registry
---
Cuitty Code Registry stores packages and artifacts owned by Cuitty users and organizations. It uses the same users, organizations, slugs, teams, apps, audit logs, and SpiceDB permissions as repositories.

Packages default to private. Moving a package to organization or public visibility requires an explicit Cuitty visibility change and audit event.

## Required services

- Cuitty Git API for package metadata and protocol endpoints.
- Database for package records, versions, dist tags, visibility, ownership, and artifact references.
- SpiceDB for namespace, package, publish, install, and view permissions.
- Registry artifact storage for tarballs, crates, wheels, and image layers.
- Airflow for publish validation, scans, provenance, index updates, and replication when enabled.
- Optional object storage for larger deployments.

## Environment variables

```bash
PUBLIC_API_URL=http://localhost:4351
AUTH_ISSUER=http://localhost:7705
AUTH_CLIENT_ID=cuitty-git
SPICEDB_ENDPOINT=http://localhost:50051
SPICEDB_PRESHARED_KEY=dev-secret
AIRFLOW_URL=http://localhost:8080
REGISTRY_STORAGE_URL=file:///var/lib/cuitty/registry
```

## Permissions model

Registry namespaces and packages have separate relationships. Namespace owners can administer the namespace and publish packages. Package owners and package maintainers can manage package metadata and versions. Public and organization visibility map to explicit SpiceDB relationships, and unauthorized callers may receive `404` for private packages.

## npm

Use the npm endpoint for scoped and unscoped package metadata, publish, and tarball download:

```bash
npm config set @acme:registry http://localhost:4351/api/v1/npm/
npm login --registry http://localhost:4351/api/v1/npm/
npm publish --registry http://localhost:4351/api/v1/npm/
npm install @acme/button --registry http://localhost:4351/api/v1/npm/
```

For scoped packages, the npm scope must match the Cuitty owner namespace. For example, `@acme/button` must publish under the `acme` owner.

## Cargo

Configure a sparse registry:

```toml
[registries.cuitty]
index = "sparse+http://localhost:4351/api/v1/cargo/index/"
```

Then publish or install with:

```bash
cargo publish --registry cuitty
cargo add package-name --registry cuitty
```

## PyPI

Upload with Twine and install from the simple index:

```bash
twine upload --repository-url http://localhost:4351/api/v1/pypi/ dist/*
pip install --index-url http://localhost:4351/api/v1/pypi/simple/ package-name
```

Package names should be normalized consistently between upload metadata, simple index pages, and install URLs.

## Docker and OCI

Push images through the registry host:

```bash
docker login localhost:4351
docker tag image localhost:4351/acme/image:tag
docker push localhost:4351/acme/image:tag
docker pull localhost:4351/acme/image:tag
```

Operators should decide whether tags are mutable, immutable, or protected by policy before opening production pushes.

## Common workflows

1. Create or claim a registry namespace for a user or organization.
2. Publish a package version through the native package manager.
3. Store package metadata, files, checksums, and visibility.
4. Update protocol indexes or tags.
5. Install through the native package manager using the same registry URL.

## Failure modes and recovery

- `404` for a private package can be intentional when the caller lacks view permission.
- `403` means the package exists but the caller is authenticated without the required permission.
- Artifact storage failures can leave metadata and files out of sync; check API logs, package version records, and storage references before allowing new publishes.
- Scope mismatch errors mean the package name does not match the target Cuitty owner namespace.

## Related pages

- [npm Packages](/docs/code/npm)
- [Cargo Crates](/docs/code/cargo)
- [PyPI Packages](/docs/code/pypi)
- [OCI and Docker Images](/docs/code/oci)
- [Authorization with SpiceDB](/docs/code/authz-spicedb)
- [Operator runbook](/docs/code/operator-runbook)