# Configuration

heypi apps are configured in TypeScript with `createHeypi()`. The config object wires together app state, adapters, the Pi agent, runtime tools, optional features, and operational controls. Most apps use [`loadAgent()`](/docs/configuration/agent) to load the agent instructions, model, tools, context, and Pi extensions from a local folder.

```ts
createHeypi({
  state: { root: "./state" },
  adapters: [slack({ mode: "socket" })],
  agent: loadAgent("./agent", { model: "openai/gpt-5.4-mini" }),
  runtime: { root: workspace("./workspace") },
});
```

The main keys are:

| Key | Required | Details |
| --- | --- | --- |
| `state` | Yes | Durable app state directory. The default store writes SQLite data under `state.root`: threads, messages, calls, approvals, jobs, admin state, and locks. Runtime workspace files live under `runtime.root`, not `state.root`. |
| `adapters` | Yes | Chat or HTTP entrypoints. Built-ins cover Slack, Discord, Telegram, and webhook. Custom adapters can be passed here too. See [Adapters](/docs/adapters). |
| `agent` | Yes | The Pi agent: model, instructions, optional system override, dynamic context, tools, skills, and Pi extensions. See [Agent](/docs/configuration/agent). |
| `runtime` | Yes | Runtime workspace and execution backend. Runtime-backed default tools include `bash`, file tools, and search tools; `attach` and `history` are default tools too, but are documented with the agent tool surface. No default. See [Runtime](/docs/configuration/runtime) and [Agent tools](/docs/configuration/tools#default-tools). |
| `http` | Only for HTTP routes | Public Node HTTP listener for HTTP adapters and self-hosted secret pages. Defaults to `127.0.0.1:3000`; admin/dev routes use `admin.http`, which defaults to `127.0.0.1:4321`. See [HTTP listener](/docs/configuration/http). |
| `scope` | No | Default sharing boundary for runtime files, memory, skills, secrets, and attachments. Defaults to `channel`. See [Scope](/docs/configuration/scope). |
| `approval` | No | Who can list and resolve approval-gated calls, plus optional expiry. Tool confirmation decides which calls need approval. See [Approvals](/docs/configuration/approvals) and [Agent tools](/docs/configuration/tools#confirmation). |
| `task` | No | Same-thread behavior and cancellation policy while a task is active. Defaults to `busy: "steer"` and `cancel: "initiator"`. See [Task behavior](/docs/configuration/task). |
| `admin` | No | Local admin web panel, auth, login links, and state inspection. Disabled by default. See [Admin](/docs/configuration/admin). |
| `memory` | No | Durable scoped notes the agent can read and update. Disabled by default. See [Memory](/docs/configuration/memory) and [Agent tools](/docs/configuration/tools#managed-tools). |
| `skills` | No | Scoped procedures and runbooks the agent can create, patch, read, and delete. Disabled by default. See [Skills](/docs/configuration/skills) and [Agent tools](/docs/configuration/tools#managed-tools). |
| `secrets` | No | Encrypted browser handoff for sensitive values that should become runtime files. Disabled by default. See [Secrets](/docs/configuration/secrets). |
| `attachments` | No | Inbound files, generated-file delivery, size limits, document conversion, and custom attachment stores. See [Attachments](/docs/configuration/attachments) and the [`attach` tool](/docs/configuration/tools#default-tools). |
| `jobs` | No | Configured cron jobs and heartbeat jobs. Omit to disable scheduling; set `[]` to reconcile and pause previously configured jobs. See [Scheduling](/docs/configuration/scheduling). |
| `store` | No | Custom durable store. Defaults to SQLite under `state.root`. Needed only when you replace the default state backend, usually for multi-instance deployments. See [Custom integrations](/docs/guides/integrations#store). |
| `scheduler` | No | Scheduler polling and job lock behavior. Defaults: `pollMs: 30_000`, `lockMs: 600_000`. Most apps should keep them. See [Scheduling](/docs/configuration/scheduling#options). |
| `appLock` | No | Single-process app lock. Enabled by default with `ttlMs: 60_000` and `drainMs: 30_000`. Disable only when deployment ownership is handled elsewhere. See [Deployment](/docs/guides/deployment#process-ownership). |
| `messages` | No | User-facing system copy for busy replies, approval errors, cancellation, runtime startup, and generic failures. See [Task behavior](/docs/configuration/task#messages). |
| `logger` | No | Structured logging sink. Defaults to `consoleLogger({ level: "info", format: "pretty" })`; use JSON for log collectors. See [Deployment](/docs/guides/deployment#logging). |