{"_id":"@amd-gaia/gaia","_rev":"4-7e6455a9fcf9913eb16c91b4fd993e5b","name":"@amd-gaia/gaia","dist-tags":{"latest":"0.2.0"},"versions":{"0.0.0":{"name":"@amd-gaia/gaia","version":"0.0.0","license":"MIT","_id":"@amd-gaia/gaia@0.0.0","maintainers":[{"name":"kovtcharov-amd","email":"kalin.ovtcharov@amd.com"}],"homepage":"https://amd-gaia.ai","bugs":{"url":"https://github.com/amd/gaia/issues"},"dist":{"shasum":"27b2849fe1cb3d5934085db1c5a8f1b9f423aaff","tarball":"https://registry.npmjs.org/@amd-gaia/gaia/-/gaia-0.0.0.tgz","fileCount":2,"integrity":"sha512-JHmil5tbnF8wkt2Vhjw8O2nOf6xMntqW/Nl6l0IM27bnQLlqPkdjcmZsAzn+dznoT/Y0qGXOv//8wJRzgH80UA==","signatures":[{"sig":"MEUCIC4DZWosJtxjKnVuVqZpanBb64S+n/A/AmNGyL6Owo3GAiEAzHpwnRhEm+4CtROSzDvlJe2v0GDt0Ti/e9x+n9C+m/Y=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":812},"_npmUser":{"name":"kovtcharov-amd","email":"kalin.ovtcharov@amd.com"},"repository":{"url":"git+https://github.com/amd/gaia.git","type":"git","directory":"hub/agents/gaia/npm"},"_npmVersion":"11.11.0","description":"Placeholder reserving the name so npm trusted publishing (OIDC) can be configured. Do not install — see 0.1.0 and later.","directories":{},"_nodeVersion":"24.14.1","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/gaia_0.0.0_1787068575453_0.3535400376502347","host":"s3://npm-registry-packages-npm-production"}},"0.1.0":{"name":"@amd-gaia/gaia","version":"0.1.0","license":"MIT","_id":"@amd-gaia/gaia@0.1.0","maintainers":[{"name":"kovtcharov-amd","email":"kalin.ovtcharov@amd.com"}],"homepage":"https://amd-gaia.ai","bugs":{"url":"https://github.com/amd/gaia/issues"},"dist":{"shasum":"c30b0ce9674ce1596457a2b7e60c86cb3604c01a","tarball":"https://registry.npmjs.org/@amd-gaia/gaia/-/gaia-0.1.0.tgz","fileCount":2,"integrity":"sha512-/J2bPuOD5h5LdfyyXEHHyVrto6wsJse2L+tMVu4rvrc/T8HpBazbqVsUVvPXXw4cJqVrWSc9O/vEFs56K7fZXA==","signatures":[{"sig":"MEUCIGa3QWO+xCQmTeFJhhML6MLXsqyF0rys/a1tXfSGc5tZAiEA6CHX71i8euJZrShOjadXRaPvF/0ju74PvncfsxVxvqg=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":852},"_npmUser":{"name":"kovtcharov-amd","email":"kalin.ovtcharov@amd.com"},"repository":{"url":"git+https://github.com/amd/gaia.git","type":"git","directory":"hub/agents/gaia/npm"},"_npmVersion":"11.11.0","description":"Reserves the package so npm trusted publishing (OIDC) can be configured; OIDC cannot create a package. Not the CLI - see 0.1.1 and later.","directories":{},"_nodeVersion":"24.14.1","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/gaia_0.1.0_1787068774526_0.7627501308869613","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@amd-gaia/gaia","version":"0.1.1","keywords":["gaia","amd","ryzen-ai","agent","tui","local-llm","privacy","sidecar"],"author":{"name":"AMD AI Group"},"license":"MIT","_id":"@amd-gaia/gaia@0.1.1","maintainers":[{"name":"kovtcharov-amd","email":"kalin.ovtcharov@amd.com"}],"homepage":"https://amd-gaia.ai/docs/guides/gaia","bugs":{"url":"https://github.com/amd/gaia/issues"},"bin":{"gaia":"dist/cli.js"},"dist":{"shasum":"685b3e04c1e348b59939a7cabffd051cb8191c20","tarball":"https://registry.npmjs.org/@amd-gaia/gaia/-/gaia-0.1.1.tgz","fileCount":39,"integrity":"sha512-u5xJ8H1gRDOksOR8YOFuPvnX9n6MR8XZvMxbZ2qp2lPfhUPvZ3aA+yhsljz8EDZyMoZoDjdE3wTdrxeQ60QwRQ==","signatures":[{"sig":"MEUCIQC73kK1fLRKydXwjTkNboEGxMDswig+bdZ7ekcp5eX7swIgO8qysVtuUzYF3tUQUiB0vknhIGaITF8fLMLMkuQOodk=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@amd-gaia%2fgaia@0.1.1","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":187624},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=18"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"20e08190959029cac1ef0f683fa9e1a81d50e9d8","scripts":{"test":"vitest run","build":"tsc -p tsconfig.json","clean":"node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"","test:watch":"vitest","prepublishOnly":"npm run clean && npm run build"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:324b6a74-303a-41b6-bddf-d154fa52ecb2"}},"repository":{"url":"git+https://github.com/amd/gaia.git","type":"git","directory":"hub/agents/gaia/npm"},"_npmVersion":"12.0.2","description":"One command to run GAIA: fetches and SHA-256 verifies the flagship agent sidecar and the terminal UI, then launches them. Runs 100% locally on AMD Ryzen AI.","directories":{},"sideEffects":false,"_nodeVersion":"22.23.2","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^2.1.8","typescript":"^5.7.2","@types/node":"^22.10.0"},"_npmOperationalInternal":{"tmp":"tmp/gaia_0.1.1_1787352083466_0.0018915992008339266","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"_id":"@amd-gaia/gaia@0.2.0","bin":{"gaia":"dist/cli.js"},"bugs":{"url":"https://github.com/amd/gaia/issues"},"dist":{"shasum":"c996ea166bbf98b3d902518e29304236e24ca695","tarball":"https://registry.npmjs.org/@amd-gaia/gaia/-/gaia-0.2.0.tgz","fileCount":39,"integrity":"sha512-X8Gknghmuj450psOr/wfWXDL04uE4cljm6WpnOPLNcPGvqP6TDEDr4uaLG3bkINgvX59RAG2lCfJ3nqch8FIXA==","signatures":[{"sig":"MEYCIQCdHWLW92bbr0XwHzkwtSALYjdgRn9VUC6/ypOqunHPAwIhAIybxhtaISeo/7+KURafUzthU9RdJqTVoSKLIql2e39Z","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQC13owJJwlcjU9sCpPAUbB+kCHBZskQ4io/INXzZF5KuQIgLJVzjDAhA5E+WE8MlzKalv+mM/Tgsw/ZHzNjQRuENCI="}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@amd-gaia%2fgaia@0.2.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":254828},"main":"./dist/index.js","name":"@amd-gaia/gaia","type":"module","types":"./dist/index.d.ts","author":{"name":"AMD AI Group"},"engines":{"node":">=18"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"de33d9c190d4965e4618be8f991c3d7ddea64271","license":"MIT","scripts":{"test":"vitest run","build":"tsc -p tsconfig.json","clean":"node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"","test:watch":"vitest","prepublishOnly":"npm run clean && npm run build"},"version":"0.2.0","_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:324b6a74-303a-41b6-bddf-d154fa52ecb2"}},"homepage":"https://amd-gaia.ai/docs/guides/gaia","keywords":["gaia","amd","ryzen-ai","agent","tui","local-llm","privacy","sidecar"],"repository":{"url":"git+https://github.com/amd/gaia.git","type":"git","directory":"hub/agents/gaia/npm"},"_npmVersion":"12.0.2","description":"One command to run GAIA: fetches and SHA-256 verifies the flagship agent sidecar and the terminal UI, then launches them. Runs 100% locally on AMD Ryzen AI.","directories":{},"maintainers":[{"name":"kovtcharov-amd","email":"kalin.ovtcharov@amd.com"}],"sideEffects":false,"_nodeVersion":"22.23.2","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^2.1.8","typescript":"^5.7.2","@types/node":"^22.10.0"},"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/gaia_0.2.0_1789576565014_0.8099218594202975"}}},"time":{"created":"2026-08-18T15:56:15.222Z","modified":"2026-09-16T16:36:05.512Z","0.0.0":"2026-08-18T15:56:15.580Z","0.1.0":"2026-08-18T15:59:34.689Z","0.1.1":"2026-08-21T22:41:23.625Z","0.2.0":"2026-09-16T16:36:05.098Z"},"bugs":{"url":"https://github.com/amd/gaia/issues"},"author":{"name":"AMD AI Group"},"license":"MIT","homepage":"https://amd-gaia.ai/docs/guides/gaia","keywords":["gaia","amd","ryzen-ai","agent","tui","local-llm","privacy","sidecar"],"repository":{"url":"git+https://github.com/amd/gaia.git","type":"git","directory":"hub/agents/gaia/npm"},"description":"One command to run GAIA: fetches and SHA-256 verifies the flagship agent sidecar and the terminal UI, then launches them. Runs 100% locally on AMD Ryzen AI.","maintainers":[{"name":"kovtcharov-amd","email":"kalin.ovtcharov@amd.com"}],"readme":"# @amd-gaia/gaia\n\nOne command gets you a working GAIA:\n\n```bash\nnpx @amd-gaia/gaia\n```\n\nThat fetches the two binaries GAIA needs — the agent sidecar and the terminal UI —\nverifies both against a checksum manifest that ships inside this package, and drops\nyou into the terminal UI. No Python to install, no repo to clone, no build step.\nLocal inference is the default. The TUI can explicitly select Fireworks AI or AMD\nLLM Gateway through Lemonade; remote chat sends conversation history to that provider. The\nterminal UI's `--use-claude` flag, which would send a conversation to the\nAnthropic API, is refused for the agent this package installs — see\n[`SPEC.md` §5.5](./SPEC.md#55-other-transports).\n\nThe terminal UI you get here is the published **`terminal-hub`** component — the\nexact same binary a full GAIA install runs as `gaia tui`, not a separate build. So\nhowever you arrive at the terminal UI, it behaves identically.\n\n## What it actually does\n\n1. **Resolves your platform** — `win32-x64`, `darwin-arm64`, `darwin-x64`,\n   `linux-x64` (plus `linux-arm64` / `win32-arm64` for the terminal UI).\n2. **Reads `binaries.lock.json`**, the checksum manifest published with this exact\n   package version. It records, per binary, which hub lane it comes from and what\n   it must hash to.\n3. **Downloads and SHA-256 verifies both binaries.** A hash that does not match is\n   a hard failure — the download is deleted and the run stops. There is no\n   \"continue anyway\" path and no unverified fallback.\n4. **Launches the terminal UI**, which brings up the GAIA daemon and the agent\n   sidecar and hands you the chat. Its exit code becomes ours.\n\n## Requirements\n\n- **Node.js 18+** (for the built-in `fetch`).\n- **[Lemonade Server](https://amd-gaia.ai/docs/reference/dev)** running locally —\n  it hosts the model the agent thinks with. GAIA tells you if it isn't up.\n- The `gaia` Python CLI **0.23.1 or newer** on `PATH` for the daemon the terminal\n  UI starts. Earlier cores start a daemon that has no entry for this agent, so the\n  UI comes up with nothing behind it. Install it with\n  `curl -fsSL https://amd-gaia.ai/install.sh | sh` (Windows:\n  `irm https://amd-gaia.ai/install.ps1 | iex`).\n\n## Supported platforms\n\nThe terminal UI is Go and cross-compiles everywhere. The agent sidecar is a frozen\nPython build, produced on the machine it targets, and **has no arm64 Linux or arm64\nWindows build**. On those two platforms `npx @amd-gaia/gaia` stops with an error\nnaming your platform and the ones that do work — it will not start a UI with no\nagent behind it.\n\n| Platform key   | Agent sidecar | Terminal UI |\n| -------------- | :-----------: | :---------: |\n| `win32-x64`    |       ✅      |     ✅      |\n| `darwin-arm64` |       ✅      |     ✅      |\n| `darwin-x64`   |       ✅      |     ✅      |\n| `linux-x64`    |       ✅      |     ✅      |\n| `linux-arm64`  |       —       |     ✅      |\n| `win32-arm64`  |       —       |     ✅      |\n\n`npx @amd-gaia/gaia version` prints this matrix, plus the version and source URL of\neach binary, for the release you have installed.\n\n## Commands\n\n```\ngaia [run] [options] [-- <tui args>]   Fetch + verify both binaries, then launch the TUI\ngaia fetch [options]                   Download + verify only; print JSON and exit\ngaia serve [options]                   Run the agent sidecar alone (REST API, no TUI)\ngaia version                           Print the lock manifest and this host's platform\ngaia help                              Show help\n```\n\nAnything after a bare `--` goes to the terminal UI untouched:\n\n```bash\nnpx @amd-gaia/gaia -- --debug\n```\n\nCommon options:\n\n| Flag                  | Meaning                                                       | Accepted by |\n| --------------------- | ------------------------------------------------------------- | ----------- |\n| `--base-url <url>`    | Override the download base URL from `binaries.lock.json`. Must be `https:` | `run`, `fetch`, `serve` |\n| `--allow-insecure-base-url` | Permit a non-`https` `--base-url` (a trusted local mirror) | `run`, `fetch`, `serve` |\n| `--sidecar-dir <dir>` | Where to install the agent sidecar (default `~/.gaia/agents/gaia`) | `run`, `fetch`, `serve` |\n| `--cache-dir <dir>`   | Where to cache the terminal UI binary                          | `run`, `fetch` |\n| `--force`             | Re-download even when a verified binary is already cached      | `run`, `fetch`, `serve` |\n| `--platform <key>`    | Fetch for another platform                                     | `fetch` |\n| `--component <name>`  | Fetch only `sidecar` or `tui`                                  | `fetch` |\n| `--port <n>`          | Sidecar bind port (default `8141`)                             | `serve` |\n\nA flag a command does not read is **refused**, not ignored — `gaia run --port\n9000` exits 2 rather than silently coming up on the default port.\n\nSet `DEBUG=gaia` for download, spawn, and sidecar output on stderr. Diagnostics\nnever touch stdout, which the terminal UI owns.\n\n## Where things land\n\n| What            | Path                                     |\n| --------------- | ---------------------------------------- |\n| Agent sidecar   | `~/.gaia/agents/gaia/gaia-agent[.exe]`   |\n| Install record  | `~/.gaia/agents/gaia/.installed`         |\n| Terminal UI     | `~/.gaia/npm-cache/gaia-<version>/gaia-tui[.exe]` |\n\nThe sidecar goes into the GAIA daemon's own cache directory on purpose: the daemon\nis what spawns and supervises it, and it does its own SHA-256 check on the way. By\nputting an already-verified binary there we save a second download rather than\nracing one.\n\nThe `.installed` record next to it is what the daemon and the terminal UI read to\nknow the agent is installed — without it the UI would run the sidecar as its own\nstdio child instead of letting the daemon supervise it. It is rewritten even when\nthe binary was already cached, so an install left by an earlier version repairs\nitself the next time you run. A `--platform` fetch stages a binary for a\n*different* machine, so it deliberately leaves no record.\n\nThe terminal UI is installed as `gaia-tui`, **never** as `gaia` — a file named\n`gaia` in a cache directory would shadow the `gaia` shim npm puts on your `PATH`.\n\n## Ports\n\n| Service       | Port                              |\n| ------------- | --------------------------------- |\n| Agent sidecar | `8141` on `127.0.0.1`             |\n| GAIA daemon   | assigned at start, recorded in `~/.gaia/host/instance.json` |\n\nPort **4001 is reserved repo-wide** and is refused with an error if you pass it.\nBoth services bind loopback only — this agent speaks for your documents and memory\nand has no business on a LAN interface.\n\n## Running the sidecar on its own\n\n`gaia serve` skips the terminal UI and gives you the REST surface directly, for\nintegrating GAIA into your own app:\n\n```bash\nnpx @amd-gaia/gaia serve --port 8141\ncurl http://127.0.0.1:8141/health\n```\n\nIt waits for `GET /health`, checks the contract version, and tears the whole\nprocess tree down on Ctrl+C. See [`SPEC.md`](./SPEC.md) for the endpoints.\n\nThe sidecar normally requires a per-session bearer token on `/v1/gaia/*`, but\nneither `serve` nor `startSidecar` mints one, so both leave it in dev mode — the\ntoken check off, `Host`/`Origin` still enforced. This agent has shell and file\ntools, so before you expose it to anything, supply a token of your own: see\n[`SPEC.md` §5.4](./SPEC.md#54-caller-authentication).\n\n## Programmatic use\n\n```ts\nimport { randomUUID } from \"node:crypto\";\nimport { fetchAll, startSidecar, shutdown } from \"@amd-gaia/gaia\";\n\nconst { sidecar } = await fetchAll();               // both binaries, SHA-256 verified\nconst proc = await startSidecar({ binaryPath: sidecar.binaryPath });\n\nconst sessionId = randomUUID(); // reuse across the whole conversation, see below\n\nconst res = await fetch(`${proc.baseUrl}/v1/gaia/query`, {\n  method: \"POST\",\n  headers: { \"content-type\": \"application/json\" },\n  body: JSON.stringify({\n    query: \"summarize my notes\",\n    run_id: randomUUID(),\n    session_id: sessionId,\n    context: [],\n  }),\n});\n\nawait shutdown(proc);\n```\n\n`/v1/gaia/query` streams Server-Sent Events terminated by exactly one `final` or\n`error`. `fetchAll()` also returns the TUI's path if you would rather launch that.\n\n**Reuse the same `session_id` for every turn in a conversation.** It is what\nlets a document you had it index, or a skill you had it load, survive to the\nnext question — drop it (or mint a new one per call) and the agent still\nanswers, but it forgets everything from the previous turn. See\n[`SPEC.md` §5.2](./SPEC.md#52-session_id-and-agent-retention) for the retry\nand eviction behavior.\n\nEvery failure throws a typed error (`IntegrityError`, `PlatformError`,\n`HealthTimeoutError`, `VersionMismatchError`, `BinaryNotFoundError`) with a message\nthat names what failed and what to do about it.\n\n## Where the binaries come from\n\nThe two binaries ship from two different places, and `binaries.lock.json` records a\nversion and a source URL for each:\n\n| Binary        | Published as                              | Built by                         |\n| ------------- | ----------------------------------------- | -------------------------------- |\n| Agent sidecar | the `gaia` agent, at this package's version | this package's release           |\n| Terminal UI   | the `terminal-hub` component, at its own version | the core GAIA release       |\n\nThe terminal UI is **consumed, not rebuilt**. It is byte-for-byte the `gaia tui`\nbinary a core install ships, so there is no second copy that could lag behind or\nbehave differently — which is the entire reason it is sourced this way.\n\n## Integrity\n\n`binaries.lock.json` is the single source of truth for what gets downloaded and\nwhat it must hash to. The release pipeline regenerates it from the artifacts\nactually being served — the sidecars it just published, and the terminal-hub\nartifacts it downloaded and cross-checked against the hub's own recorded hashes.\n\nBetween releases the lock carries `PENDING-replace-with-real-sha256` placeholders.\n**A placeholder blocks the fetch outright** — before any network call — so an\nunverifiable binary can never be downloaded, let alone executed. If you need to run\nagainst a locally built binary, build it yourself and point the lifecycle helpers\nat it directly; the fetcher will not be talked into it.\n\n## Links\n\n- Guide: <https://amd-gaia.ai/docs/guides/gaia>\n- Technical reference: [`SPEC.md`](./SPEC.md)\n- Changes: [`CHANGELOG.md`](./CHANGELOG.md)\n- Issues: <https://github.com/amd/gaia/issues>\n\nMIT licensed. © 2024-2026 Advanced Micro Devices, Inc.\n","readmeFilename":"README.md"}