Skip to Content
Referenceoo CLI

oo apps

Hosted apps such as Forgejo: add and run them.

A hosted app is an app such as Forgejo on a VM of its own, at an address under this Sunport's domain, with its own sign-in. An administrator adds one from the catalog and creates its VM, on the app's page or with oo apps vm, and the Sunport then publishes its address and installs it by itself. The address shows only once it answers there.

An agent's own account in an app is made with the app's own admin CLI on its VM (oo vm exec). In an app that keeps its own accounts, such as Mattermost, the Sunport makes each person who may sign in an account there (oo apps account), and gives it a new password, shown once (oo apps password).

oo apps agent-credentials

Read or enable agent credential enrollment

oo apps agent-credentials [options]
ArgumentRequiredDefaultChoicesDescription
--set SETnoon, offadministrator's own full identity only; default off

It also takes the connection options.

oo apps credential

An agent with an explicit services.use grant on this app saves its own account credential to a protected file. Never a person's account or another agent's. Requires the default-off hosted-app agent credential feature. Use --wait SECONDS to follow enrollment through this same endpoint, not oo jobs. Without it, state creating means repeat with --overwrite. Tokens never print. A 409 hosted_app_agent_busy means retry. For hosted_app_agent_username_taken, ask an administrator to resolve the Forgejo username conflict and remove then restore the app grant before retrying.

oo apps credential [options] APP_ID
ArgumentRequiredDefaultChoicesDescription
APP_IDyesthe app's ID, from oo apps list
--output FILEyeswrite the answer to this mode-0600 file
--overwritenoreplace an existing --output file
--wait SECONDSnowait for enrollment, saving only a ready credential

It also takes the connection options.

oo apps catalog

Print the apps this Sunport's release can add, as JSON: each with its id, name and what it is, its version and license, the smallest VM it runs on (size), how people sign in (signIn) and where it can run (providers), without its icon. canAdd says whether you may add one.

oo apps catalog

It also takes the connection options.

oo apps list

Print the apps added here that you may see, as JSON: each with its ID, app and label, its status (planning, awaiting_approval, creating, awaiting_install, installing, going_live, live, stopping, stopped, starting, failed or removing) and setup steps, its address (url) once it is live and never before, its version (installed, available, update), who may sign in (everyone) and its backups. Only those who manage an app see its plan, price and job IDs. canAdd says whether you may add one.

oo apps list

It also takes the connection options.

oo apps show

Print one app as JSON: the app as oo apps list has it, and your access to it (view, use, manage).

oo apps show APP_ID
ArgumentRequiredDefaultChoicesDescription
APP_IDyesthe app's ID, from oo apps list

It also takes the connection options.

oo apps add

Add an app from oo apps catalog and plan its VM. Create the VM with oo apps vm, or with Create VM on the app's page in the dashboard, whose link this prints. Once the VM is made, the Sunport publishes the app's address and installs it by itself, and oo apps show reads creating, installing, going_live and then live, with its address.

The VM is on OpenOrange capacity, without a public IP; --node puts it on one node. --hetzner puts it on Hetzner Cloud instead. The Sunport picks the smallest size the app fits there, unless --size, and answers hosted_app_size_unavailable when none does. Its address is the app's own first label under the Sunport's domain, such as git, or that with -2 and on while it is taken, unless --name. Unless --chosen-only, everyone in the Sunport may sign in.

oo apps add [options] APP
ArgumentRequiredDefaultChoicesDescription
APPyesthe app, such as forgejo, from oo apps catalog
--name LABELnothe address's first label, such as code
--size SIZEnothe VM's size, such as standard-4-8-60; by default the smallest the app fits
--hetzner REGIONnoon Hetzner Cloud in this region, such as fsn1
--node NODEnoon this OpenOrange capacity node, instead of any with room
--chosen-onlynoonly administrators and the people given access sign in, not everyone in the Sunport

It also takes the connection options.

oo apps plan

Plan the app's VM again, when its plan expired before anyone created the VM, or the plan or the VM's creation failed. It prints the link to the app's page; create the VM there, or with oo apps vm.

oo apps plan APP_ID
ArgumentRequiredDefaultChoicesDescription
APP_IDyesthe app's ID, from oo apps list

It also takes the connection options.

oo apps vm

Create the app's planned VM, as Create VM on its page does: whoever manages the app (services.write on it) and holds the compute permissions (hosts.manage and jobs.create) may, a person's key or an agent's. Clem does it as the administrator who asked it in chat, when one did. The app then installs by itself as the person who created the VM; a VM an agent's key created gets no root for that agent, and the app reads awaiting_install until someone who may installs it: an administrator on its page, whose link this prints, or an agent with a person's root grant on the VM (oo apps install).

oo apps vm APP_ID
ArgumentRequiredDefaultChoicesDescription
APP_IDyesthe app's ID, from oo apps list

It also takes the connection options.

oo apps install

Install the app on its VM, as its page does: an app that reads awaiting_install, or again to repair it or bring it to the version this release carries. The app keeps its data, its secrets and its accounts. The install runs as root on the app's VM, so an agent needs a person's root grant there (oo vm request).

oo apps install APP_ID
ArgumentRequiredDefaultChoicesDescription
APP_IDyesthe app's ID, from oo apps list

It also takes the connection options.

oo apps update

Update the app to the version this release carries, when the app runs an older one (version.update in oo apps show). It is the same call as install, and keeps the app's data and accounts; an app with a backup hook takes a consistent copy of its data first. It prints update: the version it moves from and to, or null when the app runs that version already, and the install repairs it.

oo apps update APP_ID
ArgumentRequiredDefaultChoicesDescription
APP_IDyesthe app's ID, from oo apps list

It also takes the connection options.

oo apps retry

Run the app's failed step again, as Retry on its page does: a new plan for a failed plan or VM creation, whose VM is then created again (oo apps vm, or at the link it prints); publishing its address; the install; a stop or start; or its removal. It is refused when nothing failed (hosted_app_nothing_failed); failure in oo apps show says which step failed and why.

oo apps retry APP_ID
ArgumentRequiredDefaultChoicesDescription
APP_IDyesthe app's ID, from oo apps list

It also takes the connection options.

oo apps stop

Stop the app: its VM powers off and keeps the app's data, still billed as compute and still backed up, until oo apps start or oo apps remove.

oo apps stop [options] APP_ID
ArgumentRequiredDefaultChoicesDescription
APP_IDyesthe app's ID, from oo apps list
--yesnoconfirm it now; an agent passes it only once the person confirmed it in chat

It also takes the connection options.

oo apps start

Power a stopped app's VM on again

oo apps start APP_ID
ArgumentRequiredDefaultChoicesDescription
APP_IDyesthe app's ID, from oo apps list

It also takes the connection options.

oo apps access

Choose who may sign in to the app: everyone in the Sunport, or chosen: administrators and the people given access to it (services.use on services/APP_ID). Administrators always may.

oo apps access APP_ID who
ArgumentRequiredDefaultChoicesDescription
APP_IDyesthe app's ID, from oo apps list
whoyeseveryone, choseneveryone or chosen

It also takes the connection options.

oo apps people

Print everyone in the Sunport as JSON, as the app's page lists them, each with whether they may sign in (access: administrator, granted by their own or their team's grant, everyone while everyone in the Sunport may, or null) and their own exact grants on the app (grants), which oo permissions remove takes away. It lists everyone, so it needs people.read on everything, with no person denied, besides managing the app.

In an app that keeps its own accounts, each person also has their account there (account: state waiting, creating, changing, ready, suspended, refused, failed, or conflict when someone else holds it as their chat account, with error, username and temporaryPassword), and people with an account but no login here are listed too (accountId null): invited, or whose login went.

oo apps people APP_ID
ArgumentRequiredDefaultChoicesDescription
APP_IDyesthe app's ID, from oo apps list

It also takes the connection options.

oo apps account

Print your account in an app that keeps its own accounts, as JSON: state (ready, creating, changing, suspended, refused, failed, conflict, waiting or none), username, the app's address (url, once it is live), and a temporary password if you have one (temporaryPassword: when it was issued, when it ends unless you change it in the app, and waiting, whether it waits for you to see it with oo apps password --reveal).

oo apps account APP_ID
ArgumentRequiredDefaultChoicesDescription
APP_IDyesthe app's ID, from oo apps list

It also takes the connection options.

oo apps password

Give your account in the app a new password, or with --person someone else's, as whoever manages the app. It prints the job that makes it; once it is done, --reveal shows it once, to whoever asked, then forgets it: keep it, or --output it to a protected file. A temporary password ends after 7 days unless changed in the app. Only a person with their own sign-in or an unrestricted key of their own asks for or reads one (full_identity_required otherwise), never an agent. An account that is suspended or changing is refused (hosted_app_account_suspended, hosted_app_account_busy).

oo apps password [options] APP_ID
ArgumentRequiredDefaultChoicesDescription
APP_IDyesthe app's ID, from oo apps list
--person PERSON_IDnosomeone else's account, as whoever manages the app
--revealnoshow the new password once, after its job is done
--output FILEnowith --reveal: write it to a protected file instead of printing it
--overwritenoreplace an existing --output file

It also takes the connection options.

oo apps sync

Compare people's accounts in an app that keeps its own accounts with who may sign in now, and make, change, suspend or bring back each one that differs, one at a time: everyone with an account or who may sign in, or only each --person. It prints how many it marked; oo apps people shows how each stands. It needs services.write on the app.

oo apps sync [options] APP_ID
ArgumentRequiredDefaultChoicesDescription
APP_IDyesthe app's ID, from oo apps list
--person PERSON_IDnoonly this person; repeat for more

It also takes the connection options.

oo apps existing

The accounts people made in an app that keeps its own accounts before the Sunport kept them, as JSON: each with its username, email, whether it is the app's administrator and active, the person it belongs to (linked), or the person here whose address it has (match), whom oo apps adopt links it to. --refresh asks the app to list them again first, as the Sunport's own job; the answer then has job while it runs, and the accounts the last list found. It needs services.write on the app and people.read on everyone.

oo apps existing [options] APP_ID
ArgumentRequiredDefaultChoicesDescription
APP_IDyesthe app's ID, from oo apps list
--refreshnoask the app to list its accounts again first

It also takes the connection options.

oo apps adopt

Link each of the app's accounts to the person whose address it has, as oo apps existing matched them: the account becomes theirs, gets their role there, and their agents' bots let them in. Only a match is linked, never an account by its email alone (hosted_app_account_not_theirs). It asks first, or takes --yes.

oo apps adopt [options] APP_ID
ArgumentRequiredDefaultChoicesDescription
APP_IDyesthe app's ID, from oo apps list
--link PERSON_ID=USER_IDyesa person and the app account to link to them, from oo apps existing; repeat for more
--yesnoconfirm it now; an agent passes it only once the person confirmed it in chat

It also takes the connection options.

oo apps tokens

Access tokens for your own account in an app that makes them, such as Mattermost, for a script or a bot that acts as you there. Only a Sunport administrator makes one, for their own account, with their own sign-in or an unrestricted key of their own (full_identity_required otherwise), never an agent. create prints the token being made; once it is ready, reveal shows it once, to its owner, then forgets it: keep it, or --output it to a protected file. list shows yours, or with --all everyone's as whoever manages the app, never their values. revoke ends one, yours or as whoever manages the app anyone's; it asks first, or takes --yes. A token stops working when its owner is no longer an administrator, or their account in the app is suspended.

oo apps tokens [COMMAND]

It also takes the connection options.

oo apps tokens list

Your tokens, or everyone's with --all

oo apps tokens list [options] APP_ID
ArgumentRequiredDefaultChoicesDescription
APP_IDyesthe app's ID, from oo apps list
--allnoeveryone's, as whoever manages the app

It also takes the connection options.

oo apps tokens create

Make a token for your own account

oo apps tokens create [options] APP_ID
ArgumentRequiredDefaultChoicesDescription
APP_IDyesthe app's ID, from oo apps list
--description DESCRIPTIONyeswhat it is for, as the app lists it: one line, at most 64 characters

It also takes the connection options.

oo apps tokens reveal

Show a new token once, to its owner

oo apps tokens reveal [options] APP_ID TOKEN_ID
ArgumentRequiredDefaultChoicesDescription
APP_IDyesthe app's ID, from oo apps list
TOKEN_IDyesthe token's ID, from oo apps tokens list
--output FILEnowrite it to a protected file instead of printing it
--overwritenoreplace an existing --output file

It also takes the connection options.

oo apps tokens revoke

End a token

oo apps tokens revoke [options] APP_ID TOKEN_ID
ArgumentRequiredDefaultChoicesDescription
APP_IDyesthe app's ID, from oo apps list
TOKEN_IDyesthe token's ID, from oo apps tokens list
--yesnoconfirm it now; an agent passes it only once the person confirmed it in chat

It also takes the connection options.

oo apps first-admin

Print the administrator account the app made when it was installed, as JSON: username, password and the app's address (url, once it is live). It is shown once, to whoever added the app, created its VM or installed it, then forgotten (hosted_app_first_admin_gone): keep it, or --output it to a protected file. Only that person reads it, with their own sign-in or an unrestricted key of their own (full_identity_required otherwise), never an agent.

oo apps first-admin [options] APP_ID
ArgumentRequiredDefaultChoicesDescription
APP_IDyesthe app's ID, from oo apps list
--output FILEnowrite it to a protected file instead of printing it
--overwritenoreplace an existing --output file

It also takes the connection options.

oo apps remove

Remove the app: its VM goes, with all the app's data and accounts. To keep the data, stop it instead (oo apps stop). It asks first, or takes --yes.

oo apps remove [options] APP_ID
ArgumentRequiredDefaultChoicesDescription
APP_IDyesthe app's ID, from oo apps list
--yesnoconfirm it now; an agent passes it only once the person confirmed it in chat

It also takes the connection options.

On this page