Run background tasks as systemd transient units with a progress indicator
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
Arne Jørgensen a3b9a162f2
All checks were successful
CI / build (push) Successful in 3m2s
CI / release-check (push) Successful in 4m14s
CI / test (push) Successful in 4m57s
CI / lint (push) Successful in 6m41s
Release / release (push) Successful in 5m2s
Merge pull request 'Update go.mod' (#20) from arnested-patch-1 into main
Reviewed-on: #20
2026-11-10 18:53:21 +01:00
.forgejo/workflows Execute golangci-lint using go run and adjust config 2026-08-20 08:05:08 +02:00
cmd/orbit Modernize code using go fix ./... 2026-08-19 20:46:56 +02:00
internal Modernize code using go fix ./... 2026-08-19 20:46:56 +02:00
testdata Initial commit: a systemd-backed background task runner 2026-08-04 14:10:55 +02:00
.gitignore feat: release with GoReleaser to Codeberg releases and APT 2026-08-04 15:30:00 +02:00
.golangci.yml Execute golangci-lint using go run and adjust config 2026-08-20 08:05:08 +02:00
.goreleaser.yaml Also build and release i386 packages 2026-08-12 09:22:30 +02:00
CLAUDE.md ci: publish the .debs to the orbit-stable distribution 2026-08-11 08:21:12 +02:00
CODE_OF_CONDUCT.md Initial commit: a systemd-backed background task runner 2026-08-04 14:10:55 +02:00
CONTRIBUTING.md Initial commit: a systemd-backed background task runner 2026-08-04 14:10:55 +02:00
go.mod Update go.mod 2026-11-10 18:45:55 +01:00
go.sum Update dependencies using go get -u ./... 2026-10-09 15:42:14 +02:00
license.go Initial commit: a systemd-backed background task runner 2026-08-04 14:10:55 +02:00
LICENSE.md Initial commit: a systemd-backed background task runner 2026-08-04 14:10:55 +02:00
README.md ci: publish the .debs to the orbit-stable distribution 2026-08-11 08:21:12 +02:00
SECURITY.md Initial commit: a systemd-backed background task runner 2026-08-04 14:10:55 +02:00

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.