# Host Functions

Untrusted code should never hold your database password or API key. A host
function runs in your process with your credentials, and the guest only sees its
inputs and outputs. This is what makes
[Code Mode](/secure-exec/docs/use-cases/code-mode) useful: the model
writes one program that chains your tools.

## Define host functions

Host functions are a record of collections, keyed by name. Each function needs
only a Zod `inputSchema` and an `execute` handler; the keys name the collection
and the function, and `.describe()` on the schema documents it for the model.
Arguments from the guest are validated before your code runs.

`hostFunctions` is a VM option. Pass it on a call, or on `createVm`.

secure-exec/examples/host-functions/src/index.ts:

```ts
// Host functions run in your process, with your credentials. The guest only
// sees their inputs and outputs. The keys name the collection and the function,
// and `execute` receives the input its own schema describes.
const total = await evaluate<number>(generated, {
	hostFunctions: {
		orders: {
			list: {
				inputSchema: z
					.object({ customer: z.string() })
					.describe("List a customer's orders."),
				execute: ({ customer }) => [
					{ customer, amount: 40 },
					{ customer, amount: 2 },
				],
			},
		},
	},
	inputs: { customer: "customer_123" },
	timeoutMs: 5_000,
	output: { capture: "stderr" },
});
console.log(total.outcome === "succeeded" ? total.value : total.stderr); // 42
```

## Call them from guest code

Inside the VM each collection is a global object and each function is async.

secure-exec/examples/host-functions/src/index.ts:

```ts
// Inside the VM each collection is a global, and each function is async. This
// is the code a model would write.
const generated = `(async () => {
	const list = await orders.list({ customer: inputs.customer });
	return list.reduce((sum, order) => sum + order.amount, 0);
})()`;
```

- Keys round-trip: `orderStore.listOrders` in your options is
  `orderStore.listOrders(input)` in the guest and `agentos-order-store
  list-orders` on the CLI.
- Each function takes one input object and resolves to what your `execute`
  returned. A schema violation, a thrown error, or a timeout rejects the promise.
- The globals are frozen. A collection whose name is already a global, such as
  `process`, is not defined, and a warning is written to stderr.
- The `hostFunction` permission scope gates which functions a guest may call. See
  [permissions](/secure-exec/docs/permissions).

The same functions are also available to shell scripts and other languages as
commands. Read the [agentOS host functions
reference](/agentos/docs/host-functions) for that, and for schemas, timeouts,
and examples.