Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions bun.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion docs/commands.md
Original file line number Diff line number Diff line change
Expand Up @@ -362,7 +362,7 @@ Usage: atc connect [agent] [options]
Connection details or launch an installed agent

Arguments:
[agent] atomic-agent, claude, codex or opencode; omit for connection details
[agent] Agent ID from the connection catalog; omit for connection details

Options:
--model <value> Model ID; defaults to first ready chat model
Expand Down
12 changes: 12 additions & 0 deletions docs/decisions/2026-11-17-configure-agents-through-core.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
---
date: 2026-11-17
title: "Configure agents through core"
---

# Configure agents through core

- **Context:** Atomic Server offered isolated launch profiles for four agents. Agents such as Hermes required manual configuration even though core already knew how to edit their settings.
- **Decision:** Use the core integration catalog, host detection, configuration writers and launch arguments. The connection guide invokes a host operation after verifying the loaded model. CLI and terminal launches use core's launch environment, including for agents that select providers at startup.
- **Consequences:** Agents are configured for the server account where they are installed. Clients on other hosts and editors without a core writer receive endpoint details for manual setup. The host operation returns status and a launch command with a key ID, never the key. The isolated profile export remains available to existing CLI clients.
- **Compatibility:** The patch to core 0.23.4 exposes its existing integration module and adds the Muse arguments for an embedding server. Remove the patch when pinning a core release with both changes.
- **Owner:** team.
11 changes: 11 additions & 0 deletions docs/decisions/2026-11-17-show-terminal-agent-setup-progress.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
---
date: 2026-11-17
title: "Show progress when opening terminal agent setup"
---

# Show progress when opening terminal agent setup

- **Context:** The server overview drew a full agent card, but only its Configure label accepted a click. After that click, model and engine reads could leave the terminal looking idle.
- **Decision:** Give the card one full-surface target and show a status while the connection guide reads local model and engine choices, using the existing setup deadline.
- **Consequences:** The title and body open the same review as Configure. Loading a model and preparing a connection still requires the review action.
- **Owner:** team.
4 changes: 4 additions & 0 deletions docs/decisions/INDEX.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,10 @@ add a new one that says which record it supersedes.

## Records

- **2026-11-17** — [Configure agents through core](2026-11-17-configure-agents-through-core.md) — use the shared registry for host configuration and launches.

- **2026-11-17** — [Show progress when opening terminal agent setup](2026-11-17-show-terminal-agent-setup-progress.md) — make the full agent card clickable and show the options check.

- **2026-11-17** — [Pair terminal connection engines with models](2026-11-17-pair-terminal-connection-engines-with-models.md) — filter the connection guide by active engines and compatible downloads.

- **2026-11-17** — [Open the dashboard from terminal onboarding](2026-11-17-open-dashboard-from-terminal-onboarding.md) — save completion and let downloads continue without loading the selected model.
Expand Down
2 changes: 1 addition & 1 deletion docs/desktop-flow-parity.md
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,7 @@ These are capability or terminal adaptations, not claims of exact desktop featur
- Foundry Local uses the inline catalog family layout. A missing engine opens its installation controls; accelerator preparation runs from the family and returns there. Core compatibility blockers remain enforced.
- Managed engine host permissions, engine-specific options and some diagnostics retain the existing server operation forms. Native desktop settings that have no server equivalent are not copied.
- The terminal uses ASCII art and responsive text columns instead of raster model artwork. Search and credential text entry use a focused terminal editor. Compact terminals use a section menu and fewer metadata columns; supported minimum is 54×24.
- Hardware memory-fit estimates, undocumented model metadata and native provider OAuth are not fabricated. External agent installation/config-file writing is offered only where a supported launch profile exists; other agents receive manual connection details.
- Hardware memory-fit estimates, undocumented model metadata and native provider OAuth are not fabricated. The connection guide uses core to configure supported agents on the server host. Editors without a core writer and agents absent from that host receive manual connection details.
- A working Cloudflare installation is required for remote tunnels. API/engine failures are shown as failures, not simulated success.

## User journeys and verification
Expand Down
5 changes: 4 additions & 1 deletion package.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "@atomicbot-ai/atc",
"version": "0.2.18",
"version": "0.2.19",
"description": "atc — the Atomic Chat server CLI: install an inference engine, pull a model, serve it over an OpenAI-compatible API, and manage it from a local web admin.",
"license": "Apache-2.0",
"repository": {
Expand Down Expand Up @@ -53,6 +53,9 @@
"pdfjs-dist": "4.8.69",
"react": "^19.2.0"
},
"patchedDependencies": {
"@atomic-chat/core@0.23.4": "patches/@atomic-chat%2Fcore@0.23.4.patch"
},
"devDependencies": {
"@eslint/js": "^9.36.0",
"@types/node": "^22.18.0",
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -66,6 +66,7 @@ export function ConnectionGuide({
onConfigure?.()
setStep('preparing')
setError('')
setProfile(null)
try {
setStatus('Loading model')
await execute('models.load', { provider: engine, model_id: modelId })
Expand All @@ -89,7 +90,14 @@ export function ConnectionGuide({
await execute('setup.complete', { model_id: modelId })
const info = record(await execute('connection.info'))
setEndpoint(text(info.endpoint, `http://127.0.0.1:${port}${w.snapshot?.api.prefix ?? '/v1'}`))
if (path === 'agent' && PROFILE_AGENTS.includes(agent)) {
if (
path === 'agent' &&
Array.isArray(info.configurable_agents) &&
info.configurable_agents.includes(agent)
) {
setStatus('Configuring agent on the server host')
setProfile(record(await execute('connection.configure', { agent, model: modelId, key_id: key })))
} else if (path === 'agent' && PROFILE_AGENTS.includes(agent)) {
setStatus('Preparing agent connection')
setProfile(record(await execute('connection.profile', { agent, model: modelId, key_id: key })))
}
Expand Down Expand Up @@ -202,14 +210,18 @@ export function ConnectionGuide({
return typeof v === 'string' ? v : text(record(v).token ?? record(v).key, '')
}}
/>
{path === 'agent' && !profile && (
{path === 'agent' && !profile?.launch_command && !profile?.command && (
<p>
{profile?.reason ? `${text(profile.reason)} ` : ''}
In {name}, choose an OpenAI-compatible provider and paste this endpoint, API key, and model ID.
</p>
)}
{profile && (
{(profile?.launch_command || profile?.command) && (
<>
<p>Run this command to launch {name} with the prepared connection.</p>
<p>
Run this command {profile.configured === true ? 'on the server host ' : ''}to launch {name}{' '}
with the prepared connection.
</p>
<pre>{text(profile.launch_command ?? profile.command)}</pre>
<Copy value={text(profile.launch_command ?? profile.command, '')} label="Copy launch command" />
</>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,26 @@ import { expect, it, vi } from 'vitest'
import { workspaceFixture } from '@/test/workspace-fixture'
import { ConnectionGuide } from './ConnectionGuide'

it('configures Hermes on the server host through core', async () => {
const { workspace, execute } = workspaceFixture({
'models.installed': [{ id: 'qwen', name: 'Qwen', providers: ['llamacpp-upstream'] }],
'keys.list': [{ id: 'key' }],
'connection.info': { endpoint: 'http://127.0.0.1:1339/v1', configurable_agents: ['hermes'] },
'connection.configure': { configured: true, launch_command: 'atc connect hermes --model qwen' },
})
render(
<ConnectionGuide workspace={workspace} initialAgent="hermes" onClose={vi.fn()} onSettings={vi.fn()} />
)
await userEvent.click(await screen.findByRole('button', { name: 'Configure & start' }))
expect(await screen.findByRole('button', { name: 'Copy launch command' })).toBeInTheDocument()
expect(execute).toHaveBeenCalledWith('connection.configure', {
agent: 'hermes',
model: 'qwen',
key_id: 'key',
})
expect(screen.getByText(/on the server host to launch Hermes Agent/)).toBeInTheDocument()
})

it.each([true, false])('connects without restarting the unchanged API (running=%s)', async (running) => {
const { workspace, execute } = workspaceFixture({
'models.installed': [{ id: 'qwen', name: 'Qwen', providers: ['llamacpp-upstream'] }],
Expand Down
40 changes: 40 additions & 0 deletions patches/@atomic-chat%2Fcore@0.23.4.patch
Original file line number Diff line number Diff line change
@@ -0,0 +1,40 @@
diff --git a/package.json b/package.json
--- a/package.json
+++ b/package.json
@@ -31,6 +31,10 @@
"types": "./dist/host/index.d.ts",
"import": "./dist/host/index.js"
},
+ "./integrations": {
+ "types": "./dist/integrations/index.d.ts",
+ "import": "./dist/integrations/index.js"
+ },
"./models": {
"types": "./dist/models/index.d.ts",
"import": "./dist/models/index.js"
diff --git a/dist/integrations/catalog.js b/dist/integrations/catalog.js
--- a/dist/integrations/catalog.js
+++ b/dist/integrations/catalog.js
@@ -331,7 +331,9 @@
* The arguments that start `agent` on `model`: its fixed `runArgs`, plus `--model atomic/<id>` for
* Kilo, which otherwise opens on the model it last used before the one its config selects.
*/
-export function runArgsFor(agent, model) {
+export function runArgsFor(agent, model, apiUrl) {
+ if (agent.id === 'muse' && apiUrl)
+ return ['--provider', 'meta', '--base-url', apiUrl, ...(model ? ['--model', model] : [])];
return agent.id === 'kilo' && model ? ['--model', `atomic/${model}`, ...agent.runArgs] : [...agent.runArgs];
}
/**
diff --git a/dist/integrations/catalog.d.ts b/dist/integrations/catalog.d.ts
--- a/dist/integrations/catalog.d.ts
+++ b/dist/integrations/catalog.d.ts
@@ -63,7 +63,7 @@
* The arguments that start `agent` on `model`: its fixed `runArgs`, plus `--model atomic/<id>` for
* Kilo, which otherwise opens on the model it last used before the one its config selects.
*/
-export declare function runArgsFor(agent: Agent, model: string): string[];
+export declare function runArgsFor(agent: Agent, model: string, apiUrl?: string): string[];
/**
* Poolside's docs give the standalone base URL with its API prefix (`/v1`), so it is kept; only
* surrounding whitespace and trailing slashes go.
11 changes: 8 additions & 3 deletions src/agent-launch/context-window.ts
Original file line number Diff line number Diff line change
Expand Up @@ -50,12 +50,17 @@ export async function readServedWindow(
}

/** Refuses a known window too small for the agent; an unknown one is left to the agent. */
export function checkAgentWindow(agent: string, model: string, contextLength: number | undefined): void {
if (contextLength === undefined || contextLength >= AGENT_MIN_CONTEXT) return
export function checkAgentWindow(
agent: string,
model: string,
contextLength: number | undefined,
minimum = AGENT_MIN_CONTEXT
): void {
if (contextLength === undefined || contextLength >= minimum) return
const tokens = (n: number) => n.toLocaleString('en-US')
throw new AtcError(
'ATC_USAGE',
`${agent} needs a context window of at least ${tokens(AGENT_MIN_CONTEXT)} tokens; ${model} is served with ${tokens(contextLength)}.`,
`${agent} needs a context window of at least ${tokens(minimum)} tokens; ${model} is served with ${tokens(contextLength)}.`,
{
hint: 'Load the model with a larger context size (turn off "Fit context to device memory" in the engine settings), or choose a smaller model.',
}
Expand Down
28 changes: 28 additions & 0 deletions src/agent-launch/core-integration.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
import { expect, it, vi } from 'vitest'
import { tmpDataFolder } from '../../test/helpers/tmp-data-folder.js'
import { prepareCoreAgent } from './core-integration.js'

it('uses core launch arguments and the server credential for Muse', async () => {
const tmp = tmpDataFolder()
try {
const home = tmp.paths.dataFolder
const endpoint = 'http://127.0.0.1:1339/v1'
const launch = await prepareCoreAgent('muse', endpoint, 'local-model', 'server-key', {
cwd: home,
folder: home,
platform: 'linux',
env: { HOME: home, OPENAI_API_KEY: 'other-provider' },
exec: vi.fn(),
find: (bin) => (bin === 'muse' ? '/usr/bin/muse' : undefined),
request: async () => Response.json({ data: [{ id: 'local-model', context_length: 65536 }] }),
})
expect(launch).toMatchObject({
command: '/usr/bin/muse',
args: ['--provider', 'meta', '--base-url', endpoint, '--model', 'local-model'],
env: { META_API_KEY: 'server-key' },
})
expect(launch.env).not.toHaveProperty('OPENAI_API_KEY')
} finally {
tmp.cleanup()
}
})
103 changes: 103 additions & 0 deletions src/agent-launch/core-integration.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,103 @@
import {
apiUrlFor,
childEnv,
configureAgent,
CONFLICTING_PROVIDER_ENV,
detectAgent,
findAgent,
HERMES_CONTEXT_LENGTH,
registeredAgents,
runArgsFor,
} from '@atomic-chat/core/integrations'
import { AtcError } from '../errors/index.js'
import { checkAgentWindow, readServedWindow } from './context-window.js'
import { AGENTS, type AgentLaunch } from './plan.js'
import type { AgentHost } from './prepare.js'
import { spawnTarget } from './spawn-target.js'

export type IntegrationHost = Pick<AgentHost, 'env' | 'platform' | 'find' | 'exec'>
const writers = new Set(registeredAgents())

export function coreAgent(id: string) {
const agent = findAgent(id)
return agent && writers.has(agent.id) ? agent : undefined
}

const legacyAgent = (id: string) => AGENTS.find((agent) => findAgent(agent.id)?.id === id)

/** Configure the active profile on the host that owns the agent, using the core's writer. */
export async function configureCoreAgent(
id: string,
endpoint: string,
model: string,
key: string,
host: IntegrationHost,
context?: number | (() => Promise<number | undefined>)
) {
const agent = coreAgent(id)
if (!agent) throw new AtcError('ATC_USAGE', 'This agent uses manual endpoint setup.')
const onPath = (legacyAgent(agent.id)?.bins ?? [agent.detectBin]).map((bin) => host.find(bin)).find(Boolean)
const detection = await detectAgent(agent, {
platform: host.platform,
env: host.env,
onPath: async () => Boolean(onPath),
})
if (!detection.installed)
return { agent, reason: `${agent.name} was not found on the server host.` } as const
const contextLength = typeof context === 'function' ? await context() : context
checkAgentWindow(
agent.name,
model,
contextLength,
agent.id === 'hermes' ? HERMES_CONTEXT_LENGTH : undefined
)
const url = new URL(endpoint)
const apiPrefix = url.pathname.replace(/\/$/, '')
const apiUrl = apiUrlFor(agent, url.origin, apiPrefix)
const program = detection.path ?? onPath ?? detection.program
await configureAgent(agent, apiUrl, model, key, {
env: host.env,
platform: host.platform,
program,
spawn: async (program, args) => {
const result = await host.exec(program, args, { env: host.env })
return { code: result.code ?? 1, stdout: result.stdout, stderr: result.stderr }
},
...(contextLength ? { contextLength } : {}),
})
return { agent, program, apiUrl, apiPrefix, contextLength } as const
}

export async function prepareCoreAgent(
id: string,
endpoint: string,
model: string,
key: string,
host: AgentHost
): Promise<AgentLaunch> {
const result = await configureCoreAgent(id, endpoint, model, key, host, () =>
readServedWindow(host.request, endpoint, key, model)
)
if ('reason' in result) {
const legacy = legacyAgent(result.agent.id)
throw new AtcError(
'ATC_USAGE',
`${legacy?.name ?? result.agent.name} is not installed on PATH. Install it from ${legacy?.docs ?? result.agent.docsUrl}`
)
}
const { agent, program, apiUrl, apiPrefix, contextLength } = result
const args = runArgsFor(agent, model, apiUrl)
const env = { ...host.env }
for (const name of CONFLICTING_PROVIDER_ENV) delete env[name]
const target = spawnTarget(program, args, host.platform)
return {
command: target.file,
args: target.args,
cwd: host.cwd,
env: {
...env,
...childEnv(agent, apiUrl, model, key, { apiPrefix, ...(contextLength ? { contextLength } : {}) }),
},
...(target.windowsVerbatimArguments ? { windowsVerbatimArguments: true } : {}),
}
}
2 changes: 2 additions & 0 deletions src/agent-launch/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -5,3 +5,5 @@ export { prepareAgent } from './prepare.js'
export type { AgentHost } from './prepare.js'
export { runAgent } from './interactive.js'
export { AGENT_MIN_CONTEXT, checkAgentWindow, servedWindow } from './context-window.js'
export { configureCoreAgent, coreAgent, prepareCoreAgent } from './core-integration.js'
export type { IntegrationHost } from './core-integration.js'
Loading
Loading