Nebo · tutorial 01 · foundations
Set up your team
Hire your first AI employee, connect it to real work, decide what it may do without asking, and add a second one that picks up where the first leaves off.
Most people install Nebo, chat with it once, and stop. That is a shame, because chat is the least interesting thing it does. This tutorial gets you to the actual product: named employees that hold a job, arrive already wired to their tools, run on a trigger, and hand work to each other.
Everything below is done once. Every other tutorial in this set assumes you have finished this page.
What an employee actually is
Four things, and it helps to know which is which, because they fail differently.
| Part | What it holds | When it is wrong you see |
|---|---|---|
PersonaAGENT.md | The job description. Priorities, judgment, what it does and refuses to do. | Correct work, wrong voice or wrong instincts. |
Wiringagent.json | Workflows, triggers, required plugins, skills, configurable inputs. | Nothing happens, or happens at the wrong time. |
| Skills | Markdown procedures for a specific recurring task. | It improvises a task it should perform the same way every time. |
| Plugins | Native binaries that actually touch mail, calendars, ledgers, phones. | It describes doing the thing instead of doing it. |
Durable rules belong in the persona; today's task belongs in the message. "Never send outbound without approval" is a persona rule forever. "Research these 25 accounts" is a message.
Step by step
Pick the department before the person
Nebo organises employees into nine departments. This is not decoration — the department drives the marketplace browse, the Inbox filter, and how you will find anything once you have a dozen employees.
Decide which department has the most repetitive, most-skippable work this week.
That is where your first hire goes. Resist starting in executive — a
coordinator with nobody to coordinate is just a slower chat window.
Hire from the marketplace
Find a role in the marketplace and copy its install code. Codes look like this, and the prefix tells you what you are installing:
| Prefix | Installs |
|---|---|
AGNT-XXXX-XXXX | An employee |
SKIL-XXXX-XXXX | A skill |
PLUG-XXXX-XXXX | A plugin |
WORK-XXXX-XXXX | A standalone workflow |
COLL-XXXX-XXXX | A collection — several of the above at once |
Paste the code straight into the chat box. You do not need to find a settings screen; Nebo recognises the shape of the code and installs it.
Installing an employee cascades, in this order:
- Its required plugins install
- Skills referenced by its workflows install
- Any additional skills install, and those pull their own plugin dependencies
- Its trigger bindings register
- Its persona loads
So a single code can pull in six or seven components. That is intended — the role arrives able to do the job rather than as an empty shell you have to equip.
Connect the tools it needs
A plugin is installed but not yet authorised. Open the employee, ask it to do something requiring the tool, and it will tell you what it is missing. Authorise through the connection flow rather than pasting credentials into the chat — a password typed into a conversation is a password stored in a conversation.
Connections are authorised per account, not per task. If you authorise your
personal mailbox for a support role, that role can reach your personal
mailbox. Use a role account — support@, not you@.
Set the gate before you give it work
Do this now, while you remember, not after the first surprise. Go to Settings → the employee → Controls. Every gated operation gets one of three settings:
| Setting | Meaning |
|---|---|
always | Performs it without asking. |
approval | Stops and asks you first. The default. |
blocked | Removed from the employee entirely — it cannot attempt it. |
An operation is gated when it moves money, contacts someone outside your company, or writes something you cannot take back. Reads are not gated: searching your knowledge base is ungated, adding to it is gated, and that asymmetry is on purpose.
Money movement and contract operations are marked critical, and a critical operation cannot be loosened by flipping a global convenience setting. The only way to let an employee move money unattended is to set that specific operation on that specific employee. There is no master switch that quietly opens everything, which is exactly what you want the first time you are tired and clicking fast.
Start stricter than feels necessary. Loosening later takes ten seconds; explaining an email your employee sent to a customer takes considerably longer.
Do the job once, by hand
Do not schedule anything yet. Ask for the real job in conversation, look hard at what comes back, and correct it. Then ask again and see whether the correction held.
You are looking for one thing: is this the artefact I would have made myself? Not "is this impressive." If the answer is no after three corrections, the problem is usually the persona, not the prompt — the role is missing a judgment rule it needs to hold permanently.
A correction you would give again next week belongs in the persona. A correction specific to this one task belongs in the message and should be forgotten. Putting task detail in the persona is the most common way a good employee slowly goes stale.
Turn the good version into a workflow
A conversation that worked once is not a routine. A workflow is declared steps, so the next run is the same run, and so a step that must call a tool cannot quietly report success without calling it.
Workflows have a doctrine worth internalising early:
Any step whose output is data — a parsed file, a converted record, a state commit — must be a deterministic node, never a model activity. Asking a model to "output this JSON exactly" is a hallucination trap even with byte-for-byte instructions: invented rows, mislabelled outcomes, and state committed for writes that never happened are all observed failures. Put the model where judgment lives — classification, matching, prose — and hand it pointers to data rather than the data itself.
So a workflow mixes two kinds of step. Model activities do the thinking. Typed
nodes — command, condition, loop, http, wait — run with no model in the path at all, and a command node's stdout is its output byte for byte.
Two authoring habits keep runs honest:
- Fewer, denser steps, each ending on an artefact. Put conditional sub-actions inside a step ("if X, also do Y") rather than making them separate steps.
- The final step must end affirmatively — the path, the JSON, the summary. A last step that reports "nothing to do" can get promoted into a run-level exit.
Give it a trigger
Seven ways work arrives. Pick by how the work actually shows up, not by habit.
| Trigger | Fires when | Good for |
|---|---|---|
schedule | A cron expression comes due | Morning briefs, nightly research |
heartbeat | Every interval, optionally in a window | Business-hours polling |
watch | A plugin streams a change | Mailboxes and queues, without polling |
folder | Matching files change on disk | Scan-to-process, dropped documents |
event | Another employee emits | Handoffs between roles |
webhook | Something POSTs to your endpoint | Website forms, CRM events |
manual | You ask | Everything, while you are still teaching it |
A folder trigger takes extensions and a debounce, so a scanner writing a large PDF does not fire three runs while the file is still being written:
Hire the second employee and connect them
This is the part that makes it a team rather than a collection. A workflow can emit a named event when it finishes, and another employee can use an event trigger to listen for it.
Build the chain in the direction work actually flows. The receptionist qualifies, and emits. The closer listens, and follows up. Neither one knows about the other's tools, which is the point: if the closer's mail connection breaks, the receptionist keeps answering.
Resist giving both roles every connection "so they can help each other." Split roles exist so that a mistake in one has a small blast radius. An employee that can do everything is a single employee with extra steps.
Decide what each employee remembers
Memory has three layers, and an employee's configuration decides which it sees.
| Setting | Reads | Writes |
|---|---|---|
| Default | Its own memory | Its own memory |
inherit_user | Your preferences, read-only, plus its own | Its own |
context_isolated | Per-context only | Per-context only |
| Both | All three layers | Per-context only |
Turn on inherit_user for anything that writes in your voice — it picks
up timezone, language and style without you restating them. Turn on context_isolated when separate conversations must not bleed into each
other.
Each company's knowledge base is a physically separate database, isolated at the token boundary — that separation is solid. Isolation within one company, between employees or between individual client matters, is a narrower guarantee. If you are handling files where one client must never see another's, confirm the current behaviour before you rely on it rather than assuming the setting name covers it.
Add a coordinator, but only now
Once you are past three or four employees, the reporting gets noisy and a coordinator earns its seat. Hire one, give it almost no connections of its own, and have it route work and return one consolidated digest.
The rule that keeps this working: a coordinator must never do a specialist's job. The moment it starts doing the work itself it becomes the bottleneck, and you have rebuilt a single overloaded assistant with extra latency.
Creating, editing, or retiring another employee should require your approval. A coordinator that can restructure your workforce unattended is the one employee capable of changing every other employee's permissions.
Before you walk away
- Every employee's Controls reviewed, not left at whatever the role shipped with
- Every connection pointed at a role account, not your personal one
- At least one full run watched end to end, including what it chose not to do
- The persona holds your durable corrections; the messages hold nothing permanent
- One trigger, not five, until the first has run clean for a week
When it goes wrong
It said it finished, but nothing actually happened
The classic failure: a run reports success while the tool was never called. This is exactly what declared workflows exist to prevent — a step that must call a tool will fail rather than narrate. If you are seeing it, the job is still a conversation, not a workflow. Promote it.
It runs at the wrong time, or twice
Check the trigger type first. A folder trigger without debounce_secs fires
while a large file is still being written. A cron expression is evaluated in the
employee's configured timezone, so a schedule that looks right can be off by hours if
the timezone input was never set.
It asks permission for everything
Working as designed — approval is the default for every gated operation.
Open Controls and set the specific operations you genuinely want unattended to always. Do them one at a time, after watching each run clean.
The second employee never wakes up
Confirm the emitting workflow actually reached its final step — an empty output terminates the branch, and a branch that terminated never emitted. Then confirm the event name matches exactly on both sides, including case.