Getting started: from nothing to an agent answering in your terminal
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.
Shipped in the
arborbinary (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
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
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’sdev:block.AGENTS.md, for a coding agent working in the project.package.json,prompts/and.gitignore.
3. Run it on a local node
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: onmeans your builds are type-checked. If it saysoff, 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
.npmrcwarning on the first run matters only when another project installs this app’s packages from the node;arbor npm setupwrites that file. - Another port: set
dev.portinarbor.yaml, orARBOR_DEV_PORT=8790 arbor dev watch.
4. Talk to it
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:
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:
dev:
model:
name: gemma4:12b
api: chat # responses | chat | anthropic
base_url: http://localhost:11434/v1
- Restart
dev watchafter changingdev:. It reads the block when it starts. A change toapp.tsneeds no restart. - With no model set, a node calls
qwen3.8:27bthrough the Responses API athttp://localhost:11434/v1, which is Ollama’s default address. A flag or anARBOR_MODELvariable overrides the block. - A hosted model’s key goes in
.env, asARBOR_MODEL_API_KEYorARBOR_MODEL_HEADERS, never inarbor.yaml.init’s.gitignorealready leaves.envout of git.
Ask it something:
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:
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:
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:
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::
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:
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:
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”) anddocs/held-calls.md. - Deploying to another node:
arbor env set --name test --host https://…, thenarbor env login --env test --code <invite>with an invite from that node’s operator, andarbor deploy --env test(docs/agent.md, “Environments”). - What Arbor is underneath:
docs/core-model.md.
Installing from the source
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.