Help using Oxygenhub on Earth

Getting started

Oxygenhub on Earth hosts Oxygen repositories. You work with them through oxy, the Oxygen client; the hub shows them, reviews them and runs their pipelines. Every command below is filled in for this hub.

1. Install oxy: build it from the oxygen repository with cargo build --release and put target/release/oxy on your path.
2. Say who you are and make a signing identity (next section).
3. Register, then create a personal access token under Settings › Tokens with repo:write. It is shown once; keep it in oxy's configuration, not in scripts.
4. Create a repository with + NEW and push to it (below). An empty repository shows the same commands, with its own address.

oxy doctor checks your identity, configuration and remotes, and says what to do about any problem.

Your identity

Oxygen changes are signed. Your identity is a key pair (Ed25519 with ML-DSA-65) kept under ~/.config/oxy; the public part travels with your changes.

oxy config --user author.name "Your Name"
oxy config --user author.email [email protected]
oxy identity create
oxy config --user core.sign change

Link the key to your account under Settings › Keys: the page gives you a challenge to sign with oxy identity sign-challenge, which proves you hold the key. Linked keys show on your profile, and the hub can then tell which signed changes are yours.

Pushing

From a checkout, add the repository as a remote, give it your token, and push. This hub's certificate is self-signed, so the commands also save it and point the remote at it:

oxy remote add oxygenhub https://oxygenhub.io/OWNER/REPOSITORY
curl -fsSL https://oxygenhub.io/.well-known/oxyhub-ca.pem -o ~/.config/oxy/oxygenhub-ca.pem
oxy config remote.oxygenhub.ca ~/.config/oxy/oxygenhub-ca.pem
oxy config remote.oxygenhub.token YOUR-TOKEN
oxy push oxygenhub

An empty repository takes its identity from the first push, so every later clone shares it. oxy push oxygenhub sends the current bookmark; oxy push oxygenhub --bookmark NAME another one. Tags travel with pushes.

A Git history comes across with oxy git import --branch main path/to/git-checkout NAME: every commit becomes a change, and the result can be pushed like any other repository.

Cloning

OXY_CA=~/.config/oxy/oxygenhub-ca.pem oxy clone https://oxygenhub.io/OWNER/REPOSITORY

Public repositories clone without a token. For private ones, and to push back, set oxy config remote.origin.token YOUR-TOKEN and oxy config remote.origin.ca ~/.config/oxy/oxygenhub-ca.pem in the clone. oxy pull origin brings in what others pushed; there is no merge commit, because Oxygen changes combine by themselves.

Proposals

A proposal asks for a bookmark's changes to be added to another bookmark, like a pull request. Push your bookmark, then open one from the repository's Proposals tab, from the compare page's Propose this, or from a fork.

• A proposal is always tested and reviewed on its projected state: exactly what the target will hold once it lands. It never goes stale, and there is nothing to rebase.
• Review comments are anchored to lines' atoms, so they stay on the right line through later pushes.
• An approval can be a seal: your signature over the proposal's changes (oxy seal), which anyone can check offline.
• Land from the page, or from a client with oxy proposal land URL, which signs the landing with your own key.
• Where the site, an organisation or a repository has set up AI assistants (Settings), you can ask one to review under Reviewers, or have it draft the description; its answer is recorded as yours via the assistant, with an agent badge. Only people approve.

Wiki

A repository's wiki is Markdown pages kept as an Oxygen repository of their own: edit them under the Wiki tab (every edit is a signed change, so it needs the same delegation as editing code), or clone and push them as oxy clone https://oxygenhub.io/OWNER/NAME.wiki. Pages are Name.md on main; _Sidebar.md is the sidebar; link between pages with [Other](Other).

Letting the hub act for you

Edits in the browser and landings from the proposal page are changes too, and they must be signed. The hub signs them as your delegate, only if you allow it. Allowing it is a one-off step:

curl -fsSL https://oxygenhub.io/.well-known/oxyhub-key -o hub.identity
oxy identity delegate add hub.identity --scope changes,refs

That makes a new version of your identity: export it in the same checkout (oxy identity export) and upload that file under Settings › Keys, signing the challenge there too, so the hub sees the delegation. The hub's key file is not the one to upload. You can withdraw it at any time with oxy identity delegate remove; a repository's trust policy still decides whether a delegated change may update a bookmark.

AI identities

An AI agent (a coding assistant, a bot) can work on your repositories in its own name and in yours: its changes are signed, they say which agent made them, and you decide what it may do and for how long. Nothing it is given is a password or a key of yours.

Keyless agents (recommended)

A keyless agent holds no key at all. You give it a grant: a token your own key signs, valid for a time you choose. Whenever the agent signs, it makes a fresh key, the hub certifies it for ten minutes under your grant, and the key is thrown away; a stolen home holds nothing that signs by itself.

On your side, name the agent and how long it may act for you (the token is printed once):

oh agent grant claude --for 30d --scope changes,seal,refs

Give the agent its own oxy home (never your own), and keep the token there; it is read from standard input, so it stays out of the shell's history:

mkdir -p ~/.oxy-agents/claude/keys
oxy identity export ~/.oxy-agents/claude/keys/YOUR_KEY.identity   # in a checkout of yours, as you
export OXY_HOME=~/.oxy-agents/claude
oxy config --user author.name "YOUR NAME"
oxy config --user author.email "[email protected]"
oxy config --user author.key YOUR_KEY
oxy config --user author.signer keyless
oxy config --user keyless.hub https://oxygenhub.io
oxy config --user core.sign seal
oxy auth grant https://oxygenhub.io   # paste the token, then Ctrl-D

The author.* lines make its changes yours: without them they show as unattributed. Use the key you make the grant with: after you rotate your identity, make a new grant and set the new key here too.

The agent then commits and pushes with OXY_HOME set to its home. Its changes are authored as you and sealed via agent:claude@OWNER, which history, proposals and your profile show. oh agent list shows your grants; oh agent revoke ID ends one at once, and a grant ends by itself when its time is up.

Where it may push

A repository with a trust policy accepts an agent's work only if the policy names it. Grant the agent's subject, with this hub as the issuer, from a checkout of the repository:

curl -fsSL https://oxygenhub.io/.well-known/oxyhub-key -o hub.identity
oxy policy grant-subject agent:claude@OWNER --issuer hub.identity --scope changes,refs

A repository without a policy takes any signed change its token may push.

Agents with a key of their own

An agent that keeps its own identity acts for you through a delegation: from your checkout, oxy identity delegate add agent.identity --scope changes --expires 7d, then link your identity again under Settings › Keys. oxy identity delegate remove KEY withdraws it. Keyless grants are simpler and leave nothing behind.

Tokens, notifications and gates

• A personal access token an agent uses can be marked agent under Settings › Tokens: proposals it opens and comments it makes reach your inbox and email like anyone else's.
• An approval gate is for a person: an agent's token cannot approve or reject one unless a repository's maintainers allow it under Settings › Gates & agents, and each decision still says which agent made it.
• Commits whose message says a skip marker ([skip flow]) start no pipeline run; agents should leave them out unless asked.

Pipelines

Pipelines run in OxygenFlow. Put a pipeline in .flow/pipeline.kdl and push: each job runs in its own microVM with no network, and its result shows on the repository's Flow tab and as a check named flow/JOB on proposals. A site administrator enables Flow for a repository.

Instead of a badge, a README can carry a state stamp:

[![flow](.flow/stamp)](.flow/run)

It shows the result for the state you are looking at (a tag shows the tag's result), names that state, and carries each job's receipt hash.

Keyboard

Backups

Under Settings › Backups (or an organisation's settings) you choose where your repositories are copied and how often. Each run copies every repository you own, its wiki, issues, proposals, releases and settings, but never a secret value. Only what changed travels, and every kept run can be restored with oxygenhub admin backup restore.

A Google Cloud Storage bucket needs no key: the hub signs in as backup:YOU with a token it issues itself, which Google trusts through workload identity federation. Once per project, create a pool and an OIDC provider whose issuer is this hub's address; once per bucket, grant roles/storage.objectAdmin to the principal …/subject/backup:YOU. The exact commands are in the hub's docs/backups.md §6.

Coming from GitHub