Console setup, release and credential contracts
Clean-install support and preflight
The current console's automated clean installer accepts Ubuntu 24.04 amd64 only. The preflight implementation tests OS version 24.04 and x86_64/amd64 architecture; it also reports internet/DNS, free space, operator candidates and Docker/Compose/Git/Git LFS/NetworkManager availability. This restriction belongs to the control-host installer; the separate Jetson perception path uses its own supported platform.
Initial disk estimate is twice the 25 GiB configuration estimate, then release-manifest requirements replace it. The installer checks free space again at the selected configuration parent. A successful generic package install does not bypass clean-installer preflight.
Setup values object
POST /api/setup/draft, /api/setup/credentials/validate, /api/setup/install and /api/jetson/provision accept { "values": { ... } }, but consume different subsets. Drafts preserve nonsecret values; secret fields are excluded from returned/stored draft state and passed through the credential workflow.
| Field | Purpose / current default |
|---|---|
hostUser |
Operator owning SDK state; default hr |
configPath |
Configuration checkout; default operator home/workspace/hrsdk_configs |
configRepo |
Configuration Git repository; default Hanson Robotics hrsdk_configs repository |
configRef |
Requested configuration branch/ref; default ros2 |
stackVersion |
Exact required release version; empty is rejected by install |
robotName, robotBody |
Selected head/body; body default is default, head can be detected/selected |
rosDomainId |
Required numeric domain 0–101 for installer; UI may propose a nonzero random value |
robotEthernetInterface |
Physical interface for generated DDS profile |
audioConfirmed |
UI readiness confirmation; does not itself configure an audio path |
provisionJetson |
Whether installation also provisions Jetson; current UI defaults true |
jetsonHost, jetsonUser, jetsonEthernetInterface |
Remote target/user and DDS interface; current UI host default 10.0.0.20, user hr |
awsRegion |
Registry access region, default ap-east-1 |
pollyAwsRegion |
Optional speech-specific AWS region |
The initial-install form does not directly persist arbitrary character/world fields in the install environment written by this implementation. Character/world are subsequently resolved through current configuration/environment defaults. Inspect effective identity after startup rather than assuming all conceptual identity fields are setup-form inputs.
Credential validation
| Secret input | Use |
|---|---|
githubToken |
Read access to configuration repository |
awsAccessKeyId, awsSecretAccessKey, optional awsSessionToken |
STS/registry/manifest access |
frpcAuthToken |
Remote tunnel client authentication |
openaiApiKey, anthropicApiKey, sonioxApiKey |
Optional runtime provider values |
googleServiceAccountJson |
Optional complete Google service-account JSON |
pollyAwsAccessKeyId, pollyAwsSecretAccessKey, pollyAwsSessionToken |
Optional speech-specific AWS credentials |
sshPassword, sudoPassword |
One-time provisioning inputs where consumed |
The UI's required credential readiness includes GitHub, AWS and FRPC. New GitHub credentials are checked against repository access; new AWS credentials are checked using STS and the stack-manifest repository; FRPC input is validated by its format rules. Reuse paths can check stored presence rather than revalidate every provider. A configured marker is not universal proof of external-provider health.
Credentials are stored through separate operator-owned secret files with restricted permissions. The API returns configuration/source status rather than the secret value. Supplying a credential can cause host file writes and tunnel-service restart; validation with persistence is not a read-only check.
Installation stages and failure behavior
Stages are preflight, credentials, dependencies, configs, robot, images, Jetson, service and validation. Installation can install host packages, fetch a manifest, clone/update Git and LFS assets, write identity/domain/environment configuration, pull images, provision Jetson, install systemd/browser-audio support, start SDK and validate runtime.
It records resolved configuration commit/ref and exact stack version. It validates release requirements before proceeding. If final runtime validation fails, the implementation disables/stops hrsdk.service rather than leaving the installation marked complete.
Status returns installed/phase/message/progress, per-stage states, safe draft, credential status, current release, validation and resumability. Do not infer completion merely from .env and main.yaml appearing: they exist before image pull/startup validation finishes.
Release manifests and switching
Release metadata is inspected for host compatibility and required artifacts. Listing a version is not proof it can be installed on this host; retain compatibility/error results. Switching accepts version and optional configRef, resolves configuration and stage state, and may update remote Jetson image selection as part of the release workflow. Preserve the prior manifest/configuration baseline for rollback.
Runtime secret PATCH
PATCH /api/hrsdk/runtime-secrets accepts:
{"set":{"OPENAI_API_KEY":"REPLACE_WITH_PRIVATE_VALUE"},"clear":[]}
This is a write operation; do not send placeholder values to a real robot. Allowed scalar names in the current implementation are OPENAI_API_KEY, GROQ_API_KEY, SONIOX_API_KEY, PERPLEXITY_API_KEY, GCLOUD_API_KEY, ELEVENLABS_API_KEY, AZURE_SPEECH_KEY and ACAPELA_PASSWORD. The Google file secret is GOOGLE_APPLICATION_CREDENTIALS.
Unknown keys are rejected. A name cannot appear in both set and clear. Scalar values cannot be empty or contain NUL/newline/carriage return; use clear to remove an override. The ElevenLabs speech-key alias is normalized/cleared with the canonical key. Clearing a local override can restore a configured default; it does not guarantee the provider is disabled.
File-secret content must be nonempty, at most 1 MiB, valid JSON object, and for Google have type: service_account. A file-secret set value is the JSON document serialized as a string, not a host filename. Nonempty directories at a credential-file destination are rejected rather than recursively deleted.
Status items report name/label/kind, configured state and source (local_override, config_default, missing), plus file format/default metadata where applicable. Changes mark restartRequired; apply/restart through the designated lifecycle and recheck status. Do not assume providers reload every credential live.
Evidence: hr_system_console/api/system_console/setup.py, main.py, setup UI and HRSDK credential editor. Typed models and per-operation index.