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/static/install.sh | bash
12```
13
14Or download and run manually:
15
16```bash
17curl -fsSLO https://atcr.io/static/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/static/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 (the main repo itself serves as the tap).
44# DID-based URL is stable across any future handle rename.
45brew tap atcr/tap https://tangled.org/did:plc:pddp4xt5lgnv2qsegbzzs4xg/at-container-registry
46
47# Install the credential helper
48brew install docker-credential-atcr
49```
50
51The Homebrew formula supports:
52- **macOS**: Intel (x86_64) and Apple Silicon (arm64)
53- **Linux**: x86_64 and arm64
54
55Homebrew will automatically download the correct binary for your platform.
56
57### Manual Installation
58
591. **Download the binary** for your platform from [Tangled tags](https://tangled.org/evan.jarrett.net/at-container-registry/tags)
60
61 - Linux amd64: `docker-credential-atcr_VERSION_Linux_x86_64.tar.gz`
62 - Linux arm64: `docker-credential-atcr_VERSION_Linux_arm64.tar.gz`
63 - macOS amd64: `docker-credential-atcr_VERSION_Darwin_x86_64.tar.gz`
64 - macOS arm64: `docker-credential-atcr_VERSION_Darwin_arm64.tar.gz`
65 - Windows amd64: `docker-credential-atcr_VERSION_Windows_x86_64.zip`
66 - Windows arm64: `docker-credential-atcr_VERSION_Windows_arm64.zip`
67
682. **Extract and install**:
69
70 **Linux/macOS:**
71 ```bash
72 tar -xzf docker-credential-atcr_VERSION_OS_ARCH.tar.gz
73 sudo install -m 755 docker-credential-atcr /usr/local/bin/
74 ```
75
76 **Windows (PowerShell as Administrator):**
77 ```powershell
78 Expand-Archive docker-credential-atcr_VERSION_Windows_x86_64.zip
79 Move-Item docker-credential-atcr.exe C:\Windows\System32\
80 ```
81
823. **Verify installation**:
83
84 ```bash
85 docker-credential-atcr version
86 ```
87
88## Configuration
89
90### 1. Configure Docker
91
92Add the credential helper to Docker's config:
93
94```bash
95# Create or edit ~/.docker/config.json
96cat > ~/.docker/config.json << 'EOF'
97{
98 "credHelpers": {
99 "atcr.io": "atcr"
100 }
101}
102EOF
103```
104
105Or add to existing config:
106
107```json
108{
109 "credHelpers": {
110 "atcr.io": "atcr",
111 "docker.io": "desktop"
112 }
113}
114```
115
116### 2. Authenticate
117
118The credential helper will automatically trigger authentication when you first push/pull:
119
120```bash
121docker push atcr.io/yourhandle/myapp:latest
122```
123
124This will:
1251. Open your browser for device authorization
1262. Display a code to confirm
1273. Store credentials in `~/.atcr/device.json`
1284. Exchange for registry JWT and proceed with push
129
130### 3. Manual Authentication (optional)
131
132If you prefer to authenticate before pushing:
133
134```bash
135# This triggers the device flow manually
136echo "atcr.io" | ATCR_AUTO_AUTH=1 docker-credential-atcr get > /dev/null
137```
138
139## Usage
140
141Once configured, Docker commands work normally:
142
143```bash
144# Push image
145docker push atcr.io/alice.bsky.social/myapp:latest
146
147# Pull image
148docker pull atcr.io/bob.bsky.social/coolapp:v1.2.3
149
150# Build and push
151docker build -t atcr.io/alice.bsky.social/web:latest .
152docker push atcr.io/alice.bsky.social/web:latest
153```
154
155## Multiple Registries
156
157The credential helper supports multiple ATCR instances (e.g., production + self-hosted):
158
159```json
160{
161 "credHelpers": {
162 "atcr.io": "atcr",
163 "registry.mycompany.com": "atcr"
164 }
165}
166```
167
168Credentials are stored per AppView URL in `~/.atcr/device.json`.
169
170## Troubleshooting
171
172### "credential helper not found"
173
174Ensure `docker-credential-atcr` is in your PATH:
175
176```bash
177which docker-credential-atcr
178```
179
180If not found, add the installation directory to PATH:
181
182```bash
183export PATH="/usr/local/bin:$PATH"
184```
185
186### "No valid credentials found"
187
188Enable auto-auth and retry:
189
190```bash
191docker push atcr.io/yourhandle/myapp:latest
192```
193
194### "authorization failed"
195
196Check that you can access the AppView:
197
198```bash
199curl -v https://atcr.io/v2/
200```
201
202For local development (HTTP):
203
204```json
205{
206 "insecure-registries": ["localhost:5000"]
207}
208```
209
210Add to `/etc/docker/daemon.json` and restart Docker:
211
212```bash
213sudo systemctl restart docker
214```
215
216### Logout
217
218To remove stored credentials:
219
220```bash
221echo "atcr.io" | docker-credential-atcr erase
222```
223
224Or delete the credentials file:
225
226```bash
227rm ~/.atcr/device.json
228```
229
230## Uninstall
231
232```bash
233# Remove binary
234sudo rm /usr/local/bin/docker-credential-atcr
235
236# Remove credentials
237rm -rf ~/.atcr
238
239# Remove from Docker config
240# Edit ~/.docker/config.json and remove "atcr" from credHelpers
241```
242
243## Platform Support
244
245| Platform | Arch | Status |
246|----------|------|--------|
247| Linux | amd64 | ✅ Supported |
248| Linux | arm64 | ✅ Supported |
249| macOS | amd64 (Intel) | ✅ Supported |
250| macOS | arm64 (Apple Silicon) | ✅ Supported |
251| Windows | amd64 | ✅ Supported |
252| Windows | arm64 | ✅ Supported |
253
254## Security
255
256- Credentials are stored in `~/.atcr/device.json` with `0600` permissions (owner read/write only)
257- Device secrets are issued per-device and can be revoked via the AppView web UI
258- Authentication uses ATProto OAuth with device authorization flow
259- No passwords are stored locally
260
261## Development
262
263See [CLAUDE.md](./CLAUDE.md#credential-helper-cmd-credential-helper) for development docs.