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)#

You can read the full manifest spec here, but the dependencies block is the real interesting bit. Dependencies for your workflow, like Go, Node.js, Python etc. can be pulled in from nixpkgs. Nixpkgs—for the uninitiated—is a vast collection of packages for the Nix package manager. Fortunately, you needn’t know nor care about Nix to use it! Just head to https://search.nixos.org to find your package of choice (I’ll bet 1€ that it’s there1), toss it in the list and run your build. The Nix-savvy of you lot will be happy to know that you can use custom registries too.

brew tap atcr-io/tap
brew install docker-credential-atcr

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.