Connections

The Connections page is one list of apps. Yours shows every app you connected, one row each, with its logo, what state it is in, and the one thing to do next. All apps shows everything you could connect, also by logo, so you can find the app you want at a glance.

Apps come in two kinds, and both live in the same list:

• Apps your agents use, such as Gmail. You choose an account, a named agent, and the exact actions or notifications it may use.
• Chat apps, such as Telegram and Slack, where people reach your agents. They carry a small Chat tag. See Relay Messaging.

Click a connected app to open its side panel: who can use it, what agents did with it lately, and a few things to try. Everything else (its name, notifications, exact actions, pause, disconnect) is under More.

This guide covers apps your agents use.

Connect an account in three steps

You can connect several accounts for one service: each account is its own row. To add another, open the app's side panel, open More and choose Connect another account (for Gmail, Connect another Gmail account). Labels keep a personal account separate from a work account. Access always belongs to the exact connection you selected.

High-risk actions wait 60 seconds

Some actions can't be taken back, like deleting an email or sending one. On Trusted, when one of your agents takes such an action from a chat where it works on its own, DorkOS holds it for 60 seconds before it runs.

While it waits, everyone is told. A notification appears in the Inbox (the bell) in every open DorkOS window, and on your phone if you turned on phone alerts. It says which agent, which action and which app, for example "Scout will run “Delete message” in Gmail". Clicking the phone or desktop alert opens the Inbox on that notification, where Cancel is.

• Cancel stops it. The action never runs, and the agent is told who cancelled it.
• Any other agent can cancel it too. The agent that asked can't cancel its own.
• Stopping the chat cancels it.
• When the minute is up, DorkOS checks again. If the action no longer qualifies to run without asking you (say you switched to Careful, or the agent was switched off), it doesn't run. You can still cancel while it checks.
• If DorkOS restarts while it waits, the action is dropped and never runs. The notification says so.
• If DorkOS restarts just as the action is being sent, it may have run. The notification says so and names the app to check.
• If nobody cancels, it runs exactly as it was asked, on the same account, and a second notification says it ran.
• If DorkOS can't show the notification or record the action, there is no wait: you get an approval card instead.
• If DorkOS can't confirm the outcome, the second notification says it may have run and names the app to check.

This is a cancel, not an undo. Once an action has run, DorkOS can't take it back.

Everything else still asks you first with an approval card: on Careful, in a chat that asks before acting, when someone outside your team started the chat (a Telegram or Slack message, say), and when the request doesn't come from an agent's chat.

Words from outside your team always bring back the card, even in a chat set to Full. Once an agent has read them, it asks you before it sends, replies or forwards an email, creates a calendar event with guests, changes any calendar event, or takes any action that can't be taken back. Drafts, labels and reading still run without asking.

Agents can ask, but you decide

An agent can ask for a service and explain why it needs access. It asks for one of the same two levels you choose from: Read (look at things there) or Read and write (also change things there). The request does not reveal your private account list and does not grant anything.

You answer with one card, wherever you meet the request. In the chat or room where the agent asked, the card walks you through signing in (if needed) and then "Let DorkBot use Gmail?" — named for the agent that asked — with the reason it gave, starting on the level it asked for. The card is always about that one agent. If it also wants to know when something new happens (like a new email), the card asks you right after which updates it gets. You can also open Connections directly, where every pending request waits in a Needs you strip at the top and opens the same card.

An agent keeps one open request per app. Asking again, even with a different reason, doesn't add a second card, and an agent can't open requests faster than you could answer them.

If the request is still attached to a live turn, the agent receives the result there, right on the card. Whatever you answer, the agent is told plainly what happens next, including what you left out, such as "you can read Gmail, but not change anything in it". After a restart, DorkOS can continue the exact recorded chat once. A denied, expired, failed, or deleted request grants no access.

Actions and notifications are separate

DorkOS-managed account notifications are not available yet. The choices below describe notification access when the selected route supports it. Slack and Telegram Messaging are separate from this limitation.

An action grant lets an agent run a reviewed operation, such as reading a profile. It does not let the agent receive account activity.

A notification grant names all of these:

• the exact connection;
• the activity type and any supported filter;
• the receiving agent;
• the destination, such as an agent chat, room, or supported messaging destination.

To change a notification's scope, remove it and create a reviewed replacement. Standalone notification editing and pause controls are not part of this release. Pausing the whole connection remains available.

Delivery timing comes from the service. Some services send webhooks, some check on a schedule, and some do not report their timing. DorkOS does not label every notification as real time.

Choose where account access runs

DorkOS does not charge for account actions in this release. Usage records distinguish which party's service project handled an attempt, but there is no billing or invoice flow.

When login is off

A local DorkOS installation without login has one local owner. Keep it on a trusted machine and network. Do not expose an installation without login to the public internet.

Program commands still name an agent and can use only that agent's approved connections. Omitting --agent never widens access. Through the supported agent and program paths, a request can ask for access but cannot approve itself.

One kind of write does not have that protection: changing who can use an app — sharing it, narrowing it, disconnecting it. With login off, DorkOS cannot tell that write apart from one the app itself made, so anything with a shell on this machine can make it, the same as the app could. Every agent is just the widest version of that change, not a special case. Turning login on closes the gap for all of them, because from then on only you, signed in, can make those writes. Until then, changing an app's access is a choice for a machine you trust.

These controls are boundaries inside DorkOS. They do not isolate other software running as your operating-system user. That software can reach the same local files and credentials that you can. The threat model explains token lifetime, runtime settings, and this same-user limit.

Remove access

Removing an agent's access stops its next action and revokes its notification grants for that connection. Pausing a connection stops local use without deleting it. Disconnecting stops every agent from using the account at once. DorkOS then ends the account's access at the service in the background.

If the service can't be reached, DorkOS keeps trying on its own, and the account stays disconnected here while it waits. If DorkOS can't finish at all (for example, your DorkOS account is no longer linked), the panel says so and, for apps like Gmail, links to the page where you can remove the access yourself. You can remove a disconnected app from your list at any time. A request already sent to another service cannot be recalled.

To keep an agent away from an app in just one chat, open that chat's details. Each app the agent was given has a switch there. Turning it off only affects that chat. Turning it back on puts back the access that chat had, and never adds any.