A container registry that uses the AT Protocol for manifest storage and S3 for blob storage.
atcr.io
docker
container
atproto
go
1# Installing ATCR Credential Helper
2
3The ATCR credential helper enables Docker to authenticate with ATCR registries using ATProto device authorization.
4
5## Quick Install (Recommended)
6
7### Using install script
8
9**Linux/macOS:**
10```bash
11curl -fsSL https://atcr.io/install.sh | bash
12```
13
14Or download and run manually:
15
16```bash
17curl -fsSLO https://atcr.io/install.sh
18chmod +x install.sh
19./install.sh
20```
21
22Custom installation directory:
23
24```bash
25INSTALL_DIR=$HOME/.local/bin curl -fsSL https://atcr.io/install.sh | bash
26```
27
28**Windows (PowerShell as Administrator):**
29```powershell
30iwr -useb https://atcr.io/install.ps1 | iex
31```
32
33Or download and run manually:
34
35```powershell
36Invoke-WebRequest -Uri https://atcr.io/install.ps1 -OutFile install.ps1
37.\install.ps1
38```
39
40### Using Homebrew (macOS and Linux)
41
42```bash
43# Add the ATCR tap
44brew tap atcr-io/tap
45
46# Install the credential helper
47brew install docker-credential-atcr
48```
49
50The Homebrew formula supports:
51- **macOS**: Intel (x86_64) and Apple Silicon (arm64)
52- **Linux**: x86_64 and arm64
53
54Homebrew will automatically download the correct binary for your platform.
55
56### Manual Installation
57
581. **Download the binary** for your platform from [GitHub Releases](https://github.com/atcr-io/atcr/releases)
59
60 - Linux amd64: `docker-credential-atcr_VERSION_Linux_x86_64.tar.gz`
61 - Linux arm64: `docker-credential-atcr_VERSION_Linux_arm64.tar.gz`
62 - macOS amd64: `docker-credential-atcr_VERSION_Darwin_x86_64.tar.gz`
63 - macOS arm64: `docker-credential-atcr_VERSION_Darwin_arm64.tar.gz`
64 - Windows amd64: `docker-credential-atcr_VERSION_Windows_x86_64.zip`
65 - Windows arm64: `docker-credential-atcr_VERSION_Windows_arm64.zip`
66
672. **Extract and install**:
68
69 **Linux/macOS:**
70 ```bash
71 tar -xzf docker-credential-atcr_VERSION_OS_ARCH.tar.gz
72 sudo install -m 755 docker-credential-atcr /usr/local/bin/
73 ```
74
75 **Windows (PowerShell as Administrator):**
76 ```powershell
77 Expand-Archive docker-credential-atcr_VERSION_Windows_x86_64.zip
78 Move-Item docker-credential-atcr.exe C:\Windows\System32\
79 ```
80
813. **Verify installation**:
82
83 ```bash
84 docker-credential-atcr version
85 ```
86
87### From Source (requires Go 1.23+)
88
89```bash
90go install atcr.io/cmd/credential-helper@latest
91sudo mv $(go env GOPATH)/bin/credential-helper /usr/local/bin/docker-credential-atcr
92```
93
94## Configuration
95
96### 1. Configure Docker
97
98Add the credential helper to Docker's config:
99
100```bash
101# Create or edit ~/.docker/config.json
102cat > ~/.docker/config.json << 'EOF'
103{
104 "credHelpers": {
105 "atcr.io": "atcr"
106 }
107}
108EOF
109```
110
111Or add to existing config:
112
113```json
114{
115 "credHelpers": {
116 "atcr.io": "atcr",
117 "docker.io": "desktop"
118 }
119}
120```
121
122### 2. Authenticate
123
124The credential helper will automatically trigger authentication when you first push/pull:
125
126```bash
127docker push atcr.io/yourhandle/myapp:latest
128```
129
130This will:
1311. Open your browser for device authorization
1322. Display a code to confirm
1333. Store credentials in `~/.atcr/device.json`
1344. Exchange for registry JWT and proceed with push
135
136### 3. Manual Authentication (optional)
137
138If you prefer to authenticate before pushing:
139
140```bash
141# This triggers the device flow manually
142echo "atcr.io" | ATCR_AUTO_AUTH=1 docker-credential-atcr get > /dev/null
143```
144
145## Usage
146
147Once configured, Docker commands work normally:
148
149```bash
150# Push image
151docker push atcr.io/alice.bsky.social/myapp:latest
152
153# Pull image
154docker pull atcr.io/bob.bsky.social/coolapp:v1.2.3
155
156# Build and push
157docker build -t atcr.io/alice.bsky.social/web:latest .
158docker push atcr.io/alice.bsky.social/web:latest
159```
160
161## Multiple Registries
162
163The credential helper supports multiple ATCR instances (e.g., production + self-hosted):
164
165```json
166{
167 "credHelpers": {
168 "atcr.io": "atcr",
169 "registry.mycompany.com": "atcr"
170 }
171}
172```
173
174Credentials are stored per AppView URL in `~/.atcr/device.json`.
175
176## Troubleshooting
177
178### "credential helper not found"
179
180Ensure `docker-credential-atcr` is in your PATH:
181
182```bash
183which docker-credential-atcr
184```
185
186If not found, add the installation directory to PATH:
187
188```bash
189export PATH="/usr/local/bin:$PATH"
190```
191
192### "No valid credentials found"
193
194Enable auto-auth and retry:
195
196```bash
197docker push atcr.io/yourhandle/myapp:latest
198```
199
200### "authorization failed"
201
202Check that you can access the AppView:
203
204```bash
205curl -v https://atcr.io/v2/
206```
207
208For local development (HTTP):
209
210```json
211{
212 "insecure-registries": ["localhost:5000"]
213}
214```
215
216Add to `/etc/docker/daemon.json` and restart Docker:
217
218```bash
219sudo systemctl restart docker
220```
221
222### Logout
223
224To remove stored credentials:
225
226```bash
227echo "atcr.io" | docker-credential-atcr erase
228```
229
230Or delete the credentials file:
231
232```bash
233rm ~/.atcr/device.json
234```
235
236## Uninstall
237
238```bash
239# Remove binary
240sudo rm /usr/local/bin/docker-credential-atcr
241
242# Remove credentials
243rm -rf ~/.atcr
244
245# Remove from Docker config
246# Edit ~/.docker/config.json and remove "atcr" from credHelpers
247```
248
249## Platform Support
250
251| Platform | Arch | Status |
252|----------|------|--------|
253| Linux | amd64 | ✅ Supported |
254| Linux | arm64 | ✅ Supported |
255| macOS | amd64 (Intel) | ✅ Supported |
256| macOS | arm64 (Apple Silicon) | ✅ Supported |
257| Windows | amd64 | ✅ Supported |
258| Windows | arm64 | ✅ Supported |
259
260## Security
261
262- Credentials are stored in `~/.atcr/device.json` with `0600` permissions (owner read/write only)
263- Device secrets are issued per-device and can be revoked via the AppView web UI
264- Authentication uses ATProto OAuth with device authorization flow
265- No passwords are stored locally
266
267## Development
268
269See [CLAUDE.md](./CLAUDE.md#credential-helper-cmd-credential-helper) for development docs.