---
title: The Agents app
description: Start a chat with a coding agent on one of your projects or with an agent on one of your computers, follow it as it works, answer its approvals and read its diffs, from any browser or phone, and install it as an app that notifies you.
section: agents
order: 5
audience: [user, operator]
sources: [services/nodejs-cloud/components/agents, services/nodejs-cloud/app/(agents), services/nodejs-cloud/lib/agents/http.ts, services/nodejs-cloud/app/manifest.ts, services/nodejs-cloud/public/sw.js, services/nodejs-cloud/lib/push, services/nodejs-cloud/lib/agents/notify.ts, services/nodejs-cloud/migrations/0278_push_subscriptions.sql, services/nodejs-cloud/lib/agents/gears.ts, services/nodejs-cloud/components/ui/PillSelect.tsx, services/nodejs-cloud/migrations/0279_agent_chats_gear.sql, services/nodejs-cloud/components/agents/handoff.ts, services/nodejs-cloud/migrations/0332_agent_chats_origin.sql]
features: [cloud.page-agents]
---

The Agents app is at `/agents` in the console, on the rail (`g g` jumps there). It needs the `agents` add-on (included in
Team and up). It opens dark; a light theme you pinned in the console stays light.

## Start a chat

A new chat is one big prompt box. Inside it are three pickers:

- **Where**: **Quick chat** (picked by default: no computer at all, the agent works through MCP servers;
  [Quick chats](/docs/agents/quick-chat.md), where the pickers are **Servers** and **Gear**), a project on one of your daemons (grouped by daemon, with its git branch), **New project…** or **Scratch
  (discarded with the chat)** on a daemon ([Workspaces](#workspaces)), one of your computers, or **My computer (new)**.
- **Gear**: the model preset the agent runs on, as in the CLI ([Gears](#gears) below).
- **Mode**: how much the agent may do without asking.

Each picker opens a list you can drive from the keyboard: arrows move, `Enter` picks, `Esc` closes, and typing a letter
jumps to the next row that starts with it. A long list has a search box. On a phone the list opens as a sheet from the
bottom.

The picker shows how much the agent may do on its own, the way Claude Code does: one arrow (▶) asks first, two arrows
(▶▶, in the warning colour) go ahead without asking, two bars (⏸) only plan. You can change the mode at any time, including
while the agent is working.

| Mode | What the agent does |
|---|---|
| Ask before acting (▶) | Reads the project freely; edits, writes and commands your rules don't allow ask first. The default. |
| Accept edits (▶▶) | Edits files in the project without asking; commands still ask unless a rule allows them. |
| Auto (▶▶) | Accept edits, plus a check on the fast model decides what would otherwise ask. Needs the daemon's OS sandbox (without one the chat runs, and shows, Accept edits). In a [computer chat](/docs/agents/computer-chats.md#asks) it opens sites without asking. |
| Plan first (⏸) | Read-only: it reads and searches, then proposes a plan. |

A chat started from a browser always keeps its approval prompts: the modes that turn them off are not offered.

The next new chat starts with what you chose last: the gear, the mode and where it ran. Changing the gear or the mode inside
a chat counts too. It is saved with your account, so it follows you to your other devices. A choice that no longer exists
(a gear removed, a project or daemon gone, gears locked by your organisation) is skipped, and the chat starts as it did
before.

Type what you want and press `Enter`, or the arrow button. `Shift+Enter` or `Option+Enter` (`Alt+Enter`) starts a new line,
and `⌘↵` / `Ctrl+↵` send too. Enter never sends while an input method (Japanese, Chinese, Korean) is still composing text.
On a phone or tablet with only an on-screen keyboard, Enter is a new line and the arrow button sends. The cloud starts the agent on the
daemon and the chat opens at its own address, `/agents/c/{id}`. Starting can take a few seconds while the daemon starts
the session.

### Start from an issue

From an issue in [Tasks](/docs/cloud/tasks.md#start-an-agent-chat), **Start an agent chat** (`⌘⌥⇧P` / `Ctrl+Alt+Shift+P`,
⌘K, or the issue menu), or `⌘J` / `Ctrl+J` while the issue is open or focused, opens this screen with the issue's brief
already in the prompt box and a **From ENG-12** chip above it. Nothing starts until you send. The brief is what you can
see: the issue's title, status, priority, labels, link and description, its latest three comments, the items linked to
it, and its reference (`issue:<id>`) for the agent to open with `workspace_item_get`. Edit it as you like. The place, gear
and mode are the ones you used last; the brief never changes them. The × on the chip starts the chat without the issue.
Several issues: the first is the chip, and the chat is linked to all of them.

A chat started from an item records it as its **origin**: its header shows **From ENG-12 · title** (a link; `⌘⌥O` /
`Ctrl+Alt+O` goes back to it), and the chat appears on the issue's **Linked** section as "worked in", with its state
(**running**, **needs you**, **done**) updated while it works. A link to `/agents?from=ENG-12` opens the composer the
same way, with a one-line brief. If the issue is deleted or moved out of your reach before you send, the chip goes and
your text stays.

When the agent finishes or asks for an approval, the push goes to you, the person who started the chat
([Notifications](#notifications)); the issue's subscribers are not notified by the chat.

## Gears

A gear is a preset of the main model and its thinking level, the same gears `/gear` offers in the CLI
([Gears](/docs/configuration/gears.md) has the full table). The gear picker lists:

1. **Your organisation's gears** first, when an admin has defined some on the [Gears page](/docs/cloud/console-gears.md).
   The org's default gear is marked and picked for you.
2. **The daemon's own gears**: the cloud asks the daemon's `venom serve` for its gears (`GET /v1/gears`), so you see what
   the CLI on that machine sees: venom's nine built-ins (`1 eco`, `2 normal`, `3 power`, `4 local`, `5 delegate`,
   `6 open`, `7 qwen`, `8 china`, `9 auto`) plus any in that machine's `venom.yaml`, each with its key and the model it
   resolves to there. A gear whose models the daemon doesn't serve is listed as unavailable.

When the daemon can't answer (it is offline, or its daemon is older than this list), the picker shows the nine
built-ins with their first-choice model and says so. A computer chat's picker shows the built-ins too; the cloud
resolves the gear on the computer's daemon when the chat starts.

If your organisation turned on "Members can only use these gears", only its gears are listed, as in the CLI.

**Default** leaves the choice to the daemon: its `venom.yaml` gear, else the orchestrator's defaults.

Each gear also says where its model runs: on the daemon's own keys (`· this machine`) or on your organisation's cloud
keys (`· cloud keys`), as **Model runs on** (Auto, This machine's keys, Cloud keys) in the same box decides; a gear that
can run in neither place says why. See [Where a daemon chat's model runs](/docs/agents/model-source.md).

Starting a chat in a gear starts the session on the model the gear resolves to on that daemon, with the gear's thinking
level, and the chat records the gear. The chat's header shows it like the CLI's status line (`3 power`). In a running
chat you can shift to another gear from the same picker: the agent switches to the new gear's model at once when it is
idle, or at its next turn when it is working. The session keeps its thinking level. Someone reading another member's
chat sees its gear but can't change it.

## Follow the agent

The prompt box moves to the bottom and the conversation streams above it:

- The agent's answer appears as it writes, as formatted text with code blocks.
- Each tool call is one line: a mark (running, done or failed), the tool, and its command or file. Open the chevron to
  see what it was given and what it printed.
- When the agent wants approval, the request appears in the stream with **Allow once**, **Allow for this chat** and
  **Deny**. When it asks a question, its options are buttons, and you can type your own answer instead.
- After a turn that changed files, a **Changed N files** line appears. Open it to list the files, then open a file for its
  diff. The diff is read from the daemon when you open it; the cloud does not keep it. Secret files (`.env` and the like)
  and files the session may not read show why they are hidden instead.

While the agent works:

- **Send** steers it: the message reaches the turn that is running.
- **After this turn** queues the message for when the agent would stop.
- **Stop** (or `Esc`) stops the turn. The chat stays open for the next message.

A screen reader hears when the agent starts working, needs an answer, or finishes.

If the connection drops, the page reconnects and picks up from the last event it had. If the daemon no longer holds the
oldest part of a long chat, a note offers to load the earlier conversation from the session's transcript.

## Computer chats

A computer chat shows the computer's live screen beside the conversation, with **Take control**, the address box and
**Start** above it, and **My computer (new)** in **Where** starts one from a prompt alone. See
[Computer chats](/docs/agents/computer-chats.md).

## The sidebar

Your chats are listed on the left, grouped by project (with the daemon's name) and by computer, the most recent first. A
dot shows which ones are working. Hover a chat (or focus it) to rename it (or press `F2`) or archive it. Archiving stops
the agent and closes its session on the daemon. **New chat** (`⌘J`, or `⌘⇧O` inside Agents; `Ctrl+J` on Windows and Linux) goes back to the prompt box with the cursor in it. `⌘J` works from every app in the workspace, including while you type in a note or an issue, and ⌘K lists it as **New agent chat**. Hover Agents on the app rail to see it.

On a phone the app is one column and the chat list is a drawer behind the menu button.

## Workspaces

A code chat needs no setup on the daemon. Under each daemon in **Where**:

- **New project…** asks for a name and, optionally, a repository to clone (`https://` only). The daemon makes the folder
  in its own workspaces folder, empty with `git init` or cloned, and the chat starts there. The project stays on the
  daemon, listed with the others, until someone deletes it. Leave tokens out of the URL: a public repository clones as
  is, and a private one uses the git login already on the daemon's machine (a credential helper, `gh auth setup-git`,
  the macOS keychain). A clone stops past 2 GiB or 4 minutes.
- **Scratch (discarded with the chat)** runs the chat in a new empty folder. Archiving the chat deletes it; if the daemon
  was offline then, it deletes the folder itself after 7 days without a change.

The daemon picks every path and keeps the folders inside its workspaces folder. Its owner sees them on the daemon's
dashboard and in `venom-daemon projects list`, marked as made from Venom Cloud, and can delete any of them. In the cloud,
the member who made a workspace or an org admin can delete it (`agents_workspace_delete`). Anyone who can start code
chats on a daemon can make workspaces on it. A daemon too old to make workspaces offers only its project folders; update
the desktop daemon.

## Add a project

To work in a folder that is already on the machine, its owner adds it on the daemon: on the dashboard under
**Projects**, or:

```sh
venom-daemon projects add ~/src/my-repo
```

The folder then appears in the picker, with each git repository directly under it. A daemon whose `venom serve` is too
old to list projects is named in the app; update venom and the daemon. Computer chats work without any project.

## Who sees what

Only the member who started a chat can send to it, answer its approvals and questions, and archive it. Org owners and
admins can open any member's chat from its link to read it, without the prompt box. See [Venom Agents](/docs/agents.md) for usage and keys.

## Install the app

Venom installs as an app that opens on Agents:

- **Android** (Chrome, Edge, Samsung Internet): the menu, then **Install app** or **Add to Home screen**.
- **iPhone and iPad** (Safari): **Share**, then **Add to Home Screen**.
- **Desktop** (Chrome, Edge): the install button in the address bar, or the menu's **Install Venom**.

The installed app opens on `/agents`. A long press on its icon (a right click on desktop) offers shortcuts: a new agent
chat, Computers, Tasks, Notes and Capture a person. It is still the share target for People capture
([Share to Venom](/docs/cloud/people-capture.md#share-to-venom)). An app installed before it opened on Agents updates itself.

The app keeps its shell offline: the Agents page, the app's code and icons, and an offline page. It never keeps a chat,
an answer from the API or anything you typed. With the network down, it shows the Agents page or the offline page and
reconnects when you are back. Signing out drops the saved page.

## Notifications

Turn on **Notifications** at the foot of the sidebar to be told on this device when an agent needs you or finishes
while you are not looking at its chat. Your browser asks for permission first. Turn it on in each browser or phone you
want notified; turn it off there the same way. **Send a test** checks that this device receives them.

You are notified when:

- an agent asks for an approval or asks you a question, and the request is still open;
- an agent finishes a turn.

The same switch serves [Venom Tasks](/docs/cloud/tasks-settings.md#notifications): the service worker also shows Tasks
notifications (assignments, mentions, reminders) on a device subscribed here or in Tasks' settings.

A chat you started from a Venom Tasks issue also reports back in your Tasks Inbox, on that issue: when it finishes,
when it needs you (an approval or a question) and when a quick chat's turn fails. Only you are told, not the issue's
other followers, and also when the chat is open in your browser ([Agent chats from an issue](/docs/cloud/tasks-notifications.md#agent-chats)).
On the issue's **Linked** section every kind of chat, code and computer chats too, shows **needs you** while it waits.

You are not notified about a chat you have open in a browser: you see it there. Each approval, question or finished
turn notifies you once. Tapping the notification opens the chat. The cloud checks your running chats about once a
minute, so a notification can come up to a minute or so after the agent asked.

On an iPhone or iPad, notifications need the app on your Home Screen (iOS 16.4 or later). If the switch is greyed out,
notifications for the site are blocked in the browser's settings.

### What the push service receives

A notification travels through your browser maker's push service (Google's for Chrome, Mozilla's for Firefox, Apple's for
Safari). That service receives the address your browser gave it, your Venom install's public key and contact, and a
message encrypted to your browser that only your browser can read. The message holds the chat's id, the kind
(`needs_you` or `done`) and a fixed title such as "An agent needs you", in your language. It never holds what the
agent said, a file name, a command or your prompt.

When a push service says a device is gone (it was unsubscribed or reset), Venom deletes it. Leaving the organisation
deletes your devices.

### For operators: VAPID keys

Notifications are off until the install has its own VAPID key pair (RFC 8292). Generate one:

```sh
node -e "const e=require('crypto').createECDH('prime256v1');e.generateKeys();console.log('VENOM_PUSH_VAPID_PUBLIC_KEY='+e.getPublicKey('base64url'));console.log('VENOM_PUSH_VAPID_PRIVATE_KEY='+e.getPrivateKey('base64url'))"
```

Set both, plus `VENOM_PUSH_VAPID_SUBJECT` (a `mailto:` address or an `https:` URL a push service can reach you at), in
the cloud's environment. With any of the three unset the switch is hidden and the cloud sends nothing. Keep the keys:
replacing them makes every browser subscribe again. Push is the one outbound call the Agents app adds, and only for
members who turn it on; an air-gapped install has no push service to reach and leaves the keys unset.
