Skip to content

Host: agent-device host front-end command and persistent service credential #3265

Description

@vkuprin

Part of #3264. ADR 0021 §3, §6, §8. Design D1 and D3 in the umbrella.

Purpose

Operators need one command that exposes the local daemon to remote verification workers and authenticates them with a credential that survives restarts. This is the Host front-end process from ADR 0021 §3. It is separate from the daemon and built on @agent-device/proxy.

Required behavior

  • agent-device host starts a long-running front-end. It starts or reuses the local daemon in HTTP mode, the same way proxy does, and forwards over loopback with the daemon token. It reuses createDaemonProxy and the proxy's Node request listener. The proxy command, its flags and its output do not change.
  • On first start Host creates one service credential at <state dir>/host/service-credential.json, with the directory at 0700 and the file at 0600, written atomically once Host is serving. It holds { version: 1, credentialId, token, principal, createdAt }. Every later start reuses it.
  • Host refuses to start with details.reason: "host-credential-insecure" when the file or directory is open to group or others or owned by another user, and with "host-credential-invalid" when the file is malformed. It never regenerates a bad file. These checks run before any daemon starts.
  • The token is printed only on the start that creates the credential. Later starts print the file path and principal.
  • Flags: --host <host>, --port <port>, --state-dir <dir>, --tls-cert <path>, --tls-key <path>. Both TLS flags together serve HTTPS. One without the other fails with "host-tls-incomplete", a file Host cannot read with "host-tls-unreadable", and a certificate and key that do not load together with "host-tls-invalid". Without TLS, Host serves plain HTTP and only on loopback ("host-tls-required" otherwise). A wildcard bind advertises the machine's hostname, and a name keeps the name the operator gave.
  • The command is in the command registry, with versioned CLI help (agent-device help host) and a section in the remote proxy docs.

Completion conditions

  • A test starts Host, stops it, and starts it again on the same state dir; the token and principal match and the file mode is 0600.
  • A request without the token or with a wrong one gets 401. An unserved route gets 404.
  • An insecure or malformed credential and an unreadable TLS file stop startup with their typed reasons, and no daemon is started.
  • An HTTPS round-trip works with a test certificate.
  • The existing proxy tests pass unchanged.

Dependencies

None.

Example

agent-device host --host 0.0.0.0 --port 8443 --tls-cert /etc/host/cert.pem --tls-key /etc/host/key.pem
# first start
✓ Host listening at https://build-mac.local:8443 (bound to 0.0.0.0:8443)
Service credential created: ~/.agent-device/host/service-credential.json
Principal: host-svc-3f9c2a1b
Token: 9f3c… (shown once; read it from the credential file later)

Activity

  1. added 2 commits that reference this issue on Oct 7, 2026
    96bb2fd
    f173b22
  2. thymikee commented on Oct 7, 2026

    @thymikee
    Member

    On hold: we are integrating Simlock first and will revisit ADR 0021 / remote Host implementation afterwards. See the sequencing decision.

    The Host command, persistent service credential, and remote front-end deployment are deferred until the Simlock integration works end to end.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions