- Go 100%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
|
|
||
| .forgejo/workflows | ||
| cmd/orbit | ||
| internal | ||
| testdata | ||
| .gitignore | ||
| .golangci.yml | ||
| .goreleaser.yaml | ||
| CLAUDE.md | ||
| CODE_OF_CONDUCT.md | ||
| CONTRIBUTING.md | ||
| go.mod | ||
| go.sum | ||
| license.go | ||
| LICENSE.md | ||
| README.md | ||
| SECURITY.md | ||
orbit
Run long jobs in the background, and actually see how far along they are.
$ orbit start -- ./build.sh
adce11
$ orbit list
ID COMMAND STATE PROGRESS
718544 bash -c exit 2 failed(2) failed (exit 2)
adce11 ./build.sh running [▇▇▇▇▁▁▁▁▁▁] 40% (running)
cd7ba6 ./deploy.sh staging running starting
What it is for
You start a build, a deploy, a long test run. You want to close the terminal, check back later, and know whether it finished — and if it is still going, how far it has got.
Orbit hands the job to systemd and gets out of the way. Each job becomes a transient user service, so it keeps running after your terminal closes, its output goes to the journal, and killing it cleans up every process it spawned.
There is no daemon and no state file. systemd's user service manager holds
everything orbit knows: the command line, the live progress, the exit status.
orbit is a thin front end over that, which means nothing is left running
between invocations and nothing can get out of sync with reality. Every job is
also a normal systemd unit, so systemctl --user status orbit-<id> and
journalctl --user -u orbit-<id> work on it directly.
The part systemd cannot do by itself is progress. Orbit runs your command on a
pseudo-terminal, watches the output for OSC 9;4 progress escape sequences —
the ones modern build tools already emit to draw a progress bar in your taskbar
— strips them out of the log, and republishes them as the unit's status text.
That is why a percentage shows up in orbit list, and in systemctl too:
$ systemctl --user status orbit-adce11
● orbit-adce11.service - orbit: ./build.sh
Loaded: loaded (/run/user/1000/systemd/transient/orbit-adce11.service; transient)
Transient: yes
Active: active (running) since Tue 2026-08-04 13:53:16 CEST; 5s ago
Main PID: 3501833 (orbit)
Status: "40% (running)"
Requirements
Linux with systemd and a user session. Orbit is systemd-only by design — there is no fallback for other init systems or platforms. Developed against systemd 255.
Install
Debian and Ubuntu
Orbit is published to an APT repository on Codeberg. Add it once:
$ sudo curl -fsSL -o /etc/apt/keyrings/arnested.asc \
https://codeberg.org/api/packages/arnested/debian/repository.key
$ echo "deb [signed-by=/etc/apt/keyrings/arnested.asc] https://codeberg.org/api/packages/arnested/debian orbit-stable main" \
| sudo tee /etc/apt/sources.list.d/orbit.list
$ sudo apt update && sudo apt install orbit
Upgrades then arrive through apt upgrade like anything else. The package
installs shell completions for bash, zsh and fish alongside the binary.
Binary
Download a linux_amd64 or linux_arm64 tarball from the
releases page, verify it
against checksums.txt, and put orbit somewhere on your PATH.
From source
$ go install arnested.dk/go/orbit/cmd/orbit@latest
Or from a checkout:
$ go build -o orbit ./cmd/orbit
Using it
Start a job
Everything after -- is your command, run as you typed it:
$ orbit start -- make -j8 build
adce11
It prints a short job ID. The job inherits your current working directory and
environment, so it behaves the way it would in your shell. Add variables it
should not inherit from you with --env:
$ orbit start --env CI=1 --env DEPLOY_ENV=staging -- ./deploy.sh
cd7ba6
See what is running
$ orbit list
ID COMMAND STATE PROGRESS
27aa55 npm test failed(254) failed (exit 254)
2a6ccd ./build.sh exited(0) done
ebd772 ./deploy.sh staging stopped(SIGTERM) terminated (SIGTERM)
ls and ps are aliases. The STATE column reports how a job ended:
| State | Meaning |
|---|---|
starting |
queued, not yet reported ready |
running |
in progress |
exited(0) |
finished, with its exit code |
failed(254) |
exited non-zero |
stopped(SIGTERM) |
you asked it to stop, and it did |
killed(SIGKILL) |
killed outright, with no chance to shut down |
Finished jobs stay listed. That is deliberate — a job you cannot see the
result of is not much use. They stay until you clear them with orbit rm.
Report jobs when you log in
orbit status is list rearranged for a login banner: a summary line, then a
line per job.
$ orbit status
orbit: 1 running, 1 failed, 1 finished
8a0dcc running sleep 300
4a5a11 failed(3) bash -c exit 3
c4bad8 exited(0) ./build.sh
It prints nothing at all when there are no jobs, and exits 0 even when it cannot reach the service manager, so it is safe to run unconditionally from a shell profile:
# ~/.profile — say something only if there is something to say
command -v orbit >/dev/null && orbit status
Two things follow from that. It reports every job orbit list would, and a
finished job stays listed until orbit rm clears it — so a success you have
already seen keeps being reported until you clear it. And because it stays
quiet about its own failures, orbit list is the command to reach for when
you suspect orbit itself is unhappy.
Watch the output
$ orbit attach adce11
This tails the job's log and follows it live. Ctrl-C detaches; the job keeps
running. -n 50 shows fewer past lines, -n all shows everything,
--follow=false prints and exits. logs is an alias.
Stop a job
$ orbit stop ebd772
ebd772 stopped by SIGTERM
The job is sent SIGTERM and given a few seconds to shut down cleanly; if it
ignores that, it is killed. orbit stop --all stops everything running. For a
job that is truly wedged, --kill sends SIGKILL immediately.
Stopping leaves the job listed so you can see how it ended.
Clear finished jobs
$ orbit rm 2a6ccd # one job
$ orbit rm --all # every finished job
$ orbit rm --all --force # ...and terminate the running ones too
remove, prune and clear are aliases. Removing a running job is refused
unless you pass --force, since that would terminate it.
Logs are not removed — journald keeps them under its own retention rules, so
journalctl --user -u orbit-<id> still works afterwards.
Shell completion
Completion suggests job IDs, filtered to what each command can act on: stop
offers only running jobs, rm only finished ones (or all, with --force), and
attach any job. Each suggestion shows the job's state and command.
$ orbit completion bash > /etc/bash_completion.d/orbit
$ orbit completion zsh > "${fpath[1]}/_orbit"
$ orbit completion fish > ~/.config/fish/completions/orbit.fish
Reporting progress from your own scripts
Anything that already emits OSC 9;4 works with no changes — that includes a
growing number of build tools and CI runners. To report progress from your own
script, print the sequence:
ESC ] 9 ; 4 ; <state> ; <percentage> BEL
| State | Meaning |
|---|---|
0 |
clear the progress indicator |
1 |
normal progress, percentage 0–100 |
2 |
error |
3 |
indeterminate — working, no estimate |
4 |
warning |
In bash:
for i in $(seq 0 10 100); do
printf '\033]9;4;1;%d\a' "$i"
echo "step $i: compiling widget-$i.o"
sleep 1
done
printf '\033]9;4;0;0\a' # done
Orbit strips all OSC sequences from the log, not just progress ones, so window titles and hyperlinks do not end up as noise in the journal. Colour and other CSI sequences are left alone.
Notes
Logging out. Jobs outlive the terminal that started them, but a user service manager is normally torn down when your last session ends. If you want jobs to survive a full logout, enable lingering:
$ loginctl enable-linger "$USER"
Where jobs live. Each job is a transient unit named orbit-<id>.service,
grouped under the orbit.slice cgroup. Nothing is written to disk.
Environment. Jobs inherit your full environment, which is convenient but
means variables are visible in systemctl --user show orbit-<id>. Keep that in
mind if your shell exports secrets.
Contributing
Patches welcome. Contributions are made under the Developer Certificate of Origin — see CONTRIBUTING.md. To report a security issue, see SECURITY.md.
Building and checking a change:
$ go build ./...
$ go test ./...
$ golangci-lint run
CI runs the same three checks on every push and pull request; see .forgejo/workflows/ci.yml.
License
MIT — see LICENSE.md, or run orbit license.