sitecard

Sitecard

Issue temporary SSH access cards for development sites and workspaces.

This directory holds only the static sanitized README staged into the generated sitecard distribution. The distributable package itself is generated by scripts/build-sitecard-dist.sh and never checked in.

What it is

Sitecard opens temporary SSH access to a selected development workspace for remote debugging and compatibility testing. The site is the workspace host; the card is the short-lived access path. Fresh Sitecard sessions allow public access by default because they are disposable. Pass --no-public-access to require credentials.

• Distribution name: sitecard
• Version: 0.1.2
• Description: Issue temporary SSH access cards for development workspaces
• Requires Python >=3.10
• Console script: sitecard = sitecard.commands:main

What it is not

The generated distribution contains no deployment helpers, local secrets, target addresses, assessment keys, tests, or unrelated files.

Build

From the repository root:

sh scripts/build-sitecard-dist.sh

Artifacts land in dist/sitecard/. The build fails if any case-insensitive occurrence of the internal project name remains in staging files, archive entry names, or archive file contents.

Authenticated access (--no-public-access)

Public mode is the default and needs no keys.

For --no-public-access with a non-Upterm provider, provision two operator-supplied public key files inside Sitecard state (the pre-existing 0700 state directory: $SITECARD_STATE_DIR/sitecard when SITECARD_STATE_DIR is set, otherwise $XDG_STATE_HOME/sitecard, falling back to $HOME/.local/state/sitecard):

STATE="${SITECARD_STATE_DIR:-${XDG_STATE_HOME:-$HOME/.local/state}}/sitecard"
umask 077
mkdir -p "$STATE"
chmod 700 "$STATE"
printf '%s\n' 'ssh-ed25519 AAAA...primary-operator-key primary' > "$STATE/authorized_keys"
printf '%s\n' 'ssh-ed25519 AAAA...distinct-recovery-key recovery' > "$STATE/recovery_authorized_keys"
chmod 600 "$STATE/authorized_keys" "$STATE/recovery_authorized_keys"

Rules:

• authorized_keys is the primary operator key file.
• recovery_authorized_keys is the independent recovery key file.
• Both files hold public keys only, mode 0600, one OpenSSH public key per line.
• The recovery key must be a distinct operator-supplied public key. Never copy the primary key into the recovery file and never generate a private key the operator cannot access.
• Recovery is optional; when the file is absent or empty only the primary file is used.
• Recovery applies to authenticated non-Upterm transports only. It is not used with the upterm provider, which authenticates via relay-issued certificates.
• Authenticated non-Upterm sessions launch the gateway with --authorized-keys <state>/authorized_keys and --recovery-authorized-keys <state>/recovery_authorized_keys.
• Host SSH files such as ~/.ssh/authorized_keys or the root host SSH file are never read or written for authenticated Sitecard sessions.

Use

sitecard -h
sitecard serve --help
sitecard serve .

serve is a true alias of start with identical arguments.

Dev Tunnel hosting

Install Microsoft's devtunnel CLI before starting. Sitecard does not download tools, create tunnels, or change their access policies. Provision an existing tunnel with port 4822 on an authenticated machine. Transfer a fresh host-scoped token in a private file to the remote machine if it cannot perform OAuth login. Keep the file mode 0600 and refresh it before expiry; restart rereads the file.

Run on the remote workspace host:

sitecard serve . --provider devtunnel --tunnel-id "$TUNNEL_ID" \
  --devtunnel-token-file "$HOST_TOKEN_FILE" --no-public-access

The token is passed to Dev Tunnel on stdin, not in argv or saved settings. Only its file path is saved. Without the token-file option the CLI uses its existing login. Sitecard starts a loopback SSH gateway first, then hosts the existing tunnel without adding the already-configured port again. Startup requires the hosting announcement, matching port, and local SSH banner. The supervisor restarts failed children, subject to a bounded restart budget. Status checks local gateway readiness, not end-to-end relay health.

Run on the client, keeping this process alive in a separate terminal:

devtunnel connect "$TUNNEL_ID"

Client port 4822 must be free. Do not also run a local Sitecard gateway or a second tunnel client on that port. Use a connect-scoped token via --access-token - if the client cannot log in. sitecard connect on the host prints the client command and SSH instructions; its ProxyCommand needs nc on the client. The public HTTPS URL is not a raw SSH endpoint. Hosting must run where the workspace gateway lives, not on the client.

Remote model proxy access

When a model works only through the remote machine's managed HTTP proxy, copying a token does not reproduce that access. First test ordinary forwarding:

ssh -N -L 127.0.0.1:43706:127.0.0.1:43705 -p 4822 "$SSH_TARGET"

Replace the destination with the proxy address actually reachable from the gateway. --tcp-forwarding enables this route; it is enabled by default. Loopback refers to the gateway's network namespace, not another container's. If a remote SSH command can reach the proxy but direct-TCP/IP forwarding cannot, try the SSH exec fallback on the client:

sitecard forward "$SSH_TARGET" --ssh-port 4822 --listen-port 43706

This uses the remote SSH command's HTTPS_PROXY, connects there using existing python3, and streams binary traffic over SSH stdin/stdout. No remote package or CLI downloads are needed. Use --proxy-env http_proxy for a different environment variable. It supports an http:// proxy without URL credentials, including HTTPS destinations via CONNECT. It does not support TLS-to-proxy or SOCKS proxy URLs. SSH key authentication and a previously verified host key are required because each connection uses noninteractive SSH. The local listener is loopback-only; each connection opens one remote SSH command.

Point the model client at http://127.0.0.1:43706 as its HTTP proxy, preserving the original model endpoint URL and destination port. For clients honoring environment variables, set HTTPS_PROXY and HTTP_PROXY; ensure NO_PROXY does not bypass the intended destination. This forwards access, not credentials, and does not change the model protocol or automate model requests. If Python in the SSH exec context cannot reach the proxy either, this fallback cannot cross that namespace boundary; run the gateway there or expose a reachable proxy address. Do not publish the proxy as an anonymous public tunnel.