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

# TypeScript agents

> How a TypeScript or JavaScript agent is built and run: the two Node.js runtimes, package managers, running TypeScript directly, and reading the agent's own files.

A TypeScript or JavaScript agent is built from its folder into an image with the Node.js version you choose and your dependencies installed. You do not write a Dockerfile, and you do not need a build script.

| `runtime` | Language | Version |
| - | - | - |
| `python3.12` | Python | 3.12 |
| `python3.11` | Python | 3.11 |
| `node22` | TypeScript or JavaScript | Node.js 22 |
| `node20` | TypeScript or JavaScript | Node.js 20 |

## Package managers

The lockfile decides which package manager installs your dependencies, with a frozen install, so the build gets exactly what your lockfile says:

| Lockfile | Install |
| - | - |
| `bun.lock` or `bun.lockb` | `bun install --frozen-lockfile` |
| `pnpm-lock.yaml` | `pnpm install --frozen-lockfile` |
| `package-lock.json` | `npm ci` |
| `yarn.lock` | `yarn install --frozen-lockfile` |
| `package.json` alone | `npm install`, and the versions installed are recorded after the build |

Development dependencies are installed too, so `build.commands` can use them. See [Dependencies](/build/dependencies).

## TypeScript runs directly

Onecortex never runs your own `tsc`. It bundles your entrypoint and everything it imports from your own code into one file, for the Node.js version you chose, with inline source maps so a stack trace in your logs points at your source. Your dependencies stay in `node_modules` and load from there, so native modules keep working.

This means path aliases, ESM and CommonJS, and `tsconfig.json` project references all work without a build step. If your agent needs one anyway, such as code generation, declare it:

```yaml agent.yml theme={null}
build:
  commands:
    - bun run generate
```

`build.commands` runs after your dependencies are installed and before the bundle, in the agent folder, with no configuration or secrets available.

## Your agent's own files

The whole agent folder is in the image, and it is the working directory. An agent that reads a prompt or a data file at run time finds it where it is in your repository:

```ts agent.ts theme={null}
import { readFileSync } from 'node:fs'

const orders = JSON.parse(readFileSync('orders.json', 'utf8'))
```

## The architecture

Every agent runs on 64 bit ARM Linux. A dependency with a native binary needs a build for `linux-arm64`, which most publish.

## Related

* [Entrypoints](/build/entrypoints): how your agent object is found.
* [Frameworks](/frameworks/mastra): each TypeScript framework's page.
* [The `agent.yml` reference](/agent-yml).