> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentium.in/llms.txt
> Use this file to discover all available pages before exploring further.

# Install Agentium 4

> Install matching Agentium 4.0.0 packages, optional provider SDKs, and a TypeScript runner.

These docs target **Agentium 4.0.0**. Use Node.js **22.18+ within v22** or **24.11+ within v24**, with TypeScript in ESM mode. Install only the packages and provider SDKs your application uses.

## Set up your environment

Use `"type": "module"` in your application's `package.json`. New applications can use the [CLI project tutorial](/learn/create-project); existing applications can follow the [manual quickstart](/quickstart).

```bash theme={null}
node --version
npm install @agentium/core@4.0.0 openai zod
npm install --save-dev typescript tsx @types/node
```

Keep credentials in the server environment. The tutorials read `OPENAI_API_KEY` and allow `OPENAI_MODEL` to override the documented default. Setting environment variables alone does not load a `.env` file; use your host's environment loader if needed.

## Add a package

Keep Agentium packages on matching versions. Install the harness as its own package alongside core:

```bash theme={null}
npm install @agentium/core@4.0.0 @agentium/harness@4.0.0
```

For an Express application:

```bash theme={null}
npm install @agentium/core@4.0.0 @agentium/transport@4.0.0 express
npm install --save-dev @types/express
```

See the [package directory](/api-reference/packages) for all ten packages and the [harness quickstart](/harness/quickstart) for a provider-free first run.

## Optional dependencies

| Task | Additional dependencies in these guides |
| - | - |
| OpenAI text or embeddings | `openai` |
| Tool schemas | `zod`; public schemas support Zod 3, Zod 4 Classic, and Zod Mini |
| HTTP hosting | `express`; `@types/express` for development |
| Socket.IO | `socket.io` and the appropriate client |
| Browser automation | Follow the [browser setup](/browser/overview) |
| Persistent storage or queues | Follow the chosen [integration](/integrations/overview) |

Provider, database, browser, telephony, and queue SDKs are optional integration dependencies. An unrelated capability should not require installing all of them.

## Build a matching local checkout

For SDK development or an unpublished patch, build all required packages from the same revision:

```bash theme={null}
npm ci
npm run build
mkdir -p .artifacts
npm pack --workspace @agentium/core --pack-destination .artifacts
npm pack --workspace @agentium/harness --pack-destination .artifacts
```

Install those tarballs in your application, replacing the absolute paths:

```bash theme={null}
npm install /absolute/path/to/agentium/.artifacts/agentium-core-4.0.0.tgz /absolute/path/to/agentium/.artifacts/agentium-harness-4.0.0.tgz
```

Use the version in your checkout's package manifests when building a later revision. Local packages can share a release's version string while containing different changes; keep the source revision with your test results.

## Upgrade from 3.x

Read the [v4 migration guide](/migration-v4) before changing dependencies. V4 removes Agent-owned harness entrypoints and redundant protocol aliases, makes workspace and hosting modes explicit, and changes several integration contracts. Persistent queue metadata may need migration before upgrading BullMQ.

If your registry cannot resolve `4.0.0`, check that it is using the intended public registry or that your private mirror has received the release. Do not silently substitute a 3.x package for a v4 example.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.