5. Enroll a remote kernel

An agent-kernel is a Rust process that runs on a customer host and exposes JSON-RPC tool execution (filesystem, command, shell) over an mTLS WebSocket to the Mnemose kernel-broker. This guide walks through enrolling a single host.

Prerequisite: 4. Provision the platform core complete — the kernel rows must exist (status: "pending") before the remote process can claim them.

Architecture recap

platform-ops persona
    ↓  kernel.list / kernel.invoke (mcp-mnemose-kernels)
    ↓  publish InvokeKernelTool (mnemose.commands)
kernel-broker (services/kernel-broker)
    ←  subscribed to cmd.kernel.* topic
    ↔  mTLS WebSocket to each enrolled kernel
agent-kernel --remote <broker-url>
    ↓  JSON-RPC tool dispatch over WS

Issue the bootstrap token

In the console, navigate to /fleet → Enroll, or call:

mutation Enroll {
  enrollKernel(
    input: {
      tenantId: "<tenant-uuid>"
      kernelId: "<uuid-from-CoreManifest>"
      label: "prod-jumphost-1"
      permissionTier: "workspace-write"
    }
  ) {
    bootstrapToken
    enrollCommand
  }
}

The mutation:

1. Marks the existing agent_kernels row as enrollable (or creates one if it is not in the core manifest).
2. Issues a single-use, short-TTL bootstrap token signed by the gateway.
3. Returns a ready-to-paste enrollCommand containing the broker URL, kernel ID, and token.

Run the enrollment on the target host

On the host that will run the kernel:

# Download the agent-kernel binary (see apps/agent-kernel/README.md)
curl -fsSL https://example.com/agent-kernel-linux-amd64 -o /usr/local/bin/agent-kernel
chmod +x /usr/local/bin/agent-kernel

# Paste the enrollCommand from the mutation response
agent-kernel enroll \
  --broker wss://<kernel-broker-url> \
  --kernel-id <uuid> \
  --token <bootstrap-token>

The kernel exchanges the bootstrap token for a long-lived mTLS client certificate (signed by the tenant intermediate CA loaded into Secret Manager during deployment) and stores it in /var/lib/agent-kernel/identity.pem.

Start the kernel

# Foreground, useful for first-run verification:
agent-kernel run --remote --broker wss://<kernel-broker-url>

# Or install the provided systemd unit:
agent-kernel install-systemd --broker wss://<kernel-broker-url>
sudo systemctl start agent-kernel

On successful connection, the broker flips the row’s status to online and emits a KernelEnrolled event.

Verify in the console

1. Refresh /fleet. The PlatformCorePanel should now show all kernels online — green strip “Platform core healthy”.
2. The Fleet map / table shows the new kernel with a live mTLS connection.

Sessions for mutating tools

Read-only tools (fs_read, metrics_*) work immediately. Mutating tools (fs_write, cmd_exec, shell_*) require an operator-approved KernelSession:

mutation Request {
  requestKernelSession(
    input: {
      kernelId: "<uuid>"
      tier: "workspace-write"
      ttlSeconds: 1800
      reason: "Patch nginx config on jumphost"
    }
  ) {
    sessionId
    status
  }
}

mutation Approve {
  approveKernelSession(sessionId: "<session-uuid>") {
    sessionId
    expiresAt
  }
}

The broker enforces tier + TTL on every invocation. The kernel additionally enforces its own immutable startup permission tier as a defence in depth.

Audit

Every invocation writes two domain events:

• KernelInvocationDispatched — when the broker forwards a JSON-RPC call
• KernelInvocationCompleted or KernelInvocationFailed — on response

Query agentActivity subscription or the domain_events table for the full audit trail.

Revoke

mutation Revoke {
  revokeKernel(kernelId: "<uuid>", reason: "host decommissioned")
}

The kernel’s mTLS certificate is added to the broker’s revocation list. The WebSocket is closed on next heartbeat. The row remains for audit but its status becomes revoked.

Reference

• apps/agent-kernel/README.md — full kernel installation, tool catalog, CLI reference
• apps/agent-kernel/docs/architecture.md — Rust workspace + transport details
• Agent-kernel integration — protocol boundary between Mnemose and the kernel

Next

If you are an operator, you are done — the platform is deployed and ready to take on infrastructure work.

If you are a developer, continue to → 6. Local development