For organizations

Administer an instance

This guide is for the admin of an arkush instance, which is most often an org install. Each section covers one task: what the admin changes in the app, what the operator changes in the environment file, and what the app shows when nothing is configured.

On arkush.app, the admins are the people who run arkush.app. A person who signs in there holds no admin right, and the Administration areas do not show.

Two roles share an instance. The admin works inside the app, in Administration. The operator runs the service: the host, the environment file, and the files beside the database. One person can hold both roles.

Before you start

The admin right comes from ARKUSH_ADMINS in the environment file. A person who signs in with an address on that list has three ways in:

• Select the account button at the right end of the toolbar, then Administration.
• On the dashboard list or the datasource list, select Administration in the section links at the top.
• Open the address /admin on this instance.

Administration is divided into areas, one per job. A panel on the left lists them, and each one has its own address. An area holds one or more sections. For example, the Access area holds a Rights section and a Groups section.

• /admin/users — Users: everyone the instance has seen, and what each person holds.
• /admin/access — Access: who holds each right, the groups a right can name, and the settings that decide who may connect an agent, download or export data, and open a dashboard to everyone.
• /admin/credentials — Credentials: what the server runs warehouse queries as.
• /admin/deliveries — Deliveries: what leaves on a schedule, and where data may go.
• /admin/appearance — Appearance: the instance name, logo, contact, and default theme.
• /admin/pages — Pages: the words the instance writes for itself.
• /admin/configuration — Configuration: the remaining deployment settings, and the handbook.

Open /admin itself for the index. On it, you see each problem on the instance that needs attention, with a button to the area where you fix it. When nothing needs attention, the index says so. Each area's page opens with one line that says what it holds.

The split follows one rule. The admin changes what changes often, in the app: group membership, the service accounts, the destinations, the pages, and the instance's name. The operator sets who holds power and where the service reads from, in the environment file: the rights, sign-in, the service's own Google credential, and the file locations.

A change in the app applies at once. The service reads the environment file only when it starts, so a changed variable applies after the operator recreates the container.

Give a person a right

Two rights sit above ordinary use, and a person who builds dashboards needs neither. The admin right manages the instance. The analyst right curates the theme library, the instance fonts and the datasource library, sets the Official stamp, and sends a delivery with Send now. It also reads a private sheet or file with the service's own Google account.

Neither right reaches the warehouse. Google Cloud decides who may run a query under a service account (Register service accounts).

In the app

The Access area shows who holds each right. It does not edit them. With a group entry in an allowlist, you make the everyday change in the app: every member of the group holds the right.

1. Open Administration, then Access.
2. Under Rights, find a group entry in the allowlist, such as group:analysts.
3. In Groups, add the person to that group, or remove the person.

The right follows the membership at once. A group that an allowlist names carries a grants admin or grants analyst tag on its row.

In the environment file

• ARKUSH_ADMINS — the admin right: full addresses, or group:<name> entries. * stops the service at start, because admin is power over other people's work.
• ARKUSH_ANALYSTS — the analyst right: addresses or group entries. The single entry * makes everyone signed in an analyst.

To give one person a right without a group, ask the operator to add the address. An address in an allowlist applies after the operator recreates the container.

With nothing configured

An unset allowlist means nobody holds the right. Rights reads nobody for analysts. An instance with no admin shows no Administration to anyone.

Read a setting you cannot change here

The operator sets some settings in the environment file. Each one shows in the area whose job it serves, with the variable that sets it and its value on this instance. Sign-in settings are in Access. The warehouse and the outbound hosts are in Credentials. The rest are in Configuration.

The settings show as a table with two columns: Setting, the variable's name, and Value on this server. A value reads not set when the deployment gives the variable no value. A secret reads set, hidden or not set and never shows the value. To change any of them, ask the operator to edit the environment file and recreate the container.

Two kinds of setting have no row. A file location has none: the area that uses the file names its path where you meet it. A setting with its own control in Administration, such as the two rights, the groups backend or the upload quota, shows in that control instead.

Limit agents, downloads, open sharing and self-deletion

With the access settings, an admin decides what people on this instance may do: connect an agent, download or export data, open a dashboard to everyone signed in, and delete their own account. The first three start at the widest value, and self-deletion starts off. An admin changes them in the app. No environment variable sets them, and they apply with no restart.

The agent setting and the rows setting can take a list of named people and groups. An entry is an email address or a group, written group:<name>. To manage those groups, see Manage groups.

In the app

1. Open Administration, then Access, and find Settings.
2. In Connect an agent, choose who may connect one. An agent acts as the person who approved it, and reads nothing that person cannot read.
3. In Download or export data, choose who may take rows off the instance. This covers the CSV download, the export of an open dashboard, the tables in a subscription, and how many rows an agent's SQL preview answers with.
4. In Open a dashboard to everyone signed in, choose Every editor or Admins only. This covers dashboards, datasource-library entries and uploaded files. Where the instance publishes to the internet, the admin also decides with this choice who may publish: Every editor lets each owner publish their own dashboard, and Admins only keeps publishing to admins who own the dashboard. Admins only also keeps Transfer ownership to admins, so an owner cannot hand a dashboard to another person.
5. Select People may delete their own account to let each person delete their account from the Your data section of their Settings page. While the box is clear, that section names the contact address of this server for the request, and an admin deletes the account from Users.
6. If you chose Named people and groups, add each entry.
7. Select Save.

The settings apply to the next request. A person the agent setting refuses loses their agents at the next call, and their connection stops with a message naming an admin. A person the rows setting refuses stops seeing Data as CSV, and their export of a dashboard writes the structure with no rows in it. Every change writes one audit line.

What the rows setting does not do

A viewer's browser holds every row of every snapshot, because the dashboard draws and filters from those rows. The rows setting hides the acts that write a file. It cannot keep the rows out of the browser, and a table block still shows them. The two controls that do hold are who may view a dashboard, and what the dashboard's SQL selects: the readers of a dashboard built on totals get only totals.

With nothing set

Everyone signed in may connect an agent, every viewer may download or export data, and every editor may open a dashboard to everyone signed in.

If anyone can sign in to this instance, only an admin shares a dashboard, opens it to everyone signed in, or transfers its ownership, whatever the sharing setting says. Everyone else keeps their dashboards private, so no person meets a stranger's email address.

Publishing to the internet is off until the operator sets ARKUSH_ALLOW_PUBLISHING=true in the instance's environment. The Access area reports the switch. With it off, nobody publishes, the Share panel shows no publish section, and every published address answers nothing — including one published before the switch went off. With it on, the sharing choice above decides who may publish, and only a dashboard's owner publishes it. Any editor can unpublish, whatever the switch and the setting say.

To take down a published dashboard that you cannot edit, select it with Select on the Dashboards page and close it to private. That deletes the published copy. Access lists every published dashboard. Moving a published dashboard to the trash unpublishes it too, and restoring it does not publish it again.

Manage groups

A group is a named set of people. A person can share a dashboard with a group, and an allowlist can name one. The instance reads membership from one of two backends. You see which one in the section heading: Groups for the membership file that admins edit, and Google Groups for the Google Workspace directory.

In the app: Groups

1. Open Administration, then Access, and find Groups.
2. Select Add group….
3. Type a short name in lowercase, such as finance. A name holds no space, : or @.
4. Type or paste addresses into Add members, then press Enter.
5. Select Add group.

To change a group, select Edit on its row. Remove a member with the close button on the member's chip, add members the same way, and select Save members. The editor marks a member that the instance has never seen — no sign-in, no dashboard, no share, no other group. When you see the mark, check the address for a typo. The mark does not stop the save.

Delete removes a group after a dialog that counts the dashboards shared with it. Shares and allowlist entries that name the group then match nobody.

In the app: Google Groups

1. Open Administration, then Access, and find Google Groups.
2. Select Add group….
3. Type the group's address, such as [email protected].
4. Select Add group. The service checks the address against the directory first.

Membership shows read-only. Change who is in a group in Google. After Remove, this instance no longer reads the group, and the group stays in Google.

In the environment file

• ARKUSH_GROUPS — the backend: file, the default, or google. Only the operator changes the backend.
• ARKUSH_GROUPS_FILE and ARKUSH_GOOGLE_GROUPS_FILE — move the backend's file out of the state directory. Neither is required.

The google backend also needs a grant outside the file. The service's own identity needs the Groups Reader admin role, in the Google Workspace Admin console.

With nothing configured

Groups work with no setting. A new instance shows an empty Groups section, and the first group an admin adds creates the file. On the Google backend, a group that Google has not answered for yet lists no members.

Register service accounts

A BigQuery datasource that runs on the server names a registered service account in Runs as. The service impersonates that account, so no key is stored anywhere. Three parties share this task. The admin keeps the registry. The operator gives the service its credential. IAM in Google Cloud decides who may use each account.

In the app

1. Open Administration, then Credentials.
2. Select Register account….
3. Type the account's address, such as [email protected].
4. In Label, say what the account is for.
5. Select Register account.
6. Select Verify on the new row.

Verify asks Google for a real token. On failure, the row names the cause. If a gcloud command fixes that cause, the row shows the command.

Remove takes an account out of the registry after a dialog. Datasources that name the account keep their data, but their next run refuses and their schedules pause.

Datasources without an account

This section appears only while a BigQuery datasource names no service account. Such a datasource cannot run on the server, and its schedule is paused. Each row opens the dashboard's or the library entry's details page.

The fix is Runs as: in the dashboard's Data workspace, or on the entry's details page. A person who can edit the dashboard, or manage the entry, sets it. The section disappears when the list is empty.

In the environment file

• ARKUSH_BQ_PROJECT — the Google Cloud project that server-side runs bill to. The service also needs its own Google credential: the host's metadata server, or a key file that GOOGLE_APPLICATION_CREDENTIALS names.
• ARKUSH_BQ_MAX_BYTES_BILLED — the most bytes that one server-side run can bill.
• ARKUSH_SERVICE_ACCOUNTS_FILE — moves the registry file out of the state directory. It is not required.

In Google Cloud

The grants that let a person use an account are in Google Cloud, never in arkush. Whoever manages IAM on the account's project makes these grants:

• A person needs the Service Account User role on the account itself to pick it in Runs as and to run under it. A grant on the account's project does not count, and the refusal says so. Never give a person Service Account Token Creator: that role lets them mint the account's token on their own machine.
• To grant a team once, grant Service Account User to a Google Workspace group, named by its email address, such as [email protected]. In the Google Cloud console, open IAM & Admin → Service accounts, select the account, then Permissions → Grant access, and enter the group's address as the principal. A group in this page's Groups section is not a Google group, and Google Cloud cannot grant to it. The grant works with either groups backend, and the group needs no entry in Google Groups.
• A group grant needs a one-time setup, and until it is done the group grants nobody. Ask for two things. The operator enables the Cloud Identity API in the Google Cloud project the service runs under. A Google Workspace admin gives the service's own identity the Groups Reader admin role, in the Google Workspace Admin console. When you, as an admin, meet the refusal for a group grant, it names the service's own identity and both steps, so you can pass it on as written.
• When a grant works, the account appears in the person's Runs as list after they reload the app. A new grant, or a new member of a granted group, can take up to ten minutes to count.
• Service Account User also lets a person attach the account to a resource they can create in Google Cloud, such as a VM or a scheduled query. Keep each registered account in a project where the people who write SQL create nothing.
• The service's own identity needs two roles on each account: Service Account Token Creator and Service Account Viewer. Verify checks the first role only. Without the second, a run refuses with the command that grants it.
• The account itself needs BigQuery Job User on the billing project, and BigQuery Data Viewer on the datasets its team reads.

With nothing configured

Every instance has the registry. Empty, the section reads "No service accounts registered yet.", and nothing runs as a service account. With no ARKUSH_BQ_PROJECT, the Server-side BigQuery row in Configuration reads not configured — people query with their own Google accounts. Verify then names the variable.

See what leaves on a schedule

A delivery sends a dashboard's charts and tables to a Slack channel, a list of email addresses, or a webhook on a schedule. Each one is set up on its own dashboard, so no single dashboard shows the whole picture. The Deliveries area does: every delivery on the instance, grouped by the destination it posts to.

In the app

1. Open Administration, then Deliveries.
2. Read What leaves on a schedule. Each destination lists the dashboards that send to it, with the schedule, who blessed it, and how the last send went.
3. To see a delivery's message and blocks, select the dashboard's name.

A delivery marked not blessed — never sends is set up but inactive. A delivery sends only after an analyst selects Send now on that dashboard and the send succeeds. An analyst who loses the analyst right, or loses edit access to the dashboard, stops every delivery they blessed. A delivery also stops when a datasource's rows no longer match the run that produced them, because someone wrote rows into the dashboard after the run. One authorized run of each affected datasource starts the delivery again.

Before you remove a destination

Each destination in the registry below lists the dashboards it serves. When you remove the entry, every one of them stops at the next schedule, and the dashboards themselves have no sign of it. Read that line first.

With nothing set

No dashboard sends anything, and the list says so.

Add delivery destinations

A destination is a named place that deliveries send to: a Slack channel, a list of email addresses, or a webhook. A dashboard names the destination and never sees its token, its address or its recipients. The Destinations section is the one place that shows them.

Before you start

• For Slack, get the bot token of the Slack app installed in the workspace. It needs the chat:write and files:write scopes. With files:read too, a delivered table posts in the thread of the message that carries its charts. Invite the bot to each channel it posts to, and copy each channel's id, such as C0123456789. The channel name does not work.
• For email, the operator sets up the mail relay once, in the environment file. Without it, a send to an email destination fails and names the relay.
• For a webhook, get the https address of the receiver, and make a secret of at least 16 characters. The receiver checks the signature of each send with that secret.

In the app

1. Open Administration, then Deliveries.
2. Write one entry per destination in the editor, in this shape:

   destinations:
     team-metrics:
       kind: slack
       channel: C0123456789
       token: xoxb-…
       label: '#team-metrics'
     weekly-report:
       kind: email
       to: [[email protected], [email protected]]
     ops-flow:
       kind: webhook
       url: https://hooks.example.org/arkush
       secret: …

3. Select Save destinations.
4. If an email address is outside the people who can sign in here, the app names it and asks once. Select Save anyway to send reports there, or cancel and remove it.

The service checks the file before it writes. An invalid file refuses with the problem named, and the stored file stays as it was. If the file changed after it loaded, the save refuses too: select Reload and make the edit again.

Subscriptions send a dashboard to one person, through the one destination marked dm: true. On an email destination, each person gets the mail at their sign-in address. On a webhook, the body names the person, and the receiver routes it. On Slack, the bot needs four scopes: chat:write and files:write to post, and users:read.email and im:write to find each person and open the direct message.

To mark a destination, add the line dm: true under its name, beside kind:

destinations:
  team-metrics:
    kind: slack
    channel: C0123456789
    token: xoxb-…
    dm: true

The marked destination is the subscription channel, whatever its kind. If two destinations carry the mark, the save refuses. If none carries the mark and all the Slack destinations use one bot token, the first Slack destination is the subscription channel.

In the environment file

• ARKUSH_REFRESH_INTERVAL_MINUTES — how often the service looks for due deliveries, every 5 minutes by default. With 0 or off, scheduled deliveries send only when the operator starts a sweep by hand.
• ARKUSH_DESTINATIONS_FILE — moves the registry file out of the state directory. It is not required.

With nothing configured

Every instance has the registry. Empty, the editor is blank, and the Deliveries flyout offers no Deliver…. An admin reads that channels are added here. Everyone else reads that the server has no channel to post to. Without a destination marked for subscriptions, the Subscriptions flyout does the same: an admin reads the setup step, and everyone else reads that the server cannot send subscriptions.

Send people their inbox by email

With inbox email on, each person gets an email when an entry in their inbox stays unread for 15 minutes. Entries that arrive together come in one email. Each person chooses in their own Settings what they get. By default they get email only when something broke or needs them: a refresh or a send that stopped, and a dashboard in the trash. The email names the dashboard, what happened and the people involved. It never holds the text of a comment.

Before you start

• The mail relay is set up. The operator sets it once in the environment file, with ARKUSH_SMTP_HOST and the other ARKUSH_SMTP_* variables. Without a relay, the Inbox messages section says that the server has no mail relay, and it shows no email switch.
• The scheduled sweep runs. The sweep is the timer that refreshes scheduled data and sends deliveries, every 5 minutes by default, and it also sends the inbox messages. Where it does not run, the Inbox messages section says so. To check the setting, read ARKUSH_REFRESH_INTERVAL_MINUTES as Read a setting you cannot change here shows. The value 0 or off stops the timer. The sweep then runs only when something calls the manual sweep route, which ARKUSH_REFRESH_TOKEN opens.

In the app

1. Open Administration, then Deliveries.
2. In Inbox messages, tick Email people about their inbox.
3. Select Save.

The section then says how many people got an inbox email in the last 24 hours. Right after you turn email on, it says that nobody got one. Only entries that arrive after you turn email on are sent, so nobody gets a backlog. The first email leaves no sooner than 15 minutes after a new entry. To stop the email, clear the box and save. At most 120 inbox emails leave in an hour, and the rest wait for a later sweep.

Each person chooses what they get in their own Settings, under Notifications: a table with a row per category and a column per channel.

Send the inbox in Slack too

People can also get their unread entries as a Slack direct message, from the bot that sends subscriptions. Every Slack box starts off, so a person gets nothing in Slack until they tick it in the Slack column of Settings, under Notifications. The Slack switch does not need the mail relay.

1. Make sure that a Slack destination is the subscription channel. See Add delivery destinations. Its bot needs the users:read.email and im:write scopes. A Slack workspace admin adds them in the settings of the Slack app, on the OAuth & Permissions page, and installs the app again. If Slack then shows a new bot token, paste it into the destination and save. Until a Slack destination is the subscription channel, the Inbox messages section says that no Slack bot sends direct messages, and it shows no Slack switch.
2. In Inbox messages, tick Send people their inbox in Slack.
3. Select Save.

The first message to a person finds their Slack member by their email address. If Slack has no member at that address, no message reaches the person. The person then selects Subscribe on any dashboard and pastes their member ID once when the panel asks for it. The member ID is in their Slack profile, under ⋮ → Copy member ID. If a bot scope is missing, the subscriptions of a person show the error in their list, and the operator sees the failure in the log.

With nothing set

Inbox messages are off after an install and after an upgrade. Each person's Settings says that this server sends no messages about the inbox, and the inbox in the app shows every entry.

Hear when Slack deactivates someone

When a person leaves, their subscriptions, the deliveries they blessed (the channel deliveries they started with Send now as an analyst), the scheduled refreshes that run as them, and their agents keep running until an admin suspends the account. Where a Slack destination is the subscription channel, Arkush asks Slack once a day about each person who has such work. When Slack deactivates one of them, every admin gets an Admin notice in the Inbox. It names the person and what runs in their name.

Before you start

• A Slack destination is the subscription channel. See Add delivery destinations. The bot needs no scope beyond the ones subscriptions need.
• The scheduled sweep runs. See Send people their inbox by email, under Before you start.

When the alert runs, the line at the top of the Users area says that every admin gets an Inbox notice when Slack deactivates someone with work in their name.

When a notice arrives

1. In the Inbox, select the person's address on the notice.
2. The Users area opens on the person's row. Select Suspend, then confirm. Suspend stops everything that runs in their name. See Suspend an account.
3. Do the rest of Offboard a person: transfer their dashboards as Transfer a dashboard or recover access shows, then delete the account.

Arkush never suspends anyone by itself. The notice resolves at the next sweep after one of these: nothing runs in the person's name any more, a suspension included, or Slack reactivates the person.

If the person has not left, for example after a move to another Slack workspace, check with the person or their team. Then select Done in the menu of the notice. The notice stays done until Slack's answer about the person changes again.

With nothing set

Without a Slack subscription channel, no notice comes. The Users area says that departure alerts are off and links to Deliveries.

See who joined the waitlist

An instance where anyone can sign in keeps a waitlist for Arkush for organizations. Where a feature is missing, the app says the feature comes with Arkush for organizations and links to the Arkush for organizations page. A signed-in person joins there. The entry stores the person's email address, the date, the features that brought them, and what they wrote about themself.

In the app

1. Open Administration, then Users.
2. Read Waitlist. Each person shows with the date, the features that brought them and what they wrote. A count per feature sits above the list.

A person leaves the list from the Arkush for organizations page. Delete account removes the entry too, and the server deletes an entry 12 months after the person joined.

With nothing set

No setting turns the waitlist on or off. An instance that limits who signs in keeps no waitlist, and each feature keeps the line it shows where the feature is not set up. The section shows here only when the list holds entries from a time anyone could sign in.

Set the instance identity

The instance identity is what the instance says about itself: a name, a logo, and a security contact. The name shows in the toolbar and the browser tab, and the logo in the toolbar, to everyone who opens the app. The landing page, the legal pages and the About page use the name too.

In the app

1. Open Administration, then Appearance, and find Instance identity.
2. In Name, type the instance's name.
3. In Logo, type the https address of an image.
4. In Security contact, type an email address or an https page, such as [email protected].
5. Select Save.

With a logo, the toolbar shows the logo and uses the name as its alternative text. The service publishes the security contact at /.well-known/security.txt, where a security researcher looks for it. Every published dashboard's page also carries Report this page, which sends its reader to the same contact. With no contact set, a published page has no report link.

In the environment file

Nothing. No variable sets the identity. The old variables ARKUSH_INSTANCE_NAME, ARKUSH_LOGO_URL and ARKUSH_SECURITY_CONTACT stop the service at start, with a message naming Appearance, where the identity is set.

With nothing set

The toolbar says "arkush" alone, and the instance publishes no security.txt.

Choose the default theme

Every new dashboard starts with the default theme, in the app and from an agent. A theme with a light face and a dark face shows each viewer the face for their mode. Dashboards that exist keep their own theme.

In the app

1. Open Administration, then Appearance, and find Default theme.
2. In Theme for new dashboards, pick a theme.

The pick saves at once. The list offers the house theme, the built-in themes, and the saved themes of the theme library. An analyst saves a theme to the library from the theme editor.

A server can hold a different theme for each mode from an earlier version. The list then reads Per mode with the two themes, and new dashboards take the theme for their creator's mode. A dashboard that an agent creates takes the light one. Pick one theme to replace both.

In the environment file

Nothing. No variable sets the default theme.

With nothing set

New dashboards take the house theme, Arkush, in a light face and a dark face. A pick saved as Arkush Light or Arkush Dark in an earlier version means Arkush too, and a pick of one face of a built-in theme means that whole theme. Pick Classic for the plain look the app draws without a theme. A pick whose saved theme was deleted reads Missing theme — house theme applies.

Write the instance pages

The instance pages carry the instance's own words: the landing copy, the examples page, the privacy policy, the terms of service, and the agent context. Each page is one markdown file. A privacy policy names who holds the data on this instance, so the software ships the editor and no words.

In the app

1. Open Administration, then Pages.
2. In the Page row of segments, select Landing page, Examples, Privacy policy, Terms of service or Agent context. Examples shows only on an instance that publishes dashboards to the internet.
3. Write the page in markdown.
4. Select the save button, such as Save privacy policy.
5. Open the page in a new tab and read the result.

The landing copy replaces the headline and the paragraph under it, between the instance name and the sign-in buttons. The buttons and the agent setup stay. A paragraph that holds only ![description](link) shows a picture, or a YouTube or Vimeo video.

The service publishes the privacy policy at /privacy and the terms at /terms. The landing page links each one that has words. The pages take headings, paragraphs, lists, links, bold, italics and code. Raw HTML shows as plain text.

The examples page shows visitors the dashboards you chose, at /examples. The landing page links it from the top bar and beside the sign-in buttons. To add a dashboard, publish it first, then link its published address and say in one line what it shows. A paragraph that holds only ![description](link) shows a picture, such as a preview of the dashboard. The examples page plays no video.

The Agent context page is for agents, not for people. Every agent that authors on this instance reads it as a part of the authoring guide, so write the tables agents should use, the names your team gives to metrics, and your house rules. Leave out anything secret, any credential and any personal data: every agent reads the page, and the text reaches each agent's model vendor. The page holds up to 20 KB. An analyst edits it, and an admin who is not an analyst cannot.

If the file changed after it loaded, the save refuses: select Reload and make the edit again.

In the environment file

• ARKUSH_LANDING_FILE, ARKUSH_EXAMPLES_FILE, ARKUSH_PRIVACY_FILE, ARKUSH_TERMS_FILE and ARKUSH_AGENTS_FILE — move the files. The container image keeps them in the state directory, so none is required.
• ARKUSH_ALLOW_PUBLISHING — whether the examples page exists. Unset, the page answers not found even when it has words, and the landing page does not link it.
• ARKUSH_ALLOW_ANONYMOUS — which landing page shows. Unset, the page speaks to colleagues who open shared dashboards, and offers Sign in only. With true, it also offers Try it without an account.

With nothing written

A blank landing page shows the stock copy. A blank examples page, privacy policy or terms do not exist: the address answers not found, and nothing links to it. If the service cannot read or write a file, the section shows the error with the file's path and its variable. The operator fixes the path.

Review the people on the instance

The Users area lists everyone the instance has seen: from sign-ins, dashboards, shares, agents and groups. It stores nothing of its own. Each row counts the person's agents, dashboards, shared datasources and uploaded storage, and shows their rights and groups.

In the app

1. Open Administration, then Users.
2. Search by email or by log pseudonym, or sort by dashboards owned, storage used or agents connected.
3. Select a person's email to open the row.

The open row starts with Copy email, which copies the person's address for a grant or a group. Under it, the row lists the person's onboarding answers, dashboards, shares, shared datasources, uploaded files, subscriptions and connected agents. Remove on a subscription stops its sends after a dialog. When a person leaves, the row is where Offboard a person starts.

Find a person in the logs

The service's logs never hold an email address. Each line names a person by a pseudonym, for example u_4cd3a619b5290108, which stays the same for that person on this instance. The open row of a person shows their pseudonym. To find who a pseudonym in a log line belongs to, type it in the search field.

When someone reports an error, ask for the time and the code. The link beside the message opens its entry, and the entry shows the code. Give the operator the code, the time and the person's pseudonym. The operator finds the lines with the steps in the install guide, in the section on reading the logs.

In the environment file

• ARKUSH_SIGNIN_ALLOW — who can sign in, when the service signs people in itself: *, a domain such as @example.org, or full addresses. Behind an identity-aware proxy, the proxy decides instead.
• ARKUSH_UPLOAD_QUOTA — the uploaded-file storage each person can use. Configuration shows it. The Users area also names it under the table when people store uploaded files.

With nothing configured

The Users area needs no setting. A new instance lists nobody until someone signs in. An unset quota reads no limit.

Transfer a dashboard or recover access

An admin sees every dashboard's title, owner and dates. To open a dashboard, the admin still needs a share. The acts below reach any dashboard. Each act shows in the dashboard's own sharing list or version history, where the owner sees it.

• Grant me edit access adds the admin as an editor. Withdraw my access removes that share again.
• Transfer ownership gives the dashboard a new owner and keeps its shares.
• Private closes a dashboard to its owner and its shares. An admin never opens a dashboard to everyone: that act stays with its editors.

In the app: one dashboard

1. Open Administration, then Users, and open the owner's row.
2. Under Dashboards they own, find the dashboard. Its row shows its acts as buttons.
3. Select Grant me edit access… or Transfer ownership….
4. For a transfer, type the new owner's email and select Transfer ownership.
5. Read the dialog and confirm.

In the app: several dashboards

1. Open Dashboards — the instance's dashboard list, in the section links at the top, outside Administration.
2. In Scope, pick Every dashboard on this instance.
3. Select Select and tick the dashboards.
4. In the bar, select Share…, Remove access…, Who can view, or More and then Transfer ownership….
5. Read the dialog and confirm.

In this scope, the Access filter on the dashboard list — not the Access area of Administration — offers No owner recorded. It finds the dashboards that nobody owns, which only an admin can reach. Transfer each one to a new owner.

In the environment file

Nothing. These acts work on every instance.

Revoke agent grants

A grant lets an AI agent act as the person who approved it. The agent reaches the dashboards that person reaches, and each change it makes carries that person's name. A person disconnects their own agents in the Connected agents section of their Settings page. An admin sees and revokes every grant.

In the app

1. Open Administration, then Users. The Agents column counts each person's grants.
2. Open the person's row.
3. Under Connected agents, select Revoke on one agent, or Revoke all.
4. Read the dialog and confirm.

A revoked agent stops at once, and a new connection needs a fresh approval. When the service signs people in itself, Revoke all also signs out every browser signed in as the person. It deletes the person's passkeys, and every unused sign-in code sent to the person stops working. Revoke all also removes the person's subscriptions and inbox, and takes the person off every access setting that names them. It does not stop a new sign-in: to end the access of a person who leaves, see Offboard a person. Connected agents shows for every person, including a person who connected no agent. For that person, Revoke all still ends their browser sessions.

In the environment file

No variable turns agents on or off. To limit who may connect one, use the agent setting in Access. When the service signs people in itself, ARKUSH_SIGNIN_ALLOW binds agents too: an address taken off the list stops its agents. A * or @example.org entry does not name a person, so no single address comes off it. There, and behind an identity-aware proxy, Suspend is the cut-off.

Read the onboarding answers

The onboarding ask puts a few of the instance's own questions to each person once, at their first sign-in. From the answers, an admin learns how to set the person up: which group to add them to, which data to share. Only the person and the admins read the answers.

In the app

1. Open Administration, then Users.
2. Open a person's row.
3. Read the answers under About.

To see how many questions this instance asks, open Administration, then Pages: the Onboarding ask row counts them.

Delete account removes the person's answers with the account. A person edits or clears their own answers under About you, in the Profile section of their Settings page. The section shows About you while the instance asks at least one question, or while the person keeps at least one answer.

In the environment file

The app has no editor for the questions. The operator writes them in ask.yml in the state directory, or in the file that ARKUSH_ASK_FILE names. The file holds at most 10 questions, each a label and an optional hint. An edit applies without a restart, so a new question is one request to the operator.

With nothing configured

With no file, or with a file that holds no questions, the Onboarding ask: row reads none. The ask reaches nobody, and stored answers stay readable. The Users area still lists every sign-in.

Suspend an account

A suspension keeps one address out of the instance until an admin lifts it. The address cannot sign in by any method, and its agents and open sessions stop, whatever the sign-in list admits. The person's dashboards and files stay.

In the app

1. Open Administration, then Users.
2. Open the person's row.
3. Under Account, select Suspend.
4. Read the dialog and confirm.

Every browser signed in as the person is signed out, their agents and unused sign-in codes stop working, and every dashboard they published is unpublished. A person who tries to sign in, or who opens the app, reads that an admin suspended the account, with the contact address of the instance. The address shows under Suspended accounts at the top of Users. To let the person back in, select Lift suspension there or in their row. Lifting publishes nothing again. You cannot suspend your own address.

Delete an account

Delete account removes a person's account for good. Use it when a person leaves, or when a person asks for the deletion of their account.

In the app

1. Open Administration, then Users, and open the row.
2. To keep the person's dashboards, select Transfer all N to… under Dashboards they own and type the new owner.
3. To keep a copy of the person's data, select Download their data under Account. The browser saves one JSON file.
4. Under Account, select Delete account.
5. Read the dialog. It counts the dashboards that still go to the trash, the dashboards other people open, the published addresses that stop answering and the uploaded files. Confirm.

The deletion ends every session, agent, passkey and unused sign-in code of the person. It moves the dashboards the person still owns to the trash for 30 days, with "Deleted account" as their owner. To keep one, restore it from the trash on the Dashboards page and transfer it to a new owner. The deletion also deletes their uploaded files, library datasources, sandboxes, subscriptions, inbox, answers and username. It takes the person off every access setting and group file entry. In other people's dashboards, "Deleted account" replaces the person's address on comments and changes. A suspension of the address stays. You cannot delete your own account here.

Signed-in browsers in the row lists the browsers signed in as the person, with Sign out on each. Use it when a person reports a lost device.

Offboard a person

An account is its email address, so ownership, shares and rights follow the address. When a person leaves, the operator, the admin, and the owners of the person's accounts outside arkush each end one part.

1. Admin: in Administration → Users, open the person's row and select Suspend under Account. The suspension ends every way in to arkush at once. See Suspend an account.
2. Operator: where ARKUSH_SIGNIN_ALLOW names the address, remove the address from the list. Behind an identity-aware proxy, block the address at the proxy.
3. Identity provider: suspend the person's account in the organization's identity provider and mail system, such as Google Workspace.
4. GitHub: where people sign in with GitHub, remove the person from each organization in ARKUSH_SIGNIN_GITHUB_ORGS.
5. Operator: remove the address from ARKUSH_ADMINS and ARKUSH_ANALYSTS where it is named.
6. Admin: under Dashboards they own, select Transfer all N to… and type the new owner.
7. Admin: ask the editors of a dashboard to adopt any chart they want from the person's sandbox. A sandbox holds the charts one person made over a dashboard they could view but not edit, and to adopt a chart copies it into the dashboard. The person's row gives the number of their sandboxes, and each editor sees the sandboxes on their dashboard in its Sandboxes panel. The next step removes the sandboxes.
8. Admin: under Account, select Delete account. See Delete an account.
9. Admin: on the Google backend, take the person out of each group in Google. The groups file in Access loses the person with the deletion.
10. Google Cloud: remove the person's Service Account User role on each service account. Where a Google group holds the role, take the person out of that group instead.

Transfer all N to… shows only for a person who owns more than one dashboard. With one dashboard, use Transfer ownership… on its row.

The published address of a dashboard stays the same after a transfer, so the links people posted keep working. The notice after Transfer all N to… names how many of the transferred dashboards are published. The suspension unpublishes every published dashboard the person still owns, and those addresses stop answering. To keep an address answering with no gap, do the transfer before the suspension. After a suspension, the new owner publishes the dashboard again, and it answers at the same address.

To end the access of a person and keep the account, select Revoke all under Connected agents in place of Delete account. Revoke all ends the sessions, agents, passkeys, unused sign-in codes and subscriptions, and keeps the dashboards, the files and the answers.

The suspension in the first step stops every schedule, delivery and subscription in the person's name at the next sweep. Without a suspension, you stop a schedule that rests on the person's run with either of two steps, and the first one you reach takes effect. Removing the address from ARKUSH_SIGNIN_ALLOW pauses every datasource the person blessed. That pause starts at the first sweep after the operator restarts the service with the new list, whatever Google still grants the account. The Google Cloud step pauses the warehouse datasources among them, within an hour.

A Slack delivery that the person blessed with Send now stops at its next due send. It stops when the person loses the analyst right or edit access to the dashboard, or leaves the sign-in allowlist. Another analyst's Send now starts it again.