DEVELOPMENT DOCUMENTATION / SETUP

Build and connect an enrolled computer.

An operator-managed setup for developers with access to the source checkout and a provisioned relay environment.

1. Prepare the environment

• A source checkout and Rust 1.95.0, pinned by rust-toolchain.toml.
• A relay host with separate consumer HTTPS and device mTLS listeners.
• An authoritative Redis catalog with persistence, TLS and a recovery policy.
• An external identity issuer, configured JWT verification keys, tenant/user/device records and explicit service grants.
• Device certificates and trusted CA material supplied through your operator's provisioning process.

2. Build and inspect the CLI

cargo build --workspace --locked --bins
cargo run --locked -p tunnel-client -- --help
cargo run --locked -p tunnel-relay -- --help

The product name changed; the tunnel-client and tunnel-relay binary names remain unchanged.

3. Configure the relay

Use examples/m1-relay.toml as a schema reference, not a ready deployment. Replace its placeholder values and certificate paths. Keep private material outside source control.

cargo run --locked -p tunnel-relay -- \
  check-serve-config --config /absolute/path/relay.toml

This dry run checks the serving configuration document. It does not read referenced credentials, connect to Redis, verify the deployment or provision authority records. The legacy check-config validates a different configuration type.

4. Configure the device

Start from examples/m1-client.toml. Resolve certificate paths relative to the client configuration file. Replace the device ID, relay URL and all credential references.

device_id = "your-enrolled-device"
relay_url = "wss://relay.example.test/v1/tunnel/control"

[credentials]
client_certificate = "credentials/device-cert-chain.pem"
client_key = "credentials/device-key.pem"
server_ca = "credentials/relay-ca.pem"

This excerpt is not a complete configuration. Keep the example's required limits and rotation sections. Its synthetic echo export is for a controlled transport smoke test, not filesystem, MCP, ACP or desktop access.

5. Provision and validate credentials

cargo run --locked -p tunnel-client -- \
  config check --config /absolute/path/client.toml

cargo run --locked -p tunnel-client -- \
  credentials create --config /absolute/path/client.toml \
  --csr-out /absolute/path/device.csr

Have your operator sign the CSR with the approved device issuer and establish the matching catalog identity and grants. Creating a CSR does not enroll or authorize a device.

cargo run --locked -p tunnel-client -- \
  credentials import --config /absolute/path/client.toml \
  --certificate /absolute/path/device-cert-chain.pem \
  --server-ca /absolute/path/relay-ca.pem

cargo run --locked -p tunnel-client -- \
  doctor --config /absolute/path/client.toml --json

doctor performs local checks. A network doctor, enrollment-code workflow and managed credential renewal are not delivered commands in this reviewed CLI.

6. Start the provisioned relay and device

cargo run --locked -p tunnel-relay -- \
  serve --config /absolute/path/relay.toml

# On the enrolled computer, in a separate terminal:
cargo run --locked -p tunnel-client -- \
  connect --config /absolute/path/client.toml --json

The client runs in the foreground. Start only after catalog records, grants, identity and trust have been provisioned. Relay connectivity alone does not grant access to an export. Add capability-specific configuration only after checking its support boundaries.

Acceptance before deployment

cargo fmt --all -- --check
cargo clippy --workspace --all-targets --locked -- -D warnings
cargo test --workspace --locked

These checks are necessary but not a replacement for the real Redis/socket and capability acceptance harnesses in the checkout. Cluster support and applicable adapter gates remain private-alpha requirements. Use dedicated disposable desktop VMs for computer-use tests.