Make docs agent friendly over SSH

Local setup

Quick start

Build the server and viewer, link the CLI, then start the local SSH and web viewer processes.

pnpm install
pnpm run build
npm link

pnpm run dev
docs-ssh status --json

By default the SSH server listens on 127.0.0.1:2222 and the viewer listens on 127.0.0.1:3000. OIDC is optional for server startup. Add it when the browser needs a signed-in user or when docs-ssh login should mint SSH access.

Authentication

OIDC identifies the browser user

OIDC is the web identity layer. It creates the viewer session cookie, resolves the browser user through auth_identities, and lets docs-ssh login bind a generated SSH public key to that signed-in user. It is not required to start the SSH server or to issue operator-created SSH sessions.

export DOCS_SSH_OIDC_ISSUER=https://accounts.google.com
export DOCS_SSH_OIDC_CLIENT_ID=<client-id>
export DOCS_SSH_OIDC_CLIENT_SECRET=<client-secret>
export VIEWER_PUBLIC_ORIGIN=https://docs.example.com

Without OIDC, docs-ssh login cannot create a browser-approved user session. Use docs-ssh auth create-ssh-session, pre-created SSH keys, or an existing API token flow instead, and keep the viewer private or behind external auth. After the owner exists, add more web users from the viewer Account panel or prelink their OIDC identity from the operator CLI.

Session flow

Web login creates SSH access

docs-ssh config init creates local configuration first. Configure OIDC before this flow: docs-ssh login opens the viewer for browser authorization and writes a temporary SSH identity under ~/.docs-ssh/sessions. This is the path that binds a generated SSH key to a signed-in web user; operator-issued sessions do not create a viewer user session.

docs-ssh config init
docs-ssh login --json
docs-ssh config init
docs-ssh status
ssh docs-ssh bootstrap --json

Workspace model

Projects are server-managed

Local config selects an existing project. It does not create projects. The viewer and operator CLI manage project creation, display names, and archival.

host = "docs-ssh"
viewer_origin = "https://docs.example.com"
project = "default"

/
  README.md
  home/
  projects/
    <project>/
      README.md
      issues/
      tasks/
  tmp/

Automation

API tokens mint scoped SSH sessions

Owners and admins create project-scoped tokens from the viewer. Tokens can read project data, write project data, and create SSH sessions depending on their selected scopes.

docs-ssh token login \
  --token dssh_... \
  --host docs-ssh \
  --project default \
  --viewer-origin https://docs.example.com \
  --json

Token secrets are shown once. Revoke tokens from the viewer when the workflow no longer needs access.

Deployment

Self-host with Docker Compose

The self-hosting compose file keeps docs, auth state, and workspace data on separate host paths. Put the viewer behind HTTPS when using OIDC.

mkdir -p /srv/docs-ssh
cd /srv/docs-ssh
curl -fsSLO https://raw.githubusercontent.com/trknhr/docs-ssh/v0.2.2/docker-compose.selfhost.yml
curl -fsSLO https://raw.githubusercontent.com/trknhr/docs-ssh/v0.2.2/.env.selfhost.example

Agent workflow

Agents start with bootstrap

Agent sessions should call bootstrap --json first. The response includes the current project, accessible projects, principal, paths, and scopes.

ssh docs-ssh bootstrap --json | jq .

Use the generated AGENTS.md and SKILL.md helpers when you want agents to discover the project filesystem and access rules quickly.

Skill distribution

Distribute agent helper files

The CLI can print agent instructions and a reusable docs-ssh skill. Configure a stable SSH alias such as docs-ssh first so generated helper files point at the same target agents will use, then run these commands from a directory with .docs-ssh.toml.

docs-ssh agents --output AGENTS.md --append

docs-ssh skill --output .agents/skills/docs-ssh/SKILL.md

Use docs-ssh setup to preview the full setup guide, or run docs-ssh agents and docs-ssh skill without --output to inspect each generated file before distributing it.

Configuration

Common environment variables