Skip to content
helightdevPublic

About

Sets up Ubuntu desktops for coding agents on a laptop, a server or a container, and manages them from your terminal

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

2 stars

Watchers

1 watching

Forks

berth

berth sets up Ubuntu 26.04 desktops for coding agents on a spare laptop, a server or a container, and manages them from your terminal.

A host runs XFCE on a virtual display that you open in a browser. Plugins add the agents, such as Claude Code, Codex and Pi with T3 Code as their web front end, and the toolchains they work with. Each host has a profile that berth installs and can apply again. Once the host runs, its page in berth has the status, sign-ins, updates and secrets. A machine you only log in to can be a host too: berth host add dock 192.0.2.4 --user ops.

berth's terminal UI showing the overview of a host with its actions

Status: early. Try a profile in the container or a VM before booting the installer on real hardware: the installer erases the disk it selects.

Install

On Linux or macOS:

curl -fsSL https://raw.githubusercontent.com/helightdev/berth/main/install.sh | sh

The script installs the latest release to ~/.local/bin after checking its SHA-256. On other architectures, build it:

rustup target add x86_64-unknown-linux-musl
cargo install --locked --git https://github.com/helightdev/berth berth

Setting up hosts also needs ssh, python3 and ansible-playbook on your machine. berth is also an image, ghcr.io/helightdev/berth, which runs its local API server by default.

On macOS and Windows berth uses the hosts of a berth server elsewhere, with the same screens. install.sh installs it on macOS too, and on Windows:

irm https://raw.githubusercontent.com/helightdev/berth/main/install.ps1 | iex

Coming from berth 0.5? Update the server first, then the clients and the hosts, as Upgrading from 0.5 says.

Quick start

berth studio          # a new host: choose how to install, features and settings
berth                 # the home screen with all hosts
berth run studio status

A new host opens on its Install tab, where you choose how to install it. The methods are a machine a plugin creates, a USB installer, a cloud-init seed, SSH to an existing Ubuntu server, and a container image. Features and Settings follow, and Run installs it. Once it runs, berth studio opens its overview, where you sign the agents in and find the address of its desktop.

Documentation

The documentation site is built from docs/ (cd docs && npm install && npm run dev).

  • Getting started: installing berth and a first host.
  • Deploying: the install methods, and testing in QEMU.
  • Using berth: the terminal UI and commands, sign-ins, secrets and updates.
  • Upgrading from 0.5: the order, what is converted, and going back.
  • Extending: plugins, services and berth serve.
  • Reference: tools, box, profile fields, building and releasing.
  • The API reference of berthd and berth serve, generated from docs/openapi/.

Contributing and security

CONTRIBUTING.md says what berth is meant to be and how changes get in. Open an issue before a pull request. SECURITY.md says how to report a vulnerability and where berth's API is meant to be reachable from.

License

Licensed under either of the Apache License, Version 2.0 or the MIT license, at your option. Contributions are licensed the same way.

The vendored tui-input crate under crates/vendor has its own MIT license. The agents and tools that plugins install, such as Claude Code, Codex and Unity, are separate products under their vendors' terms. berth downloads them from their vendors and doesn't include them.

About

Sets up Ubuntu desktops for coding agents on a laptop, a server or a container, and manages them from your terminal

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

2 stars

Watchers

1 watching

Forks

Releases

Packages

Used by

Contributors

Languages