Connecting your own device

Orbi runs in the cloud; most of your files live on your own device. Orbi Node is the small application that connects the two. Once it is installed, an agent on the board can work in the folders you allow, your device can tell Orbi when something happens, and your coding agent can run on your own device.

Here are the boundaries in five sentences. Everything else on this page is detail.

• Your device can tell Orbi about things: a file changed, a threshold was crossed, a certain time arrived.
• Agents in Orbi can read and write files on your device only in the folders you allow, and can only do the things you have defined.
• If you have a coding agent on your device, cards run there.
• Your device never decides anything on its own. What happens is always decided by the agents and flows in Orbi.
• If your device is off, nothing happens and the work waits.

#Installing

The download page is orbiwork.space/download. On macOS and Linux installing is a single line; on Windows you run the file you downloaded. You are never asked for an administrator password — the application lands in your own user folder.

If you are installing on a server with no screen, you do not need the window: run the same install line with the --cli option and only the command-line version is installed. The full recipe for a server is in Installing on a server below.

The first time it opens, the application shows a code. Approving that code in Orbi ties the device to your account. You then choose which workspaces can see this device; each choice is a separate connection and it starts empty. For a workspace to see anything on this device, you have to add a folder as well.

The desktop application updates itself; you do not have to do anything when a new version ships. The command-line version you install on a server does not update itself — it only tells you a new version is out. Updating explains how.

You do not need to memorise commands in the command-line version either. Typing just orbi-node in the terminal opens a full-screen application you navigate with the arrow keys; folders, capabilities and settings are all managed from the same place. If orbi-node is already running in the background on a server (under systemd, say), this application opens in attached mode without opening a second connection: the screens and the changes you make there still work, only the live feed is read from the service's own log.

#Installing on a server

A server differs from the device on your desk in two ways: it has no screen, and it is expected to stay up while you are not at it. That is why we install the application as a service on a server. A service is a program that starts on its own when the server boots and does not close when you close your connection.

The steps below are for Linux and are written to be followed in order. You do not need to know Linux; you can paste the commands as they are. Connect to the server with ssh and begin.

#1. Install the application

curl -fsSL https://get.orbiwork.space/install | sh -s -- --cli

This line installs only the command-line version and never asks for an administrator password. When it finishes it prints where the application landed. If orbi-node then says "command not found", run the export PATH=... line from that message and try again.

#2. Tie the server to your account

orbi-node login --url https://api.orbiwork.space
orbi-node link
orbi-node dirs add /srv/project --write

The first line shows a code on screen; you approve that code in Orbi from the browser on your own device. The second opens the server to a workspace. The third announces the first folder — put your own path in place of /srv/project, and leave out --write if the folder should only be read.

Which user you run these three commands as matters. The service in the next step has to run as the same user, otherwise it stops at startup saying there is no linked workspace.

#3. Try the connection

orbi-node start
orbi-node status

The first command puts the application in the background and hands your prompt straight back. If the second one prints running yes, your server is connected to Orbi and shows as online on the Devices screen.

It stays connected after you close your session. To stop it, run orbi-node stop.

If something is wrong, the application's own record says what:

orbi-node log --out

#4. Keep it connected across restarts

Step 3 survives your session closing, but not the server restarting. For the server to connect on its own every time it boots, define a service.

First stop the one you started by hand — otherwise the service tries to open a second copy and cannot start:

orbi-node stop

Then copy the whole block below as it is. It works out where the application is installed and which user you are; there is nothing for you to fill in:

sudo tee /etc/systemd/system/orbi-node.service >/dev/null <<EOF
[Unit]
Description=Orbi Node
After=network-online.target
Wants=network-online.target

[Service]
User=$(id -un)
ExecStart=$(command -v orbi-node) start --foreground
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
EOF
sudo systemctl daemon-reload
sudo systemctl enable --now orbi-node

The --foreground in the definition tells the application not to put itself in the background: a service manager cannot supervise a process it cannot see.

Run these as the same user you ran step 2 as. The application's settings live in that user's folder; a service started as anybody else stops with "no workspace is linked".

After this the server connects to Orbi on its own every time it starts. If the connection drops for any reason it is rebuilt within ten seconds.

#5. Verify the installation

systemctl status orbi-node

If the output says active (running), the installation is done. If something is wrong, this shows why:

journalctl -u orbi-node -n 50

status=203 or status=127 means the service could not find the application. That happens when the service definition carries only the application's name instead of its full path; the block above works the path out itself, so copying it as it is prevents this.

#Managing the server afterwards

If you connect to the server with ssh and type orbi-node, the same full-screen interface opens: you see the folders, approve abilities and watch what is happening. This interface does not replace the service, it is only a window onto it; closing it with q does not stop the service.

To stop, start, or remove the service entirely:

sudo systemctl stop orbi-node
sudo systemctl start orbi-node
sudo systemctl disable --now orbi-node

#If you clone the server

Orbi recognises a device by its hardware identity, not by its name. That is why you can reinstall your device and rename it and still keep the same record in Orbi, with your folders, permissions and settings where you left them.

When you clone a virtual server, the copy carries the original's hardware identity too. The same happens when you make a second Orbi Node install on one device. Orbi may take the two for one device, and one of them takes over the other's connection. So when you approve the code in the browser, Orbi asks if the same device is already registered on your account under another name: "Same device, reinstalled" updates the record to the new name (folders and permissions stay, the old install can no longer connect); "Add as a separate device" creates a new record and the old install keeps working as it is. An install that comes with the same name counts as a reinstall, with no question.

On a server, without going to the browser, you can make the same choice on the command line:

orbi-node login --url https://api.orbiwork.space --separate

Run this on the copy only. There is no need to run it on the original.

#Common mistakes

Almost every server that shows as offline in Orbi has run into one of these two.

• Starting the application by hand. Connecting to the server and running orbi-node is not enough. The application closes when your session ends and the device goes offline with it.
• Leaving it open inside screen or tmux. This keeps the application up after your session ends, but it does not come back when the server reboots.

On any server that has to stay connected, follow step 3.

#macOS and Windows servers

macOS has no systemctl; launchd does the same job and needs a definition file that calls orbi-node start --foreground. Service definitions always use --foreground: a service manager cannot supervise a process it cannot see. On Windows you install from PowerShell:

irm https://get.orbiwork.space/cli.ps1 | iex

If you would like us to prepare the service definition for either of these, write to platform@orbiwork.space.

#Updating

The desktop application downloads and installs a new version by itself. The version you install on a server with --cli does not: when a new version ships it only writes a line to its log and you start the update. The install line is the same one, run it again:

curl -fsSL https://get.orbiwork.space/install | sh -s -- --cli

Then restart the device's connection once. The install only replaces the file on disk; the application that was already running keeps running its old version, so the update does nothing until it is restarted:

sudo systemctl restart orbi-node

If you started it by hand instead of as a service, orbi-node stop followed by orbi-node start does the same job.

#Why the version still looks old

On the Devices screen, the version next to a device's name is the version currently running on it — not the one installed on disk. If you installed the update but did not restart the device's connection, the old version keeps running and the screen keeps showing it. When a newer version is published Orbi says so on the same line; the warning disappears on its own once you restart.

#The device's name

The name you type during setup is both the name you see in the list and the address agents use to reach that device: @device.username.device-name. You can change it later. There are two places to do it: the Settings screen of the application on the device, or the Devices screen in Orbi, as the owner of the device. Spaces and punctuation become -, and the name is unique within your account.

Because the name is an address, changing it affects text that was written earlier. Before you save, Orbi tells you how many flows and how many cards mention the old address. It does not change that text for you: a card or comment holding the old address stays as it is and no longer matches a device. A flow's permission to use this device also comes from the address in its text, so a flow you leave unchanged loses that permission the next time it is saved. After a rename it is worth opening those flows and correcting the address.

#Folders

Orbi does not see your whole device. It sees only the folders you add, and for each folder you decide whether it may only read or may also write. Folders are added and removed in the application on the device; the Devices screen in Orbi only shows them.

A folder's real path is never written to Orbi. On the board you see the folder under the name you gave it.

#What it can do

An agent cannot run free-form commands on your device. It can only do the predefined things we call capabilities. There are two kinds.

For an agent to use your device, it is enough to mention it: write @device. on a card, in a comment, in a flow or in chat and pick the device. The agent then sees that device's shared folders, capabilities and watchers in one go. Devices you did not mention are not piled in front of the agent; if it needs one, it lists them and opens one itself.

The ones that come with it are the same on every device: read a file, list a folder, take the last lines of a file, bring a file to Orbi, put a file from Orbi onto the device, look at system status. All of them stay inside the folders you allowed.

Your own capabilities are the jobs you define — "clean up old logs", say, or "write the report into Excel". When you tell Orbi what you want, a draft is prepared for you, but the draft is never written to your device without your approval: you see its full text, you can correct it, try it, and then approve it.

Ready-made packs are groups of capabilities we wrote, and you never have to read any text to use them. The first pack is office files: it creates and reads Word and Excel files in the folders you allowed. You switch a pack on and off in the Orbi Node app on the device, with the switch on the Abilities screen. On a server without a screen the same job is done with orbi-node verbs enable office and orbi-node verbs disable office. The switch lives only on the device, because the person at the device has the last word on what it can do. The Devices page in Orbi shows the capabilities of a pack that is on with a "ready-made pack" label, and when you flip the switch the list updates without reloading the page. The capabilities of a pack that is off are not listed and agents cannot call them.

Every capability has a working folder and its output lands there. Some capabilities are defined so that the caller picks the folder; the agent then chooses among the folders you shared.

A capability is defined the way an agent understands it. Each one has a name, a description that says what it does and when to use it, the inputs it takes, the shape of what it returns and one example call; Orbi fills all of these in when it drafts one, and a draft missing any of them is not created. The agent sees the capability the same way it sees the built-in tools and maps a request like "clean up old logs" to the right one. If a card is tied to a device (unfinished work is there, or it is the preferred device) the agent sees only that device's capabilities; otherwise those of every device in the workspace.

Improving one later. On the Devices screen, open the capability and press Edit. You change the description, inputs, output shape and example by hand; for the command itself you either tell Orbi what else it should do and have it rewritten, or edit the text yourself. Every change you save goes to the device as a new draft: the old version keeps running, the new one takes over once you approve it on the device, and the pending update shows on the Devices screen. Creating and editing capabilities on Windows devices is not supported yet; the screen says so.

#Letting it tell you things

If you want your device to notify Orbi on its own, you set up a watcher. Five things can be watched:

• the processor, memory or disk staying above a threshold you set (one watcher can cover all three; you hear about whichever crosses first),
• a new line landing in a file (an error log, for example),
• a file arriving in, changing in, or disappearing from a folder,
• a time you choose,
• an address failing to respond.

You can describe what should be watched in a sentence; you are shown the filled-in form and a readable summary of "you will be told when this happens". Once you approve it, the watcher goes down to your device.

A resource alert carries the device's whole picture at that moment: CPU, memory, disk and how long the device has been up. Whatever you are watching, one alert tells you what was happening on the device — there are no separate alerts to piece together.

When you watch a log file, we ask whether its name changes from day to day. If it stays the same, pick the single file. If it changes — app-2026-09-09.log, say — pick "files whose name changes" and write app-*.log; the star stands for the part that changes. Every matching file is followed, yesterday's goes quiet on its own once nothing writes to it, and a new one is read from its first line. Without this the watcher follows only the name you typed, and goes quiet without a word on the day that name changes. The star cannot cover everything: password files and keys (.env, .pem, id_rsa and the like) cannot be watched, neither as a single file nor through a star, and such a pattern is turned down before it is saved. An agent can change a watcher's threshold and interval, but what is watched (file, folder, address) is only ever changed by you.

A watcher is a coarse net: keeping the threshold low is right, because the filtering is the agent's job. Watchers are independent of each other; if one gets stuck the others keep going. What a watcher reports can start a flow.

One arrangement comes up often: when a file lands in a folder, the agent reads it, summarises it and saves the summary to Orbi. A single button next to the folder watcher sets that flow up for you.

Every watcher has a daily event limit, 500 by default. A watcher that reaches it goes quiet for the day: it produces no events, starts no flow and uses no resources on your device. On the Devices screen it shows "reached today's limit, continues tomorrow" and carries on by itself the next day (in your workspace's time zone). You can change the limit in the watcher's settings. This brake keeps one misconfigured watcher from burning all your credit in a morning; in normal use you never see it. When the limit is reached, the device's owner gets a notification (once a day per watcher; the "My connected devices" category, which can be switched off in notification preferences).

In a log-file watcher, matching lines are gathered for a while and sent as one event; for a new watcher that is 30 seconds. If you leave the pattern empty every new line becomes an event; the form says so before saving, because a busy log fills the limit within hours.

If a watcher reports while the flow's previous run is still going, the report is not lost: it goes into the flow's waiting bucket and one run is started for everything in it when the run ends. See Flows › Overlap behaviour.

#The coding agent

If you have a coding tool such as Claude Code on your device, cards can run there. For that, the repository address is written in the coding agent's definition — assigning a card to that agent is how you choose which repository is worked on. You do not pick a repository on the card as well.

The card goes to a device that shares that repository and is open to you. You can see which devices could take the card on the card itself, and it tells you when none of them is online.

Which tool is used, which model is chosen and which working copy the job runs in is decided on the device. The same agent can work with one tool on one of your devices and a different tool on another. The model is picked from a list in the application on the device; the choice goes to the run as it is, and if you wrote the command yourself the application tells you whether the model was applied. How many cards a device runs at the same time is set on the Devices screen; the setting reaches the device while it is connected.

Claude Code, Gemini CLI, Qwen Code and Codex connect to Orbi on their own for every run; the model and permission mode picked on the card are applied to them too. With these tools the agent reports its result and can ask on the card. Other tools run cards as well but cannot report a result yet; with them the card closes by the older rule.

The "Now" section of the Devices screen shows a running card the way the board does: number, project, agent, title, the tool and branch in use, and at the bottom which step the run is at (work taken, code branch prepared, working, sending the result). The application on the device draws the same card the same way.

When the agent takes a card it gets the description, the checklist, the latest comments and the attachments together. A screenshot you attached to the card is seen too: when the agent reads the card, the image comes alongside the text, and if an image cannot be read (too large, or a type the model cannot look at) it says so. Comments you write while the card is running are not lost either: every time the agent touches Orbi it sees the new comments written up to that moment and reads them first. A comment reaches the agent on its next touch; a very short run that finishes without touching Orbi at all can miss it.

The agent's own definition and the team's memory travel with the card: the definition you wrote on the agent page, the pinned rules, the topic headings of memory and the notes of the card's project come before the card text. The agent does not have to ask who it is or what the team's rules are. If it learned something lasting while working, it reports that together with its result; the lesson enters memory linked to the files the run changed, and if those files change later the note becomes a "stale" candidate. A very long definition or a very full memory that does not fit into the package is cut, and the agent is told where.

The agent reports how the run ends itself; the device does not guess from the tool's last sentence. When the work is done the agent reports it with a summary, and that summary becomes the card's closing comment. If it needs a decision from you, it asks on the card with options. If it cannot go on without you, it stops and writes what it needs. The card closes accordingly:

The card's expected output is picked in the run settings. With Code changes the agent commits, pushes the branch and opens a pull request. With Answer only it commits nothing and writes its answer in the closing comment; pick it to have a question answered or a review done. For a run that ends without reporting anything the device does not open a second turn; queue the card again to retry.

If the device loses its connection to Orbi, the application reconnects on its own; you do not need to close and reopen it. A device you paused from the Devices screen stays paused even if its connection drops and comes back, and it only starts taking cards again when you resume it.

You can also pause the device on the machine itself (orbi-node pause). That pause belongs to the machine. The Devices screen shows it as "paused on its machine", and the badge of a card waiting for that device says so too. The Resume button in Orbi does not lift it; it only lifts a pause set in Orbi. You lift the machine's pause by running orbi-node resume on that machine.

When a card comes back from the device you read the reason both in the card's comment and in its history; the device is named by its @device. address, which keeps resolving even if it is renamed later. If the same card bounces back three times in a day without ever reaching the device, it stops bouncing: it fails and you are told.

#The code card drawer

A card assigned to a coding agent, or one that has once gone to a device, opens as a code card in a drawer of its own. Whatever the card's state (to do, queued, running, in review) this view stays; when a run is stopped or the agent exits without producing work, nothing disappears.

• Status line. One sentence under the title says where the card is: which device it has been running on and for how long, what it is waiting for in the queue, why it came back ("Stopped from the card", "The agent's question went unanswered", "The agent ended without reporting a result", "The tool exited with an error", "The device shut down") or when it finished. The dot in front is violet while running, amber when the card came back and green when it finished. What you can do sits at the right of the same line: "Stop" while running, "Queue again" after a return. The status is a single line; a long detail sentence is shortened, and hovering shows all of it. "Stop after this turn", "Release", state changes and deleting are in the ⋯ menu in the column's strip.
• Meta tags. Right under the status you read the branch, the coding tool with the model and the pull request in small tags. The line never wraps; a long branch name is shortened inside its tag, and hovering shows it in full with the repository. Clicking the pull request opens it at the provider.
• Session tab. Comments, the messages you wrote to the agent and the tool's steps sit on one line, in time order; who said what and when reads at a glance. Tool steps come in compact blocks: the last three steps are shown, and clicking the block's header opens all of them. The running block flows live and stays readable after the run.
• Details tab. Assignee, priority, due date and tags; parent card and subtasks; description, pull requests, attachments and checklist.
• The agent's question. If the agent needs a decision, it asks on the card with options; on the board the card says "Waiting for your answer", and in the drawer the question sits above the message box. You answer by picking an option or typing your own answer; the agent carries on in the same session. If no answer arrives within half an hour the card comes back to you with the question. You still answer from the same box: Answer and queue writes your answer on the card and queues the card again, and the new run starts by reading it.
• One message box. While a run is on, the box at the bottom of the drawer can write to two places. With Agent selected the agent reads the message at the end of its turn and continues in the same session; with Comment selected it is written to the team. A note next to the message says "reached the device · the tool reads it on its next turn", because the tool cannot take input mid-turn. Without a run, the box writes a comment.
• Run settings. Without a run, one tag sits in the message box's bottom bar and lists the chosen settings in order: device, model, effort and expected output. Clicking the tag opens the preferred device, model, effort, permission mode and expected output fields, with their names, inside the box; if the agent has several repositories, the repository is there too. A choice is saved at once. On a card in review or in error, the arrow next to the send button opens Comment and run again. The lists come from the connected devices, and a field that says "default" uses the folder's default on the device.

#Where the card runs

Which device runs a card? Usually you do not think about it: the device of the person who queued the card goes first, and if it is off, the first free device sharing the repository takes it. In two cases a card gets a place of its own:

• Unfinished work. When a run ends without pushing its work to the branch (the agent stopped before committing, a command was refused, the device shut down), what was done stays on that device and the card is tied to it: the board shows an "unfinished work" badge, and the drawer's status line says how many files and commits are waiting. If you queue the card again, only that device takes it and continues where it stopped; no other device sets up the branch from scratch and writes the work a second time. If the device is off, a queued card waits an hour and then comes back to you with two ways out: turn the device on and queue the card again, or release the card. Releasing makes the device save the unfinished work, push it to the card's branch and clean its copy; any device can continue the card afterwards. If the device is off, the request waits and is carried out when it comes back; the card says so. The tie clears by itself once the work reaches the branch.
• Preferred device. You pick it under the message box before the run starts; only devices that can take the card are listed. While the device you picked is on, only it takes the card; if it is off, the card does not wait and the next suitable device takes it. The choice stays on the card: however many times you queue it, it goes to the same device.

#What to set up once on the device

Nobody is watching while a card runs, so anything that stops to ask a person is the same as the work stopping. Three things have to be ready beforehand:

• The coding tool must be able to run commands. A card's work does not end at writing code: it has to save the change, run the project's own checks and open a merge request. The commands that come ready are already set up to do that; if you write your own, keep that part. The same setting answers the "do you trust this folder" question every coding tool asks the first time it sees a directory.
• Git must know whose name the change is saved under. Changes are recorded with the name and email in your device's git settings; with both empty, nothing can be saved at all.
• Sending must not ask for a password. When the work is done, the card sends the repository upstream. That needs either a key without a passphrase or an access key stored once.

If a card comes back to you saying nothing was saved, the reason is almost always one of these. The work is not lost: the working copy on the device is left exactly as it was and the card says where it is. Fix what was missing, queue the card on the same device again, and the work carries on from where it stopped.

#Who can ask for what

The device is registered to your account. For someone else to have work done on your device, you have to add them to the access list; while the list is empty, only you can. If someone who is not on the list mentions your device on a card, the work is not done and the reason is written on the card.

Only you open that access. A workspace admin can pause your device's connection, transfer it or close it for good, but cannot let anyone have work done on your device. Closing is the team's safety; opening is the owner's call.

If a card is pointed at a device that is not open to you, the board says so instead of letting it wait. If you queued the card, it reads "you have no access to the device" and names who can grant it. When someone else opens the same card, they see the name of the person who lacks access, so the device's owner knows who to add to the list. Everyone used to see the same sentence, which made a person who did have access doubt their own; before that, the card said nothing and waited for hours.

If a flow is going to do something on your device, that is a separate permission and you approve it once. If the flow is changed later the permission lapses and you are asked again. That way nobody can set up an automation running on your device without your approval.

When someone leaves the workspace, their device connection closes too.

#Security

The decision is on your device. Orbi can ask for something; whether to accept is the application's call.

• No request that reaches outside a folder you allowed is accepted. Shortcuts and links are resolved and checked as well.
• Some files are never read by default: password files, keys, repository settings.
• The record of what was done on your device is kept on your device. You can read it one entry at a time from the "Now" screen in the application.
• You can stop it whenever you want, both from the Devices screen in Orbi and from inside the application.
• When your device shuts down, the card it was holding is not lost; it goes back to the queue.
• If the connection stops answering (a sleeping laptop, a dropped network) Orbi notices within a minute and shows the device as offline; requests headed for it do not wait, they get an "offline" answer right away. If the device crashes, the card's temporary access key is revoked at the same moment.

#Plans

Connecting a device is available on paid plans. Your plan decides how many devices you can connect and how many watchers you can set up on each; the details are on Plans and security.

The AI cost of the coding agent belongs to the tool on your device and is not taken from your Orbi credit. The cost of the Orbi agent that asks something of your device is taken from your credit as usual.

If something is not working the way you expect, see Troubleshooting.