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/install.sh | bash

Or download and run manually:

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

Custom installation directory:

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

Windows (PowerShell as Administrator):

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

Or download and run manually:

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

Using Homebrew (macOS and Linux)#

# Add the ATCR tap
brew tap atcr-io/tap

# 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 GitHub Releases

   • 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.23+)#

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#

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.