Connect To The gRPC Backend

dokime serve and cargo dokime serve expose the same native gRPC API. The backend serves no UI. Use the desktop application as the operator interface, or generate your own client from the canonical protobuf contract.

Local service

cargo dokime serve --port 8765

The listener defaults to 127.0.0.1. Local callers are trusted unless you supply --auth-file. --port 0 allocates an available port; an explicit occupied port fails rather than silently choosing another. Stop the process to drain the listener and flush the runtime.

Remote service

Provide a certificate valid for the hostname clients use, its PEM private key, and a JSON authentication file. The file contains a grants array; each entry has subject, role (read, control, or admin), and token fields. Provision an independently generated high-entropy token of 32–4096 visible ASCII bytes for each grant, and protect this file as a credential. Tokens are never CLI arguments.

cargo dokime serve --host 0.0.0.0 --port 8765 --allow-remote \
  --tls-cert server.pem --tls-key server-key.pem --auth-file authentication.json

Remote mode requires both TLS and authentication. Clients verify the server certificate and send authorization: Bearer <token> in gRPC metadata. Use the certificate’s reachable hostname, rather than the wildcard listening address. The desktop stores saved bearer credentials in the OS credential store.

Generate a consumer

Download the protocol artifact from a successful protocol CI job or produce it with mise run protocol:archive -- path/to/protocol.tar <source-commit>. The archive contains canonical .proto sources, imported schemas, a descriptor set, source identity and checksums. Feed those sources to the protobuf/gRPC compiler for your chosen language. No Dokime runtime installation or foreign example project is required on the consumer machine.

Start with Backend.GetIdentity, GetCapabilities, and GetHealth; then use the declared services. The contract reference explains paging, mutation receipts, stream invalidation and content ownership.