apus configure

Interactive prompts for targeted changes to an existing setup: credentials, devices, agent defaults, gateway, channels, plugins, skills, and health checks.

Use apus onboard or apus setup for the full guided first-run journey, apus setup --baseline for the baseline config/workspace only, and apus channels add when you only need channel account setup.

apus config with no subcommand opens the same wizard. Use apus config get|set|unset for non-interactive edits.

Options

Before apus configure changes local credentials or configuration, Apus compares the selected CLI state/config paths with the local Gateway or its installed service. A proven mismatch stops before the write. A remote Gateway or an authenticated path that cannot be verified produces a warning instead.

This comparison also applies when APUS_HOME relocates the CLI's default state directory. The installed service's recorded environment determines its paths, including while the Gateway is stopped. The CLI's path overrides do not replace them. If the service definition or its recorded paths cannot be verified, Apus warns and leaves configuration available. Inspect the service with apus gateway status --deep before relying on local changes to reach it.

--section <section>: repeatable section filter. Available sections:

workspace, model, web, gateway, daemon, channels, plugins, skills, health

apus configure
apus configure --section web
apus configure --section model --section channels
apus configure --section gateway --section daemon

Selecting gateway, daemon, or health (or running the full wizard with no --section) prompts where the Gateway runs and updates gateway.mode. Section filters that skip all three go straight to the requested setup with no gateway-mode prompt. Picking remote gateway mode writes the remote config and exits immediately. It does not run local-only steps like plugin installs.

Gateway, daemon, health, and web settings do not require an agent owner. Workspace, model, plugin, skill, and channel setup use the configured System Agent in an explicit fleet. If none is configured, the wizard asks which existing agent to use. That selection applies to the remaining agent-scoped sections without changing the System Agent setting. Channel setup uses the selected workspace for plugin discovery. Removing channel configuration does not require an agent selection.

apus configure requires an interactive terminal (both stdin and stdout must be TTYs). Without one it prints the equivalent non-interactive apus config get|set|patch|validate commands and exits with an error instead of partially running.

Gateway section

First-run apus onboard and apus setup generate a Gateway secret in token mode without a token/password picker. They preserve existing password mode. Use their --gateway-auth password or --gateway-password <value> flags to choose a password explicitly. Tailscale Funnel still requires password mode. The local configure Gateway section retains its auth-mode picker for targeted reconfiguration. The mode selects the configured secret. Clients may send it in either auth.token or auth.password.

Remote configuration asks for one Gateway secret and stores it as gateway.remote.token, whether the remote Gateway calls it a token or password.

For Trusted Proxy auth, enter comma-separated IPv4 or IPv6 addresses or CIDR ranges, such as 10.0.0.1, ::1, 10.0.0.0/24. The wizard rejects malformed addresses and empty entries before saving. It ignores surrounding whitespace.

For Trusted Proxy auth, an address or CIDR that matches a loopback source shows a security warning. The wizard then asks for explicit consent before it sets gateway.auth.trustedProxy.allowLoopback. Declining leaves it unset and warns that loopback proxy requests will be rejected at runtime. See Trusted proxy auth for the trust requirements.

Reconfiguring trusted-proxy mode defaults the loopback prompt to the existing opt-in and preserves deviceAutoApprove unchanged. An explicit refusal revokes loopback consent. Without a matching loopback source, the existing setting is retained.

Model section

Model includes a multi-select for the explicit agents.defaults.modelPolicy.allow list (what shows up in /model and the model picker). Provider-scoped setup choices merge their selected models into the existing list instead of replacing unrelated providers already in the config. Per-model aliases and parameters remain under agents.defaults.models. Those entries do not restrict model overrides by themselves.

Re-running provider auth from configure preserves an existing agents.defaults.model.primary, even when the provider's auth step returns a config patch with its own recommended default model. Adding or reauthing a provider makes its models available without taking over your current primary model. Use apus models auth login --provider <id> --set-default or apus models set <model> to intentionally change the default model.

When configure starts from a provider auth choice, the default-model and model-policy pickers prefer that provider automatically. For paired providers such as Volcengine and BytePlus, the same preference also matches their coding-plan variants (volcengine-plan/*, byteplus-plan/*). If the preferred-provider filter would produce an empty list, configure falls back to the unfiltered catalog instead of showing a blank picker.

Web section

apus configure --section web picks a web-search provider and configures its credentials. Some providers show provider-specific follow-ups:

Other notes

Related