<!-- From docs/getting-started.md at Loa Arbor v0.2.6, as released. -->

> Coming soon: the Homebrew tap and Arbor's source aren't public yet, so the install steps below won't work for you today.

# Getting started: from nothing to an agent answering in your terminal

> Shipped in the `arbor` binary (`arbor docs get docs/getting-started.md`). Steps 1 to 9 were
> run on 2026-11-22 against arbor 0.2.4 installed from the tap, on macOS (Apple silicon) with a
> local model; where a step's output is shown, it is that run's, trimmed.

Arbor runs your app on a node: a process that keeps every actor's inbox, ledger and state, and
advances them one committed step at a time. You write the app in TypeScript; Arbor builds it,
type-checks it, and runs it. In nine steps you install Arbor, run an app on a node of your own,
turn it into an agent on a model, and let a customer and a staff member talk to it.

## 1. Install Arbor

```sh
brew tap loaapp/tap && brew trust loaapp/tap && brew install arbor
arbor --version
```

The tap builds for macOS on Apple silicon and for Linux on x86-64 and ARM64. It installs
TypeScript beside Arbor, so every build is type-checked. To build from the source instead, see
"Installing from the source" at the end of this page.

## 2. Create a project

```sh
arbor init --name hello
cd hello
```

`init` writes a project that runs as it is:
- `app.ts`, the app: one plain actor that answers every message with "hello: ".
- `arbor.yaml`, the project: its name, the environments it deploys to, the defaults every
  deploy carries, and the local node's `dev:` block.
- `AGENTS.md`, for a coding agent working in the project.
- `package.json`, `prompts/` and `.gitignore`.

## 3. Run it on a local node

```sh
arbor dev watch
```

```
local node: http://127.0.0.1:8787 (data in ~/.arbor/projects/hello)
type check: on (tsc 7.0.2)
Building: hello@0.1.0-dev.1 (ab601930…) - OK, 50ms
Deploying to local:
- revision 1 - OK
- latest -> 1
App: http://127.0.0.1:8787/ui/apps/hello
Watching for changes...
```

`dev watch` starts a node of the project's own: SQLite under `~/.arbor/projects/hello`,
listening on loopback only. It builds the app, publishes it, and does both again on every save.
Leave it running and use a second terminal for the steps below.

- **`type check: on`** means your builds are type-checked. If it says `off`, it names the
  command that installs TypeScript for the way you installed Arbor. A build that cannot be
  type-checked is still published, and says so.
- **The `.npmrc` warning** on the first run matters only when another project installs this
  app's packages from the node; `arbor npm setup` writes that file.
- **Another port:** set `dev.port` in `arbor.yaml`, or `ARBOR_DEV_PORT=8790 arbor dev watch`.

## 4. Talk to it

```sh
S=$(arbor session open)
arbor session send --session "$S" "hi there"
arbor session follow --session "$S" --until reply --for 60s
```

```
2 [session] participant_joined: {"participant":"p1","role":"user",…}
5 [-> greeter] user_msg: hi there
8 [greeter] reply: hello: hi there
```

A session is one conversation. `open` prints its id alone, so the shell can keep it. `send`
posts a message as you, and `follow` prints what the session says. With `--until reply` it stops
at the reply to your message, or after `--for` at the latest; without it, press Ctrl-C.

## 5. Make it an agent

An agent is an actor whose function is the model loop. Replace `app.ts` with:

```ts
import { agent, bundle } from '@arbor/sdk';

const desk = agent('desk', {
  instructions: 'You answer questions for a small bookshop. Answer briefly and plainly.',
}).wake('chat');

export default bundle({ app: 'hello', roots: [desk], session: { exposed: [desk] } });
```

Then tell the local node which model to call, in `arbor.yaml`'s `dev:` block. This run used a
local Ollama model:

```yaml
dev:
  model:
    name: gemma4:12b
    api: chat                       # responses | chat | anthropic
    base_url: http://localhost:11434/v1
```

- **Restart `dev watch` after changing `dev:`.** It reads the block when it starts. A change to
  `app.ts` needs no restart.
- **With no model set**, a node calls `qwen3.8:27b` through the Responses API at
  `http://localhost:11434/v1`, which is Ollama's default address. A flag or an `ARBOR_MODEL`
  variable overrides the block.
- **A hosted model's key goes in `.env`**, as `ARBOR_MODEL_API_KEY` or `ARBOR_MODEL_HEADERS`,
  never in `arbor.yaml`. `init`'s `.gitignore` already leaves `.env` out of git.

Ask it something:

```sh
S=$(arbor session open)
arbor session send --session "$S" "Do you sell second-hand books?"
arbor session follow --session "$S" --until reply --for 60s
```

```
26 [desk] reply: Yes, we have a selection of pre-loved books. What are you looking for?
```

`arbor session activity --session "$S"` tells you what happened, in words: what woke the desk,
the model call, its tokens and time, and the reply.

## 6. Give the model a role

A bundle never names a vendor's model. It names a **role**, and the node's settings map the
role to a model, so the same release runs on one model in development and another in
production. The role must be declared in the bundle:

```ts
const desk = agent('desk', { instructions: '…', model: 'fast' }).wake('chat');

export default bundle({
  app: 'hello', roots: [desk],
  models: { fast: { description: 'quick, cheap replies' } },
  session: { exposed: [desk] },
});
```

An agent that names an undeclared role fails the build. A declared role that nothing maps still
publishes, with the warning `model role "fast" is not mapped in the configuration (model.fast);
its agents run on the node's base model`. `arbor revision get r3` shows the warning on the
revision `dev watch` named (`- revision 3 - OK`). Map
the role on the node, review the change, then publish it:

```sh
arbor settings set model.fast.model=gemma4:12b model.fast.api=chat model.fast.base_url=http://localhost:11434/v1
arbor draft review
arbor draft publish
```

`settings set` only stages a change into the app's draft. `draft publish` makes it a revision,
and new sessions run on it. A role can also name `fallbacks`, up to four models tried in order
when the first fails, and another role as its `default`. Both are in `docs/scripting.md`
("Model roles").

## 7. Let people join

A session's people are its **participants**, each holding a role the app declares. Declare the
roles in the bundle and name the ones the agent takes posts from:

```ts
const desk = agent('desk', { instructions: '…', model: 'fast' })
  .wake('chat')
  .participants(['customer', 'staff']);

export default bundle({
  app: 'hello', roots: [desk],
  models: { fast: { description: 'quick, cheap replies' } },
  session: {
    roles: {
      customer: { max: 1, principal: true },
      staff: { max: 2, join: 'invite' },
    },
    exposed: [desk],
  },
});
```

The bundle grants nothing by itself. The settings say who may hold each role, by audience, in
`arbor.yaml`'s `defaults:`:

```yaml
defaults:
  role:
    customer: [employee, customer]
    staff: [employee]
```

On your local node you are the operator, with the audience `employee`, so you open sessions as
the customer. Staff join only by invitation:

```sh
S=$(arbor session open)
arbor session send --session "$S" "Do you have the new Le Guin biography?"
arbor session join --session "$S" --role staff --subject sam --audience employee
arbor session follow --session "$S" --until reply --for 60s
```

To act as Sam, for example to approve a call that waits for staff, use his own token:
`TOKEN=$(arbor dev token --subject sam --audience employee)`, then pass `--token "$TOKEN"` to
each command. `docs/agent.md` ("Held calls") shows how.

## 8. Look at it in the console

Open the `App:` address that `dev watch` printed, `http://127.0.0.1:8787/ui/apps/hello`. The
console shows the app's sessions. Each session has its Chat, its Activity (what each actor did,
in words), its Ledger (every committed step) and its Topology. On your local node it needs no
sign-in.

## 9. Read the documents from the shell

The documents ship in the binary, so they match the `arbor` you have:

```sh
arbor docs search "model roles"
arbor docs get docs/scripting.md    # writing an app: agents, actors, tools, hooks, modules
arbor docs get docs/agent.md        # the CLI as a coding agent uses it
```

## Next

- **Tools, held calls and approvals:** `docs/scripting.md` ("Script tools", and "Held calls:
  approval, client tools, external work") and `docs/held-calls.md`.
- **Deploying to another node:** `arbor env set --name test --host https://…`, then
  `arbor env login --env test --code <invite>` with an invite from that node's operator, and
  `arbor deploy --env test` (`docs/agent.md`, "Environments").
- **What Arbor is underneath:** `docs/core-model.md`.

## Installing from the source

```sh
git clone https://github.com/loaapp/arbor.git && cd arbor
make build                  # the console, the client and the binary: bin/arbor
pnpm -C sdk install         # TypeScript for the type check
./bin/arbor --version
```

`make build` needs Go, Node and pnpm. `pnpm -C sdk install` puts `tsc` where a node run from
the checkout finds it. Without it, `dev watch` says `type check: off` and names that command.
Put `bin/` on your `PATH`, or call `./bin/arbor`, and carry on from step 2.
