at-container-registry/INSTALLATION.md

Installing ATCR Credential Helper

The ATCR credential helper enables Docker to authenticate with ATCR registries using ATProto device authorization.

Quick Install (Recommended)

Using install script

Linux/macOS:

curl -fsSL https://atcr.io/static/install.sh | bash

Or download and run manually:

curl -fsSLO https://atcr.io/static/install.sh
chmod +x install.sh
./install.sh

Custom installation directory:

INSTALL_DIR=$HOME/.local/bin curl -fsSL https://atcr.io/static/install.sh | bash

Windows (PowerShell as Administrator):

iwr -useb https://atcr.io/static/install.ps1 | iex

Or download and run manually:

Invoke-WebRequest -Uri https://atcr.io/static/install.ps1 -OutFile install.ps1
.\install.ps1

Using Homebrew (macOS and Linux)

# Add the ATCR tap (the main repo itself serves as the tap).
# DID-based URL is stable across any future handle rename.
brew tap atcr/tap https://tangled.org/did:plc:pddp4xt5lgnv2qsegbzzs4xg/at-container-registry

# Install the credential helper
brew install docker-credential-atcr

The Homebrew formula supports:

• macOS: Intel (x86_64) and Apple Silicon (arm64)
• Linux: x86_64 and arm64

Homebrew will automatically download the correct binary for your platform.

Manual Installation

1. Download the binary for your platform from Tangled tags

   • Linux amd64: docker-credential-atcr_VERSION_Linux_x86_64.tar.gz
   • Linux arm64: docker-credential-atcr_VERSION_Linux_arm64.tar.gz
   • macOS amd64: docker-credential-atcr_VERSION_Darwin_x86_64.tar.gz
   • macOS arm64: docker-credential-atcr_VERSION_Darwin_arm64.tar.gz
   • Windows amd64: docker-credential-atcr_VERSION_Windows_x86_64.zip
   • Windows arm64: docker-credential-atcr_VERSION_Windows_arm64.zip

2. Extract and install:

   Linux/macOS:

   tar -xzf docker-credential-atcr_VERSION_OS_ARCH.tar.gz
   sudo install -m 755 docker-credential-atcr /usr/local/bin/
   

   Windows (PowerShell as Administrator):

   Expand-Archive docker-credential-atcr_VERSION_Windows_x86_64.zip
   Move-Item docker-credential-atcr.exe C:\Windows\System32\
   

3. Verify installation:

   docker-credential-atcr version
   

From Source (requires Go 1.26+)

go install atcr.io/cmd/credential-helper@latest
sudo mv $(go env GOPATH)/bin/credential-helper /usr/local/bin/docker-credential-atcr

Configuration

1. Configure Docker

Add the credential helper to Docker's config:

# Create or edit ~/.docker/config.json
cat > ~/.docker/config.json << 'EOF'
{
  "credHelpers": {
    "atcr.io": "atcr"
  }
}
EOF

Or add to existing config:

{
  "credHelpers": {
    "atcr.io": "atcr",
    "docker.io": "desktop"
  }
}

2. Authenticate

The credential helper will automatically trigger authentication when you first push/pull:

docker push atcr.io/yourhandle/myapp:latest

This will:

1. Open your browser for device authorization
2. Display a code to confirm
3. Store credentials in ~/.atcr/device.json
4. Exchange for registry JWT and proceed with push

3. Manual Authentication (optional)

If you prefer to authenticate before pushing:

# This triggers the device flow manually
echo "atcr.io" | ATCR_AUTO_AUTH=1 docker-credential-atcr get > /dev/null

Usage

Once configured, Docker commands work normally:

# Push image
docker push atcr.io/alice.bsky.social/myapp:latest

# Pull image
docker pull atcr.io/bob.bsky.social/coolapp:v1.2.3

# Build and push
docker build -t atcr.io/alice.bsky.social/web:latest .
docker push atcr.io/alice.bsky.social/web:latest

Multiple Registries

The credential helper supports multiple ATCR instances (e.g., production + self-hosted):

{
  "credHelpers": {
    "atcr.io": "atcr",
    "registry.mycompany.com": "atcr"
  }
}

Credentials are stored per AppView URL in ~/.atcr/device.json.

Troubleshooting

"credential helper not found"

Ensure docker-credential-atcr is in your PATH:

which docker-credential-atcr

If not found, add the installation directory to PATH:

export PATH="/usr/local/bin:$PATH"

"No valid credentials found"

Enable auto-auth and retry:

docker push atcr.io/yourhandle/myapp:latest

"authorization failed"

Check that you can access the AppView:

curl -v https://atcr.io/v2/

For local development (HTTP):

{
  "insecure-registries": ["localhost:5000"]
}

Add to /etc/docker/daemon.json and restart Docker:

sudo systemctl restart docker

Logout

To remove stored credentials:

echo "atcr.io" | docker-credential-atcr erase

Or delete the credentials file:

rm ~/.atcr/device.json

Uninstall

# Remove binary
sudo rm /usr/local/bin/docker-credential-atcr

# Remove credentials
rm -rf ~/.atcr

# Remove from Docker config
# Edit ~/.docker/config.json and remove "atcr" from credHelpers

Platform Support

Platform	Arch	Status
Linux	amd64	✅ Supported
Linux	arm64	✅ Supported
macOS	amd64 (Intel)	✅ Supported
macOS	arm64 (Apple Silicon)	✅ Supported
Windows	amd64	✅ Supported
Windows	arm64	✅ Supported

Security

• Credentials are stored in ~/.atcr/device.json with 0600 permissions (owner read/write only)
• Device secrets are issued per-device and can be revoked via the AppView web UI
• Authentication uses ATProto OAuth with device authorization flow
• No passwords are stored locally

Development

See CLAUDE.md for development docs.