Skip to content

Commit 9f6b95b

Browse files
fix: reload providers per process, not per workspace, and qualify the Base docs
- The register route skipped its reload whenever the requesting workspace already listed Base. Caches in other directories, or in the `/api` registry, could still predate a background registration. It now skips only once this process has reloaded for that exact credential. - The headless disclosure test isolates its home directory like the other Base suites. - Docs: the three-second startup wait and background completion, the retry backoff, the auto-register skip conditions, what registration sends, and the TUI notice appearing when Base first becomes active. Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]> Claude-Session: https://claude.ai/code/session_016x3nbZU5Vb6HnSTqE7vELm
1 parent 6f92853 commit 9f6b95b

7 files changed

Lines changed: 55 additions & 40 deletions

File tree

‎docs/docs/configure/providers.md‎

Lines changed: 8 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -63,12 +63,16 @@ If you need stronger guarantees — no training on your data, metadata-only rete
6363
instead.
6464

6565
Choose **Altimate Base** from the first-run picker or `/connect` — or do nothing at all: every
66-
install that is not yet registered registers it automatically at startup, before your first prompt,
67-
so it works the same way headlessly (`run`, `serve`, `acp`, `web`). This happens whether or not you
66+
install that is not yet registered registers it automatically at startup, so it works the same way
67+
headlessly (`run`, `serve`, `acp`, `web`). Startup waits up to three seconds for this; a slower
68+
registration finishes in the background and applies from the next launch (a `serve` client can
69+
apply it sooner through the register route). After a failed attempt, startup skips registration
70+
for a retry backoff of one hour (longer if the gateway asks, up to 24 hours). This happens whether or not you
6871
also have a model of your own; a registered Base only becomes your default when nothing you
6972
configured is usable. There is no confirmation dialog to accept.
70-
The disclosure above is printed once per install the first time Base is registered — a toast in the TUI,
71-
or a one-line notice to stderr for a headless entrypoint (`serve` skips it when
73+
The disclosure above is shown once per install: in the TUI as a toast the first time Base becomes
74+
the active model, and for a headless entrypoint as a one-line notice to stderr the first time it runs
75+
with Base registered (`serve` skips it when
7276
`ALTIMATE_CLI_CLIENT=datamates`, since the VS Code extension shows its own notice). After registration, the model is available as
7377
`altimate-free/altimate-base` and becomes the free fallback when no paid Altimate Gateway or
7478
explicit model is selected. Big Pickle is retired as a new selection — it no longer appears in the

‎docs/docs/getting-started/quickstart.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,7 @@ On a fresh install, a welcome panel appears with a curated 6-provider picker:
2525

2626
- **Altimate LLM Gateway** *(recommended)* — 10M tokens free, no API keys. Routes to the best model per task across Sonnet, Opus, GPT-5, and more. Sign-in opens a browser tab; complete Google or email signup and you're back in the TUI. If your terminal can't open a browser (SSH / tmux / WSL), the CLI prints the URL — paste it into a browser on your desktop.
2727
- **Anthropic** / **OpenAI** / **Google** — paste an API key or OAuth in.
28-
- **Altimate Base** — a hosted open model, free and rate limited, with no signup or API key. Requests and responses may be logged and used to improve Altimate's products, so do not send secrets or confidential code. Every install registers it automatically at startup, whichever provider you pick — there is no confirmation dialog — and shows this notice once; it only becomes your model when nothing else you configured is usable. Opt out with `ALTIMATE_BASE_AUTO_REGISTER=0`, `altimate providers logout altimate-base`, or `disabled_providers` (see [providers](../configure/providers.md#altimate-base)).
28+
- **Altimate Base** — a hosted open model, free and rate limited, with no signup or API key. Requests and responses may be logged and used to improve Altimate's products, so do not send secrets or confidential code. Every install registers it automatically at startup, whichever provider you pick — there is no confirmation dialog — and this notice is shown once, when Base is first used; it only becomes your model when nothing else you configured is usable. Opt out with `ALTIMATE_BASE_AUTO_REGISTER=0`, `altimate providers logout altimate-base`, or `disabled_providers` (see [providers](../configure/providers.md#altimate-base)).
2929
- **Search all providers…** — full picker if you need Bedrock, Databricks AI Gateway, Cloudflare AI Gateway, Snowflake Cortex, DigitalOcean Inference, etc.
3030

3131
Or set an environment variable and skip the picker:

‎docs/docs/reference/network.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -41,7 +41,7 @@ altimate needs outbound HTTPS access to:
4141
| Destination | Purpose |
4242
|-------------|---------|
4343
| Your LLM provider API | Model inference (Anthropic, OpenAI, etc.) |
44-
| Official Altimate Base gateway (embedded in release), or the host set by `ALTIMATE_BASE_GATEWAY_URL` | Altimate Base registration (automatic at startup on any install not yet registered, unless `ALTIMATE_BASE_AUTO_REGISTER=0` or after logging out of Base) and inference |
44+
| Official Altimate Base gateway (embedded in release), or the host set by `ALTIMATE_BASE_GATEWAY_URL` | Altimate Base registration (automatic at startup on any install not yet registered, unless `ALTIMATE_BASE_AUTO_REGISTER=0`, after logging out of Base, or during the 1–24 h retry backoff after a failed attempt) and inference |
4545
| `registry.npmjs.org` | Package updates |
4646
| `models.dev` | Model catalog (can be disabled) |
4747
| Your warehouse endpoints | Database connections |

‎docs/docs/reference/security-faq.md‎

Lines changed: 7 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -11,15 +11,18 @@ Answers to the most common security questions about running Altimate Code in you
1111

1212
## Does Altimate Code send my data to external services?
1313

14-
Altimate Code sends prompts and context to the LLM provider you configure (Anthropic, OpenAI, Azure OpenAI, AWS Bedrock, etc.). **You choose the provider.** No data is sent anywhere else except optional [telemetry](#what-telemetry-is-collected), which contains no code, queries, or credentials.
14+
Altimate Code sends prompts and context to the LLM provider you configure (Anthropic, OpenAI, Azure OpenAI, AWS Bedrock, etc.). **You choose the provider.** Beyond that provider, Altimate Code contacts the Altimate Base gateway to register this install (see below), and sends optional [telemetry](#what-telemetry-is-collected), which contains no code, queries, or credentials.
1515

16-
Altimate Base is Altimate's own hosted free model. Every install that is not yet registered
17-
registers it automatically at startup, whether or not you also have a model of your own — there is
16+
Altimate Base is Altimate's own hosted free model. By default, every install that is not yet
17+
registered registers it automatically at startup, whether or not you also have a model of your own.
18+
Registration sends only a hash of a random per-install secret and the CLI version, not your prompts or code. It is skipped when
19+
`ALTIMATE_BASE_AUTO_REGISTER=0` is set, after you log out of Base, when no gateway is configured, and
20+
during the retry backoff that follows a failed attempt. There is
1821
no confirmation dialog to accept. It only becomes your default model when nothing you configured is
1922
usable. Requests and responses are
2023
logged and may be used to improve Altimate products and services, including the model; secrets are
2124
automatically masked before storage, but don't rely on it — avoid sending secrets or confidential
22-
code. This notice is printed once — a toast in the TUI, or a one-line stderr notice the first time
25+
code. This notice is shown once — a toast in the TUI the first time Base becomes the active model, or a one-line stderr notice the first time
2326
a headless entrypoint (`run`, `serve`, `acp`, `web`) runs with Base registered — and is part of the Altimate
2427
Base service, separate from anonymous product telemetry. To opt out: set
2528
`ALTIMATE_BASE_AUTO_REGISTER=0` before Base ever registers, run `altimate providers logout

‎packages/opencode/src/server/server.ts‎

Lines changed: 13 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -71,6 +71,12 @@ globalThis.AI_SDK_LOG_WARNINGS = false
7171

7272
export namespace Server {
7373
const log = Log.create({ service: "server" })
74+
// altimate_change start — the Base credential every provider cache in this process is known to
75+
// reflect: set after the register route has disposed both registries for it. Unset until then,
76+
// because a cache built before a background registration finished cannot be told apart from one
77+
// built after it, in any directory or either registry.
78+
let appliedBaseCredential: string | undefined
79+
// altimate_change end
7480

7581
export const Default = lazy(() => createApp({}))
7682
// altimate_change start — upstream_fix: preserve upstream v1.17.9 /api HttpApi routes.
@@ -817,12 +823,12 @@ export namespace Server {
817823
const after = await FreeTier.credentials().catch(() => undefined)
818824
const changed = before?.apiKey !== after?.apiKey || before?.baseURL !== after?.baseURL
819825
// An unchanged file is not enough to skip: a startup registration that finished in the
820-
// background, or an expired/rejected credential that was refreshed in place, leaves this
821-
// server's cached provider state without Base. Skip only when Base is actually loaded.
822-
const baseLoaded = await Provider.list()
823-
.then((providers) => FreeTier.PROVIDER_ID in providers)
824-
.catch(() => false)
825-
if (!changed && baseLoaded) return c.json(outcome)
826+
// background leaves caches built before it without Base, in any directory and in either
827+
// registry. Skip only when this process has already reloaded for this exact credential.
828+
const fingerprint = after ? `${after.baseURL}\n${after.apiKey}` : undefined
829+
if (!changed && fingerprint !== undefined && fingerprint === appliedBaseCredential) {
830+
return c.json(outcome)
831+
}
826832
const disposed = await Promise.all([
827833
Instance.disposeAll().then(
828834
() => true,
@@ -839,6 +845,7 @@ export namespace Server {
839845
},
840846
),
841847
]).then((results) => results.every(Boolean))
848+
if (disposed) appliedBaseCredential = fingerprint
842849
return c.json(disposed ? outcome : { ...outcome, staleProviders: true as const })
843850
}
844851
return c.json(outcome)

‎packages/opencode/test/altimate/altimate-base-headless-disclosure.test.ts‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,9 @@ import path from "node:path"
44
import { FreeTier } from "../../src/altimate/free/client"
55
import { FreeTierConsent } from "../../src/altimate/free/consent"
66
import { FreeTierStore } from "../../src/altimate/free/store"
7+
import { isolateAltimateBaseHome } from "./_fixtures/altimate-base-harness"
8+
9+
isolateAltimateBaseHome("altimate-base-headless-disclosure")
710

811
// The headless notice (`run`, `serve`, `acp`, `web`) must reach a user whose registration finished
912
// in the background after the startup wait: that launch reported "pending" and every later launch

‎packages/opencode/test/server/altimate-base-registration.test.ts‎

Lines changed: 22 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -153,42 +153,40 @@ describe("Altimate Base registration route", () => {
153153
}
154154
})
155155

156-
test("skips instance disposal when registration is idempotent (credential unchanged)", async () => {
156+
test("skips instance disposal once this process has reloaded for the unchanged credential", async () => {
157157
const existing = { apiKey: "sk-existing", baseURL: "https://gateway.test", installSecret: "s" }
158-
mockCredentialsSequence(existing, existing)
158+
mockCredentialsSequence(existing)
159159
mockRegister(async () => existing)
160-
// Base is already loaded on this server, so there is genuinely nothing to re-read.
161-
const list = spyOn(Provider, "list").mockResolvedValue({
162-
[FreeTier.PROVIDER_ID]: {},
163-
} as unknown as Awaited<ReturnType<typeof Provider.list>>)
164160
const disposeAll = spyOn(Instance, "disposeAll")
165-
try {
166-
const response = await app().request("/altimate/base/register", {
161+
const post = () =>
162+
app().request("/altimate/base/register", {
167163
method: "POST",
168164
headers: { "content-type": "application/json" },
169165
body: JSON.stringify({}),
170166
})
171-
expect(response.status).toBe(200)
172-
expect(await response.json()).toMatchObject({ ok: true })
173-
// No staleProviders and no disposal: nothing changed, so there's nothing for a provider
174-
// loader to re-read, and no reason to tear down live sessions/LSPs/PTYs/MCP connections.
175-
expect(disposeAll).not.toHaveBeenCalled()
167+
try {
168+
// First call: unchanged on disk, but nothing yet shows this process's caches include it.
169+
expect(await (await post()).json()).toMatchObject({ ok: true })
170+
expect(disposeAll).toHaveBeenCalledTimes(1)
171+
// Second call: already reloaded for this credential, so there is nothing left to re-read,
172+
// and no reason to tear down live sessions/LSPs/PTYs/MCP connections again.
173+
expect(await (await post()).json()).toMatchObject({ ok: true })
174+
expect(disposeAll).toHaveBeenCalledTimes(1)
176175
} finally {
177176
disposeAll.mockRestore()
178-
list.mockRestore()
179177
}
180178
})
181179

182-
test("reloads when the credential is unchanged but this server has not loaded Base yet", async () => {
183-
// A startup auto-registration that finished in the background (or a credential refreshed in
184-
// place) leaves the file unchanged across this request while the cached provider state still
185-
// predates it; skipping would leave Base disconnected until a restart.
186-
const existing = { apiKey: "sk-existing", baseURL: "https://gateway.test", installSecret: "s" }
187-
mockCredentialsSequence(existing, existing)
188-
mockRegister(async () => existing)
189-
const list = spyOn(Provider, "list").mockResolvedValue(
190-
{} as unknown as Awaited<ReturnType<typeof Provider.list>>,
191-
)
180+
test("reloads for a credential registered in the background, even if one directory already sees Base", async () => {
181+
// A startup auto-registration that finished after the server started leaves the file unchanged
182+
// across this request, while caches built earlier (another directory, or the /api registry)
183+
// still predate it. Whether this request's own directory lists Base says nothing about those.
184+
const late = { apiKey: "sk-late", baseURL: "https://gateway.test", installSecret: "s" }
185+
mockCredentialsSequence(late)
186+
mockRegister(async () => late)
187+
const list = spyOn(Provider, "list").mockResolvedValue({
188+
[FreeTier.PROVIDER_ID]: {},
189+
} as unknown as Awaited<ReturnType<typeof Provider.list>>)
192190
const disposeAll = spyOn(Instance, "disposeAll")
193191
try {
194192
const response = await app().request("/altimate/base/register", {

0 commit comments

Comments
 (0)