SSH Key and Certificate Management
The CLI manages SSH public keys and short-lived certificates for secure Space
entry. For both Space admins and Space members, the default command is
spaces connect. The typical flow is:
- Connect to a Space with
connect. - The CLI ensures a dedicated local SSH key exists, registers that public key
if needed, fetches pinned host trust material, issues a short-lived
certificate, and invokes
ssh.
Most users should stop there. For advanced use, you can still register keys
manually with ssh add-key, issue certificates manually with ssh issue-cert,
or generate an OpenSSH config block with ssh client-config.
Certificates default to a 5-minute TTL, keeping the attack surface minimal.
Test harness -- in normal use, just run "spaces" directly.
. .specdown/test-env
tmp=$(mktemp -d)
spaces_issue_auth_key alice@example.com admin > "$tmp/auth.key"
chmod 600 "$tmp/auth.key"
cat > "$tmp/spaces" <<WRAPPER
#!/bin/sh
export SPACES_BASE_URL=$SPACES_BASE_URL
: "\${SPACES_SESSION_FILE:=$tmp/session.json}"
export SPACES_SESSION_FILE
exec $SPACES "\$@"
WRAPPER
chmod +x "$tmp/spaces"
"$tmp/spaces" login alice@example.com --key-file "$tmp/auth.key" >/dev/null
ssh-keygen -q -t ed25519 -N '' -f "$tmp/id_ed25519"
printf '%s\n' "$tmp/spaces" "$tmp"rm -rf ${tmp}Registering SSH Keys
Add a key
Register your SSH public key with a friendly name:
You can also pass the key material inline with --public-key instead of
--public-key-file.
List registered keys
Remove a key
Unregister a key by its fingerprint:
Connecting to a Space
Quick connect
connect is the easiest way to enter a Space. It handles certificate
issuance automatically. If you omit SPACE, the CLI uses your saved default
Space, or the only visible Space when exactly one is available. When you want
to override that choice, pass either the Space ID (e.g. sp_xxx) or the exact
Space name when that name is unique among your visible Spaces:
spaces connect
spaces connect my-project
spaces ssh connect --space my-project
Behind the scenes, the CLI:
- Ensures a dedicated local private key exists (defaults to
~/.ssh/id_ed25519_spaces) - Registers the matching public key if the control plane has not seen it yet
- Fetches a pinned
known_hostsline for the SSH entry host - Sends the public key to the control plane to get a short-lived certificate
- Writes the certificate next to the private key
- Runs
sshwith strict host-key checking, the certificate, the identity file, and the Space target
That means a member who has already run spaces login you@example.com usually does not
need to think about ssh add-key, ssh list-keys, ssh remove-key, or
ssh issue-cert at all.
OpenSSH config
If you prefer to use ssh directly, generate an OpenSSH config block and
paste it into ~/.ssh/config. The CLI rejects client-config inputs that
contain whitespace or control characters, because those values would change the
meaning of the generated ssh_config directives:
After adding this to your SSH config, you can connect with just
ssh spaces-sp_1.
Manual Certificate Issuance
For scripting or debugging, you can issue a certificate without connecting:
The certificate is written next to the private key: