---
title: Get started with Venom Agents
description: "From a connected daemon to your first agent chat: open /agents, pick a new project, a scratch folder or a folder already on the machine, and send a prompt. Nothing to set up on the daemon."
section: agents
order: 2
audience: [user]
sources: [services/go-orchestrator/cmd/venom-daemon/projects.go, services/go-orchestrator/internal/workspaces/workspaces.go, services/nodejs-cloud/components/agents, services/nodejs-cloud/app/(agents), services/nodejs-cloud/lib/agents/index.ts]
features: []
---

This page takes you from nothing to a coding agent working in one of your repositories, driven from a browser. You need:

- a Venom Cloud organisation on the Team plan or above, or one where Venom Agents is in preview ([Plans and the add-on](/docs/agents/plans.md));
- a role that can start chats: owner, admin or developer ([Who can do what](/docs/agents.md#who-can-do-what));
- the [desktop daemon](/docs/deploy/desktop-daemon.md) on the machine that holds your code, connected to the organisation.

## 1. Open Agents and pick where it works {#open}

There is nothing to set up on the daemon: once it is connected, it can run a coding agent. Open `/agents` in the console,
or **Agents** on the rail (`g g`). The prompt box in the middle of the page has three pickers:

- **Where**, under the daemon's name:
  - **New project…**: type a name, and optionally an `https://` repository to clone. The daemon makes the folder and
    keeps it for later chats. A private repository uses the git login already on the daemon's machine; leave tokens out
    of the URL.
  - **Scratch (discarded with the chat)**: an empty folder for this chat only, deleted when you archive the chat.
  - a project already there: one you made before, or a folder the daemon's owner added.

  If the daemon is not there, the app says why: no daemon is connected, the daemon is offline, or it is too old (update
  the desktop daemon).
- **Model**: the organisation's default, or one of its [gears](/docs/cloud/console-gears.md).
- **Mode**: **Ask before acting** is the default. The agent reads freely and asks before it edits or runs anything your
  rules don't allow ([The Agents app](/docs/agents/app.md#start-a-chat) lists the modes).

## 2. Send a prompt {#prompt}

Type what you want, for example "Find why the login test is flaky and fix it", and press `Enter` (`Shift+Enter` for a
new line). The chat opens at its own address, `/agents/c/{id}`, and the answer streams in. When the agent asks to run a
command or edit a file, answer with the buttons in the stream. After a turn that changed files, open **Changed N files**
for the diffs.

While it works you can steer it (**Send**), queue a message for after the turn (**After this turn**) or stop it (`Esc`).
[The Agents app](/docs/agents/app.md) covers the rest of the chat.

## On your phone {#phone}

The app works in a phone's browser: one column, with your chats in a drawer behind the menu button. You can also install
Venom as an app on your phone or computer and turn on notifications, so you hear when an agent needs an answer or
finishes. Notifications are opt-in on each device, and they say only which chat and why, never what the agent wrote.
[The Agents app](/docs/agents/app.md) shows how to install it and what a notification contains.

## Work in a folder already on the machine {#project}

To work in an existing repository on the daemon's machine, add its folder there:

```bash
venom-daemon projects add ~/code/my-app
```

Or open the daemon's dashboard, go to **Local models** and add the folder on the **Projects** card. Add a folder that
holds several repositories (`~/code`) and each git repository directly inside it is offered as its own project, with its
branch. Only the folders you add and the daemon's workspaces are served, never the rest of your home folder.
[Projects on the desktop daemon](/docs/deploy/projects.md) has the details.

## A computer chat instead {#computer}

To give an agent a browser rather than a repository, pick one of your [computers](/docs/computers.md) under **Where**.
A computer chat needs no project. See [Computer chats](/docs/agents/computer-chats.md).

## If something goes wrong {#troubleshooting}

| What you see | What to do |
|---|---|
| "Add Venom Agents to your plan" | The organisation does not have the add-on. An owner or billing member adds it under Settings → Billing ([Plans and the add-on](/docs/agents/plans.md)). |
| No daemon in the picker | Check the daemon is online on the console's daemon list. |
| No New project… or Scratch under the daemon | The daemon is too old to make workspaces: update the desktop daemon. |
| The daemon is named as too old | Update the desktop daemon; its `venom serve` must list projects (`GET /v1/projects`). |
| "git clone failed" | Check the URL. For a private repository, log in to git on the daemon's machine first (for example `gh auth setup-git`). |
| "This chat's session has ended" | The daemon restarted or the folder was removed. Start a new chat. |
| Your role cannot start chats | Billing and viewer members can't. Ask an owner or admin to change your role. |
