remotes.md Raw History Folder

Remotes Commands

Manage saved remote Gordon instances for easier CLI usage.

gordon remotes

Subcommands

Subcommand	Description
`list`	List saved remotes
`add`	Add a new remote
`remove`	Remove a saved remote
`use`	Set active remote
`set-token`	Set or update token for a remote

gordon remotes list

List all saved remotes.

gordon remotes list

Output

Saved Remotes

Name            URL                                    Token           Status
-------------------------------------------------------------------------------
prod            https://gordon.mydomain.com            $PROD_TOKEN     active
staging         https://staging.mydomain.com           set
dev             https://dev.mydomain.com               none

gordon remotes add

Add a new remote.

gordon remotes add <name> <url> [options]

Arguments

Argument	Description
`<name>`	Name for the remote (e.g., `prod`, `staging`)
`<url>`	Gordon URL (the `gordon_domain` from remote config)

Note: <url> must match the configured gordon_domain. Older servers that only set registry_domain may need a config migration before remote CLI works.

Options

Option	Description
`--token`	Store token directly in config
`--token-env`	Store environment variable name (token resolved at runtime)
`--insecure`	Skip TLS certificate verification for this remote

Examples

# Basic (no token)
gordon remotes add prod https://gordon.mydomain.com

# With direct token
gordon remotes add prod https://gordon.mydomain.com --token eyJ...

# With environment variable reference (recommended)
gordon remotes add prod https://gordon.mydomain.com --token-env PROD_TOKEN

# With self-signed certificate
gordon remotes add dev https://dev.internal --insecure

Token Security

Option 1: pass Store (Recommended)

When pass is installed and initialized, Gordon stores tokens encrypted via GPG automatically. No extra flags are needed -- gordon auth login and gordon remotes set-token use pass when available.

Tokens are stored at the path gordon/remotes/<name>/token inside the pass store. If pass is unavailable, Gordon falls back to plaintext config with a warning.

Option 2: Environment Variable Reference

gordon remotes add prod https://gordon.mydomain.com --token-env PROD_TOKEN

The remotes.toml stores only the variable name:

[remotes.prod]
url = "https://gordon.mydomain.com"
token_env = "PROD_TOKEN"

At runtime, Gordon reads $PROD_TOKEN from the environment.

Option 3: Direct Token Storage

gordon remotes add prod https://gordon.mydomain.com --token eyJ...

The token is stored directly in ~/.config/gordon/remotes.toml. Ensure restricted permissions:

chmod 600 ~/.config/gordon/remotes.toml

gordon remotes remove

Remove a saved remote.

gordon remotes remove <name>
gordon remotes remove <name> --force  # Skip confirmation

Arguments

Argument	Description
`<name>`	Name of the remote to remove

Options

Option	Description
`--force`	Skip confirmation prompt

Example

gordon remotes remove staging

gordon remotes use

Set the active remote.

gordon remotes use <name>

Arguments

Argument	Description
`<name>`	Name of the remote to set as active

Description

When a remote is active, it's used automatically for most remote-capable commands without needing to specify --remote and --token.

If no remote is active and you do not pass --remote, Gordon can also auto-infer a saved remote for gordon images push and gordon images tags <repository>. It only auto-selects when exactly one saved remote matches. Ambiguous matches and probe failures require an explicit --remote.

gordon remotes use prod
gordon apps list        # Uses prod remote automatically
gordon daemon status    # Uses prod remote automatically

Example

gordon remotes use prod

gordon remotes set-token

Set or update the authentication token for a saved remote.

gordon remotes set-token <name> <token>

Arguments

Argument	Description
`<name>`	Name of the remote
`<token>`	The JWT token to set

Description

This command is useful when:

You have a pre-generated token from gordon auth token generate
You want to update an expired token

Examples

# Set token for prod remote
gordon remotes set-token prod eyJhbGciOiJIUzI1NiIs...

# Set token from file
gordon remotes set-token staging $(cat token.txt)

# Set token from environment variable
gordon remotes set-token prod "$GORDON_TOKEN"

Output

✓ Token updated for remote 'prod'

Configuration File

Remotes are stored in ~/.config/gordon/remotes.toml:

active = "prod"

[remotes.prod]
url = "https://gordon.mydomain.com"
token_env = "PROD_TOKEN"
insecure_tls = true

[remotes.staging]
url = "https://staging.mydomain.com"
token = "eyJ..."

Resolution Precedence

When multiple sources specify remote or token, the CLI uses this priority:

For aggregate views, --remote and GORDON_REMOTE are the explicit single-target selectors. Without either one, those commands aggregate local + saved remotes even when an active remote exists. Auto-inference is not used for those aggregate views.

Remote target selection:

--remote flag
GORDON_REMOTE environment variable
Active remote from remotes.toml
Auto-inferred saved remote for supported target-based commands

Token:

--token flag
GORDON_TOKEN environment variable
Token from client config (gordon.toml)
pass store (gordon/remotes/<name>/token)
Token from active remote in remotes.toml

Insecure TLS:

--insecure flag
GORDON_INSECURE environment variable (true/false)
[client] insecure_tls in gordon.toml
insecure_tls from the selected remote in remotes.toml

This allows overriding specific values while keeping defaults:

# Force one target
GORDON_REMOTE=prod gordon daemon status

Workflow Examples

Multi-Environment Setup

# Add all environments
gordon remotes add prod https://gordon.example.com --token-env PROD_TOKEN
gordon remotes add staging https://gordon.staging.example.com --token-env STAGING_TOKEN
gordon remotes add dev https://gordon.dev.example.com --token-env DEV_TOKEN

# Work with prod
gordon remotes use prod
gordon apps list
gordon daemon status

# Switch to staging
gordon remotes use staging
GORDON_REMOTE=staging gordon daemon status

CI/CD Pipeline

# GitHub Actions example
env:
  GORDON_REMOTE: ${{ secrets.GORDON_URL }}
  GORDON_TOKEN: ${{ secrets.GORDON_TOKEN }}

steps:
  - name: Push to Gordon
    run: |
      gordon images push myapp --build --remote ${{ secrets.GORDON_URL }}

Compare Environments

# Compare one target at a time
gordon daemon status --remote https://gordon.example.com --token $PROD_TOKEN
GORDON_REMOTE=staging gordon daemon status

# Or switch between active remotes for other commands
gordon remotes use prod && gordon apps list
gordon remotes use staging && gordon apps list

Private Admin + Wildcard App Domains

Recommended default: use your normal Gordon admin domain with a valid public certificate.

# ~/.config/gordon/remotes.toml
active = "prod"

[remotes.prod]
url = "https://gordon.example.com"
token_env = "GORDON_TOKEN"

A common Tailscale setup is to point your domain's DNS at the machine's Tailscale IP (Cloudflare DNS-only / grey cloud). Since the server isn't publicly reachable, there is no external CA to issue a trusted certificate — Gordon's internal CA handles TLS automatically. Clients need to trust the internal CA:

insecure_tls = true on the remote — skips certificate verification entirely
sudo gordon ca install — on the Gordon host only: installs the root CA into system, Firefox, and Java trust stores
gordon ca export --remote <name> --out gordon-ca.crt — fetches the root CA PEM from the remote for manual installation
Visit https://<gordon-host>/.well-known/gordon/ca (or your mapped edge address) in a browser — onboarding page with downloads for macOS, Linux, Windows, iOS, and Android

If you have your own certificate for the domain (e.g. from a corporate CA), you can provide it via tls_cert_file/tls_key_file — see Server Configuration. The static cert is served for SNI-matching domains; everything else falls through to the internal CA.

insecure_tls only affects CLI -> Gordon admin HTTPS verification. It does not change runtime routing: the reverse proxy can still serve wildcard app domains like *.example.com.

Migration from [client] Config

The [client] section in gordon.toml is deprecated. On first run, Gordon auto-migrates it to a default remote entry in remotes.toml and sets it as active. No manual action needed.

source

1# Remotes Commands
2
3Manage saved remote Gordon instances for easier CLI usage.
4
5## gordon remotes
6
7### Subcommands
8
9| Subcommand | Description |
10|------------|-------------|
11| `list` | List saved remotes |
12| `add` | Add a new remote |
13| `remove` | Remove a saved remote |
14| `use` | Set active remote |
15| `set-token` | Set or update token for a remote |
16
17---
18
19## gordon remotes list
20
21List all saved remotes.
22
23```bash
24gordon remotes list
25```
26
27### Output
28
29```
30Saved Remotes
31
32Name            URL                                    Token           Status
33-------------------------------------------------------------------------------
34prod            https://gordon.mydomain.com            $PROD_TOKEN     active
35staging         https://staging.mydomain.com           set
36dev             https://dev.mydomain.com               none
37```
38
39---
40
41## gordon remotes add
42
43Add a new remote.
44
45```bash
46gordon remotes add <name> <url> [options]
47```
48
49### Arguments
50
51| Argument | Description |
52|----------|-------------|
53| `<name>` | Name for the remote (e.g., `prod`, `staging`) |
54| `<url>` | Gordon URL (the `gordon_domain` from remote config) |
55
56> **Note:** `<url>` must match the configured `gordon_domain`. Older servers that only set `registry_domain` may need a config migration before remote CLI works.
57
58### Options
59
60| Option | Description |
61|--------|-------------|
62| `--token` | Store token directly in config |
63| `--token-env` | Store environment variable name (token resolved at runtime) |
64| `--insecure` | Skip TLS certificate verification for this remote |
65
66### Examples
67
68```bash
69# Basic (no token)
70gordon remotes add prod https://gordon.mydomain.com
71
72# With direct token
73gordon remotes add prod https://gordon.mydomain.com --token eyJ...
74
75# With environment variable reference (recommended)
76gordon remotes add prod https://gordon.mydomain.com --token-env PROD_TOKEN
77
78# With self-signed certificate
79gordon remotes add dev https://dev.internal --insecure
80```
81
82### Token Security
83
84**Option 1: pass Store (Recommended)**
85
86When [pass](https://www.passwordstore.org/) is installed and initialized, Gordon stores tokens encrypted via GPG automatically. No extra flags are needed -- `gordon auth login` and `gordon remotes set-token` use `pass` when available.
87
88Tokens are stored at the path `gordon/remotes/<name>/token` inside the pass store. If `pass` is unavailable, Gordon falls back to plaintext config with a warning.
89
90**Option 2: Environment Variable Reference**
91
92```bash
93gordon remotes add prod https://gordon.mydomain.com --token-env PROD_TOKEN
94```
95
96The `remotes.toml` stores only the variable name:
97
98```toml
99[remotes.prod]
100url = "https://gordon.mydomain.com"
101token_env = "PROD_TOKEN"
102```
103
104At runtime, Gordon reads `$PROD_TOKEN` from the environment.
105
106**Option 3: Direct Token Storage**
107
108```bash
109gordon remotes add prod https://gordon.mydomain.com --token eyJ...
110```
111
112The token is stored directly in `~/.config/gordon/remotes.toml`. Ensure restricted permissions:
113
114```bash
115chmod 600 ~/.config/gordon/remotes.toml
116```
117
118---
119
120## gordon remotes remove
121
122Remove a saved remote.
123
124```bash
125gordon remotes remove <name>
126gordon remotes remove <name> --force  # Skip confirmation
127```
128
129### Arguments
130
131| Argument | Description |
132|----------|-------------|
133| `<name>` | Name of the remote to remove |
134
135### Options
136
137| Option | Description |
138|--------|-------------|
139| `--force` | Skip confirmation prompt |
140
141### Example
142
143```bash
144gordon remotes remove staging
145```
146
147---
148
149## gordon remotes use
150
151Set the active remote.
152
153```bash
154gordon remotes use <name>
155```
156
157### Arguments
158
159| Argument | Description |
160|----------|-------------|
161| `<name>` | Name of the remote to set as active |
162
163### Description
164
165When a remote is active, it's used automatically for most remote-capable commands without needing to specify `--remote` and `--token`.
166
167If no remote is active and you do not pass `--remote`, Gordon can also auto-infer a saved remote for `gordon images push` and `gordon images tags <repository>`. It only auto-selects when exactly one saved remote matches. Ambiguous matches and probe failures require an explicit `--remote`.
168
169```bash
170gordon remotes use prod
171gordon apps list        # Uses prod remote automatically
172gordon daemon status    # Uses prod remote automatically
173```
174
175### Example
176
177```bash
178gordon remotes use prod
179```
180
181---
182
183## gordon remotes set-token
184
185Set or update the authentication token for a saved remote.
186
187```bash
188gordon remotes set-token <name> <token>
189```
190
191### Arguments
192
193| Argument | Description |
194|----------|-------------|
195| `<name>` | Name of the remote |
196| `<token>` | The JWT token to set |
197
198### Description
199
200This command is useful when:
201
202- You have a pre-generated token from `gordon auth token generate`
203- You want to update an expired token
204
205### Examples
206
207```bash
208# Set token for prod remote
209gordon remotes set-token prod eyJhbGciOiJIUzI1NiIs...
210
211# Set token from file
212gordon remotes set-token staging $(cat token.txt)
213
214# Set token from environment variable
215gordon remotes set-token prod "$GORDON_TOKEN"
216```
217
218### Output
219
220```
221✓ Token updated for remote 'prod'
222```
223
224---
225
226## Configuration File
227
228Remotes are stored in `~/.config/gordon/remotes.toml`:
229
230```toml
231active = "prod"
232
233[remotes.prod]
234url = "https://gordon.mydomain.com"
235token_env = "PROD_TOKEN"
236insecure_tls = true
237
238[remotes.staging]
239url = "https://staging.mydomain.com"
240token = "eyJ..."
241```
242
243## Resolution Precedence
244
245When multiple sources specify remote or token, the CLI uses this priority:
246
247For aggregate views, `--remote` and `GORDON_REMOTE` are the explicit single-target selectors. Without either one, those commands aggregate local + saved remotes even when an active remote exists.
248Auto-inference is not used for those aggregate views.
249
250**Remote target selection:**
2511. `--remote` flag
2522. `GORDON_REMOTE` environment variable
2533. Active remote from `remotes.toml`
2544. Auto-inferred saved remote for supported target-based commands
255
256**Token:**
2571. `--token` flag
2582. `GORDON_TOKEN` environment variable
2593. Token from client config (`gordon.toml`)
2604. `pass` store (`gordon/remotes/<name>/token`)
2615. Token from active remote in `remotes.toml`
262
263**Insecure TLS:**
2641. `--insecure` flag
2652. `GORDON_INSECURE` environment variable (`true`/`false`)
2663. `[client] insecure_tls` in `gordon.toml`
2674. `insecure_tls` from the selected remote in `remotes.toml`
268
269This allows overriding specific values while keeping defaults:
270
271```bash
272# Force one target
273GORDON_REMOTE=prod gordon daemon status
274```
275
276---
277
278## Workflow Examples
279
280### Multi-Environment Setup
281
282```bash
283# Add all environments
284gordon remotes add prod https://gordon.example.com --token-env PROD_TOKEN
285gordon remotes add staging https://gordon.staging.example.com --token-env STAGING_TOKEN
286gordon remotes add dev https://gordon.dev.example.com --token-env DEV_TOKEN
287
288# Work with prod
289gordon remotes use prod
290gordon apps list
291gordon daemon status
292
293# Switch to staging
294gordon remotes use staging
295GORDON_REMOTE=staging gordon daemon status
296```
297
298### CI/CD Pipeline
299
300```yaml
301# GitHub Actions example
302env:
303  GORDON_REMOTE: ${{ secrets.GORDON_URL }}
304  GORDON_TOKEN: ${{ secrets.GORDON_TOKEN }}
305
306steps:
307  - name: Push to Gordon
308    run: |
309      gordon images push myapp --build --remote ${{ secrets.GORDON_URL }}
310```
311
312### Compare Environments
313
314```bash
315# Compare one target at a time
316gordon daemon status --remote https://gordon.example.com --token $PROD_TOKEN
317GORDON_REMOTE=staging gordon daemon status
318
319# Or switch between active remotes for other commands
320gordon remotes use prod && gordon apps list
321gordon remotes use staging && gordon apps list
322```
323
324### Private Admin + Wildcard App Domains
325
326Recommended default: use your normal Gordon admin domain with a valid public certificate.
327
328```toml
329# ~/.config/gordon/remotes.toml
330active = "prod"
331
332[remotes.prod]
333url = "https://gordon.example.com"
334token_env = "GORDON_TOKEN"
335```
336
337A common Tailscale setup is to point your domain's DNS at the machine's Tailscale IP (Cloudflare DNS-only / grey cloud). Since the server isn't publicly reachable, there is no external CA to issue a trusted certificate — Gordon's internal CA handles TLS automatically. Clients need to trust the internal CA:
338
339- `insecure_tls = true` on the remote — skips certificate verification entirely
340- `sudo gordon ca install` — on the Gordon host only: installs the root CA into system, Firefox, and Java trust stores
341- `gordon ca export --remote <name> --out gordon-ca.crt` — fetches the root CA PEM from the remote for manual installation
342- Visit `https://<gordon-host>/.well-known/gordon/ca` (or your mapped edge address) in a browser — onboarding page with downloads for macOS, Linux, Windows, iOS, and Android
343
344If you have your own certificate for the domain (e.g. from a corporate CA), you can provide it via `tls_cert_file`/`tls_key_file` — see [Server Configuration](../config/server.md#custom-certificates). The static cert is served for SNI-matching domains; everything else falls through to the internal CA.
345
346`insecure_tls` only affects CLI -> Gordon admin HTTPS verification. It does not change runtime routing: the reverse proxy can still serve wildcard app domains like `*.example.com`.
347
348## Migration from [client] Config
349
350The `[client]` section in `gordon.toml` is deprecated. On first run, Gordon
351auto-migrates it to a `default` remote entry in `remotes.toml` and sets it
352as active. No manual action needed.
353
354## Related
355
356- [CLI Overview](./index.md)
357- [Remote CLI Guide](/wiki/guides/remote-cli.md)

remotes.md RawHistoryFolder

Remotes Commands

gordon remotes

Subcommands

gordon remotes list

Output

gordon remotes add

Arguments

Options

Examples

Token Security

gordon remotes remove

Arguments

Options

Example

gordon remotes use

Arguments

Description

Example

gordon remotes set-token

Arguments

Description

Examples

Output

Configuration File

Resolution Precedence

Workflow Examples

Multi-Environment Setup

CI/CD Pipeline

Compare Environments

Private Admin + Wildcard App Domains

Migration from [client] Config

Related

remotes.md Raw History Folder