# Software

agentOS ships with a common set of POSIX utilities (coreutils, sed, grep, gawk, findutils, diffutils, tar, gzip) out of the box. The `software` option installs additional packages, each providing one or more CLI commands.

## Install

```bash
npm install @rivet-dev/agentos @agentos-software/pi
```

Add packages like `@agentos-software/ripgrep` or `@agentos-software/jq` for anything beyond the default utilities. Browse the full catalog on the [Registry](/registry).

## Usage

Import the software packages you want, list them in the `software` array on the actor, then run commands through the client handle.

examples/software/server.ts:

```ts
import { agentOS, setup } from "@rivet-dev/agentos";
import pi from "@agentos-software/pi";
import ripgrep from "@agentos-software/ripgrep";
import jq from "@agentos-software/jq";

// Each entry adds its CLI commands to the VM. Common POSIX utilities ship by
// default; `pi` is the agent, and `ripgrep`/`jq` add the `rg` and `jq`
// commands. Browse the registry for more packages.
const vm = agentOS({
	software: [pi, ripgrep, jq],
});

export const registry = setup({ use: { vm } });

registry.start();
```

examples/software/client.ts:

```ts
import { createClient } from "@rivet-dev/agentos/client";
import type { registry } from "./server";

const client = createClient<typeof registry>({
	endpoint: "http://localhost:6420",
});
const agent = client.vm.getOrCreate("my-agent");

// `rg` (ripgrep) and `jq` are now available inside the VM. Find files containing
// "TODO" and pretty-print the matching paths as JSON.
const result = await agent.process.exec("rg --files-with-matches TODO /home/agentos | jq -R .");
console.log(result.stdout);
```

## Available Packages

Browse all available software packages on the [Registry](/registry).

## Custom Software

Package your own agents, command packages, and WASM commands. See [Software Definition](/agentos/docs/custom-software/definition) to define a package, and [Building Binaries](/agentos/docs/custom-software/building-wasm) to compile WASM commands from source in the [agentos registry](https://github.com/rivet-dev/agentos/tree/main/registry).