First Admin Console setup

This guide takes an initialized instance to its first callable chain. Applications should receive only a Gateway Key, Gateway URL, and public model alias; Provider credentials, real model IDs, and prices stay inside Halro.

Check the version first

Credential, Provider, Deployment, Route, Project, Gateway Key, and Run Governance are all in the released line; Run Governance APIs remain experimental. Confirm the deployed version with halro version, and check the install center for what each channel has accepted.

This guide starts after the first administrator exists. The production bootstrap flow shipped in v0.8.3: a remote deployment should use a read-only admin.setup_token_file, or run the idempotent offline admin bootstrap before start, instead of reading the token from service logs. See Production Admin bootstrap and secret lifecycle for delivery, audit, and recovery; releases up to and including v0.8.2 do not support these commands.

If Web setup commits the administrator but session creation fails, setup is already complete. Do not resubmit or rotate the password; go to /admin/login and inspect the admin.bootstrap Audit event.

Prerequisites

Prepare these facts before opening forms:

Prerequisites

Information	Confirmed by	Used for
Provider type, access surface, official Base URL	Platform administrator	Credential scheme and protocol Profile
Real model/deployment ID, Region, account/project	Provider administrator	Exact invocation target
Capability and limit evidence	Application owner and platform administrator	What the Deployment may accept
Current price, currency, Region/Tier, effective time	FinOps and platform administrator	Immutable Price Version
Public alias, environment, failure domain	Application owner and platform administrator	Route design without upstream names in apps
Project owner, budget, limits, source CIDRs	Business owner and platform administrator	Access and cost boundary

Production Admin must use HTTPS, restricted network access, and admin.mfa_policy: required. The current user must be an administrator; read-only users may inspect but not mutate resources.

1. Save a Credential

Under Credentials & Providers → Credentials:

1. Select Provider type and access surface.
2. Enter a name, bound Base URL, and secret; Bedrock Mantle Region is selected here and becomes part of the bound endpoint.
3. Record a real expiration when one exists.
4. After saving, confirm only “configured” remains and plaintext is never returned.

Rotate a Secret in the existing record only for the same endpoint. Create a new Credential for a different endpoint or authentication scheme. Never put Provider keys into Gateway Keys, Project names, logs, or test bodies.

Optional: create a Provider egress proxy

Create one under Credentials & Providers → Egress proxies only when upstream access must use a specific exit:

1. Use an http:// or https:// CONNECT URL with explicit port and no path, query, fragment, or embedded credentials.
2. Enter Basic Auth separately; its password is Vault-encrypted and never returned by the API.
3. Private/loopback targets or Basic Auth over plaintext HTTP require separate risk acknowledgement.
4. Container 127.0.0.1 means the Halro container, not its host; use a reviewed host gateway, container-network proxy, or host networking.
5. Save, bind it in the Provider form, and test the real Provider connection.

A Provider bound to a proxy never silently connects directly when the proxy fails. Drain its Deployments before changing endpoint, authentication, or policy, then retest. Deleting a referenced proxy is rejected.

2. Create the Provider connection

Under Credentials & Providers, select type, access surface, Base URL, Credential, and any required API Version or Project identity. Bedrock Region comes from the Credential. Select direct access or the reviewed proxy, enable only capabilities actually allowed by this connection, save, and run a connection test. Record the failure category rather than copying sensitive upstream bodies.

Some access surfaces need a Deployment before a real model can be selected for the Provider test. If the UI says so, create it in the next step and return; the prompt is not a passed test.

A connection can resolve to multiple protocol bindings. The Profile determines encoding and pre-I/O field rejection; it is not a marketing label. Connectivity does not prove tools, vision, or structured output.

3. Select the real target and capability evidence

Under Model Deployments:

1. Select the Provider and refresh its real target list.
2. Where upstream enumeration exists, select from it. Enumeration proves existence, not capability.
3. For a catalog-covered target, review its immutable capability snapshot and source.
4. For unknown or conflicting targets, confirm the protocol binding, then explicitly declare or run controlled detection.
5. Keep only business-required, evidenced capabilities and set Deployment concurrency.
6. Save and test the Deployment.

Detection makes real, potentially billable Provider calls. Control-plane detection is excluded from Project budgets, Accounting Ledger, and Usage. Distinguish unsupported, inconclusive, unavailable, and unauthorized; keep capability disabled without reliable evidence.

4. Activate a Price Version

In the Deployment’s Price Versions:

1. Confirm Provider, target, Region, and Tier.
2. Enter input, cached-input, and output prices in USD / 1M tokens, plus USD / request when applicable.
3. Choose free only when the target is genuinely free; four zeros must not mean “not researched.”
4. Add source/review evidence and choose immediate or future activation.
5. Recalculate the example amount on the confirmation screen before creating the immutable version.

Without an effective Price Version, default cost governance rejects before Provider I/O. Historical Attempts preserve their execution-time price evidence.

5. Publish a Route

Use an application-stable alias such as support-chat-prod:

• for one target, create an enabled Route and confirm capability drift, pricing, or dependency state does not hold it;
• use ordered for primary/backup with lower numbers first; round_robin distributes traffic and is not failover;
• include only semantically equivalent, priced targets in different failure domains;
• native Anthropic, deferred work, and Files/Batches resource operations have fixed/unique-target constraints and cannot copy synchronous Chat fallback design.

Test the Route and confirm selected Deployment, Provider, and Profile. The test calls upstream and may incur cost.

6. Create policy and Project

Create and test any Token Guard or Redaction policy before creating the Project. Confirm every boundary:

6. Create policy and Project

Project setting	Decision
Allowed Models	Which public Route aliases may this workload call?
Daily Budget	Maximum spend in one accounting-timezone day?
RPM, TPM, max concurrency	Maximum normal peak and failure retry load?
Input/output tokens, body, stream duration	Is worst-case request cost and occupancy bounded?
Allowed CIDRs	Which application networks may use the Key?
Token Guard / Redaction	Were anomaly and data-handling rules tested with real samples?
Deferred Responses	May successful results be sealed into the local data directory?
Run Governance	Will the workload use Work Unit, Run, Outcome, and Run budgets?

Projects authorize public aliases, not Provider or Deployment IDs. Separate development, staging, and production, and split production workloads with distinct budgets or owners.

7. Issue a Gateway Key

• Normal inference needs only inference.
• Agent orchestration adds work_unit:create, run:create, or run:attach as required.
• Outcome writers use a separate key with outcome:write and optionally governance:read.
• Record owner, purpose, expiry, and rotation plan.

Plaintext appears once. Save it in the application’s secret manager before closing. If lost, revoke and reissue; Halro cannot retrieve it.

8. Verify one governed request

curl -fsS http://127.0.0.1:8080/health/ready

Then send a minimal request using the Project’s Gateway Key and public alias:

curl https://halro.example.com/v1/chat/completions \
  -H "Authorization: Bearer $HALRO_GATEWAY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"chat","max_tokens":64,"messages":[{"role":"user","content":"Reply with: ready"}]}'

Confirm in Admin Console that the Request belongs to the expected Project, the selected Deployment and each Attempt are visible, and usage/cost carry the intended pricing evidence. Record the response request ID for the acceptance log.

Acceptance continues beyond HTTP 200:

• the Request belongs to the expected Project and the Attempt selected the intended Route, Deployment, and Provider;
• the Attempt carries the current Price Version snapshot, not unknown or incorrectly free cost;
• tokens, latency, classification, and Provider Request ID are plausible;
• unauthorized Key, forbidden alias, and tiny budget each reject before Provider I/O;
• ordered primary/backup proves safe fallback, while ambiguous failures do not fallback.

The local Developer Workbench issues real Gateway calls and may be billed; disable it for remote Admin. Continue with Use an existing Gateway Key and Retries, timeouts, and idempotency.