yoi/docs/development/server-runtime-auth.md

Server / Runtime manual auth setup

Workspace Server and Worker Runtime authenticate remote Runtime control traffic with manually exchanged Ed25519 public keys and short-lived Server-signed capability tokens.

This is a non-interactive bootstrap flow. Commands fail when required flags are missing, and existing identity/trust records are not overwritten unless --replace is passed explicitly.

Authority boundary

• Workspace Server is the workspace control plane. It owns trusted Runtime records in the Server DB and signs per-request Runtime capability tokens.
• Runtime owns Worker execution. It does not own a workspace registry or workspace list.
• Runtime API paths remain worker-centric; workspace scope is carried in the signed auth context and enforced by Runtime-side authorization/filtering code.
• Browser/Web clients should talk to Workspace Server, not directly to Runtime.

Identifiers used in examples

Replace these values for the deployment:

SERVER_ID=server-main
RUNTIME_ID=runtime-main
RUNTIME_BASE_URL=http://127.0.0.1:38800

SERVER_ID is the issuer id in Server-signed tokens. RUNTIME_ID is the token audience and must match the Runtime identity.

1. Create and show the Server identity

From the Workspace Server host:

yoi-server identity init --server-id server-main

Show the public identity and copy the public_key value:

yoi-server identity show --json

The Server private identity is stored in the Yoi data directory under the Server data root, currently:

<data_dir>/server/identity.toml

On Unix this file is written with 0600 permissions. Do not copy the private key to Runtime or commit it to the repository.

2. Create and show the Runtime identity

From the Runtime host, using the same Runtime storage flags that the Runtime server process will use:

yoi-runtime identity init --runtime-id runtime-main

Show the public identity and copy the public_key value:

yoi-runtime identity show --json

By default, Runtime auth state is stored at:

<data_dir>/runtime/auth.toml

If the Runtime process is launched with --fs-root or --fs-runtime-dir, pass the same flags to every identity and trust-server command. Otherwise the setup command may write an auth file that the server process never reads.

Example with explicit Runtime storage:

yoi-runtime identity init \
  --runtime-id runtime-main \
  --fs-root /var/lib/yoi-runtime

yoi-runtime identity show \
  --json \
  --fs-root /var/lib/yoi-runtime

3. Register the Server public key on Runtime

On the Runtime host, register the Server public key copied from yoi-server identity show --json:

yoi-runtime trust-server add \
  --server-id server-main \
  --public-key '<SERVER_PUBLIC_KEY>'

With explicit Runtime storage, keep using the same storage flags:

yoi-runtime trust-server add \
  --server-id server-main \
  --public-key '<SERVER_PUBLIC_KEY>' \
  --fs-root /var/lib/yoi-runtime

Verify:

yoi-runtime trust-server list --json

4. Register the Runtime public key and endpoint on Server

On the Workspace Server host, register the Runtime public key copied from yoi-runtime identity show --json:

yoi-server trust-runtime add \
  --runtime-id runtime-main \
  --base-url http://127.0.0.1:38800 \
  --public-key '<RUNTIME_PUBLIC_KEY>' \
  --display-name 'Runtime main'

This writes a trusted Runtime record to the Server DB. During yoi-server serve, active trusted Runtime records are loaded as remote Runtime sources and receive signed capability tokens. You do not need to duplicate the same Runtime in runtimes.toml for this trust-backed path.

Verify:

yoi-server trust-runtime list --json

5. Start Runtime and Workspace Server

Start Runtime with the same storage flags used during Runtime identity/trust setup:

yoi-runtime \
  --bind 127.0.0.1:38800

For repository builds, the equivalent cargo command is:

cargo run -p worker-runtime \
  --bin yoi-runtime \
  -- --bind 127.0.0.1:38800

Start Workspace Server:

yoi-server serve --listen 127.0.0.1:8787

For repository builds:

cargo run -p yoi-workspace-server --bin yoi-server -- serve --listen 127.0.0.1:8787

If the Server DB has no workspace record yet, initialize it first:

yoi-server init --workspace <WORKSPACE_ROOT>

Smoke checks

Check both trust stores:

yoi-server trust-runtime list --json
yoi-runtime trust-server list --json

Check that Workspace Server can see Runtime workers through the authenticated path. From the CLI:

yoi workers \
  --backend http://127.0.0.1:8787 \
  --runtime-id runtime-main

In Web, open the Workspace UI through Workspace Server and verify that Runtime worker listing, worker creation, and Console protocol input work. The protocol WebSocket uses the same Server-signed Runtime auth path as REST control calls.

Rotation and replacement

Identity and trust records are intentionally not overwritten by default.

Rotate Server identity:

yoi-server identity init --server-id server-main --replace

After Server identity rotation, every Runtime that trusts that Server must be updated with the new Server public key:

yoi-runtime trust-server add \
  --server-id server-main \
  --public-key '<NEW_SERVER_PUBLIC_KEY>' \
  --replace

Rotate Runtime identity:

yoi-runtime identity init --runtime-id runtime-main --replace

After Runtime identity rotation, Server must be updated with the new Runtime public key:

yoi-server trust-runtime add \
  --runtime-id runtime-main \
  --base-url http://127.0.0.1:38800 \
  --public-key '<NEW_RUNTIME_PUBLIC_KEY>' \
  --replace

Revocation

Revoke a trusted Runtime on Server:

yoi-server trust-runtime revoke --runtime-id runtime-main

Remove a trusted Server from Runtime:

yoi-runtime trust-server revoke --server-id server-main

Troubleshooting

trusted runtimes are registered but server identity is not initialized

The Server DB contains trusted Runtime records, but the Server signing identity file does not exist. Run:

yoi-server identity init --server-id server-main

If the identity was created in another environment, ensure the Server process is using the same Yoi data directory.

Runtime accepts unauthenticated requests

Runtime only enables signed capability-token auth when both a Runtime identity and at least one trusted Server are present in its auth file. Check:

yoi-runtime identity show --json
yoi-runtime trust-server list --json

Also confirm the Runtime process was started with the same --fs-root / --fs-runtime-dir used for setup.

Wrong audience or unauthorized Runtime response

Confirm the --runtime-id registered on Server exactly matches the Runtime identity id:

yoi-runtime identity show --json
yoi-server trust-runtime list --json

RUNTIME_ID is the token audience; mismatches are rejected by Runtime.

Duplicate registration fails

This is expected. Use --replace only when intentionally rotating or updating trust material.