Skip to content

Author against a remote project (SSH + branch)

The studio can author a reel workspace that lives in a git remote — cloned locally or held entirely in memory — and push every commit-on-save back. Auth is forge-aware and config-driven: token over HTTPS is the default, and SSH works when you point the tool at a key. Either way the credentials come from config/env and are never committed (spec 0012-studio-remote-git.md).

This guide covers the two things that are easy to miss: using SSH instead of a token, and picking the branch to author against.

Token vs SSH — which you get

When you add a remote project (studio project switcher → Add remote, or POST /api/v1/projects with {remote, branch?, storage?}), keryx resolves git credentials from your config's forge subtree:

  • If <forge>.ssh is configured → SSH auth (a key file or ssh-agent).
  • Otherwise → token auth (<forge>.auth / the <FORGE>_TOKEN env var).

The forge is the tool's release source (gitlab for a keryx built from this project); override it with the vcs.provider config key when your blog remote lives elsewhere (e.g. github).

Use an SSH remote URL to match: [email protected]:you/blog.git, not the https://… form. The URL you paste into the add-remote form is what git dials.

Configure SSH

Add an ssh subtree under your forge in the keryx config. Three shapes, simplest first:

# 1. ssh-agent — no key path; keryx uses your running agent.
gitlab:
  ssh: true                 # a bare truthy value falls back to the agent

# 2. ssh-agent, explicit.
gitlab:
  ssh:
    key:
      type: agent

# 3. A key file — by path, or by an env var holding the path.
gitlab:
  ssh:
    key:
      path: ~/.ssh/id_ed25519
      # or, instead of path:
      # env: KERYX_SSH_KEY      # env var whose value is the key path

Authoring against a GitHub blog instead? Set the provider and configure the matching subtree:

vcs:
  provider: github
github:
  ssh:
    key:
      path: ~/.ssh/id_ed25519

Notes:

  • Passphrase-protected keys need the agent path (shape ½) — load the key into your agent (ssh-add ~/.ssh/id_ed25519) first. A bare passphrased key file can't be unlocked non-interactively.
  • If <forge>.ssh is set but no usable key path resolves, keryx logs a warning and falls back to the agent — so a running agent is the safe default.

Pick the branch

Both the add-remote form and the API accept a branch. keryx honours it for both storage backends:

  • Local clone — a single-branch clone checked out on that branch.
  • In-memory — the remote is cloned into RAM on that branch.

Leave branch empty to take the remote's default branch.

// POST /api/v1/projects
{ "remote": "[email protected]:you/blog.git", "branch": "reels", "storage": "local" }

The chosen branch is recorded on the project entry, so commit-on-save and push stay on it for the session.

Verify

  • Add the remote with an SSH URL + your branch; the project appears in the switcher and its reels load.
  • Save a storyboard edit → the commit-on-save status shows a short hash (an SSH auth or identity problem surfaces here, not silently).
  • With git.auto_push on, the commit is pushed back over SSH.

Token auth remains the zero-config default; reach for SSH when your remote is SSH-only or you'd rather not mint a token. See the studio component guide for the surrounding project-switcher and commit-on-save behaviour.