---
title: Projects on the desktop daemon
description: The folders on your computer that coding agents can work in, from the daemon's dashboard or with venom-daemon projects; the workspaces Venom Cloud makes for chats; nothing else is served.
section: deploy
order: 52
audience: [user, operator]
sources: [docs/daemon.md, services/go-orchestrator/cmd/venom-daemon/projects.go, services/go-orchestrator/internal/daemon/projects.go, services/go-orchestrator/internal/workspaces/workspaces.go, services/nodejs-web/components/daemon/ProjectsCard.tsx, packages/harness-server/src/projects.ts]
features: []
---

A project is a folder on the computer running the [desktop daemon](/docs/deploy/desktop-daemon.md) that your coding agents may open sessions in. The daemon runs `venom serve` on two kinds of folder, so Venom Cloud can start an agent while the code stays on your machine:

- **Workspaces**: folders Venom Cloud makes for chats inside the daemon's own workspaces folder (`~/.venom/daemon/workspaces`). They need no setup here: a chat can start on a daemon you just connected ([Workspaces](#workspaces)).
- **Your project folders**: folders you add, such as an existing repository.

Nothing else is served, never the rest of your home folder.

## Add a folder {#add}

On the dashboard, open **Local models** and find the **Projects** card. Type a path and choose **Add folder**:

- `~/code/my-app` or `code/my-app`: a folder under your home folder.
- `/srv/repos`: an absolute path, as typed.

The daemon checks that the path exists and is a folder (a symlink is stored as the folder it points to). The root of a disk is refused. Up to 50 folders.

From a terminal:

```bash
venom-daemon projects add ~/code/my-app
venom-daemon projects add /srv/repos
venom-daemon projects list
venom-daemon projects remove ~/code/my-app
```

When the daemon is stopped, the change is saved and applies at its next start.

## Workspaces {#workspaces}

From the Agents app (or the `agents_workspace_*` tools), a member makes a workspace on the daemon:

- **A new project**: a named folder, empty (with `git init`) or cloned from an `https://` repository URL. It stays until someone deletes it.
- **Scratch**: a folder for one chat. It is deleted when the chat is archived, and the daemon deletes one that had no change for 7 days in case the cloud could not reach it then.

The cloud only names a workspace; the daemon picks the path, inside its workspaces folder, and refuses a name that could reach outside it. A clone takes https only, at most 2 GiB and 4 minutes, and never asks for a password. Leave credentials out of the URL: a URL with a user or token in it is refused. A public repository just works; a private one uses whatever git login this computer already has (a credential helper, `gh auth setup-git`, the macOS keychain), as `git clone` in your own terminal would. At most 50 named and 30 scratch workspaces per daemon.

You see and delete every workspace: the Projects card lists them under **Workspaces**, marked as made from Venom Cloud, with the repository they were cloned from, and **Delete** removes the folder and everything in it. From a terminal:

```bash
venom-daemon projects list
venom-daemon projects delete my-site
```

A folder you put in the workspaces folder yourself is listed as made by hand; the cloud can open it but not delete it.

## What gets served {#served}

Agents can open a session in a project folder or a workspace, or anywhere below them. The list of projects an agent sees (`GET /v1/projects` on `venom serve`) has the workspaces folder, each folder you added, and the git repositories directly inside them, with the branch each one is on, so adding `~/code` offers every repository in it. It never includes file contents.

Every session still goes through the permission engine, as in the terminal: its mode, your allow, ask and deny rules, your organisation's policy and the sandbox. An agent asks before it edits a file or runs a command unless your rules say otherwise ([Permissions](/docs/security/permissions.md)).

Removing a folder restarts `venom serve`, which ends the sessions running on this daemon at that moment. Nothing in the folder is changed or deleted.

## How it runs {#how}

| | |
|---|---|
| Process | `<install>/bin/venom serve --host 127.0.0.1 --port <port> --root <workspaces> --root <folder>…`, started with the daemon whenever the `venom` CLI is installed with it (0.2.3 and later). Port 8790 when it is free (the last run's port first). |
| Model | This daemon's own orchestrator, with its client key. |
| Token | `server_token` in `secrets.json`, generated once and never printed. |
| Folders | `projects.json` in the daemon's state directory, mode `0600`; workspaces in `workspaces/` (`0700`). |
| Log | `logs/serve.log`. `venom-daemon logs` shows it with the others. |
| Status | `venom-daemon status` prints the serve URL; the Projects card shows Serving or Not running with the reason. |

When the daemon is connected to Venom Cloud, it tells the cloud it can run coding sessions (`serve` in its capabilities) while `venom serve` runs. The orchestrator does not restart when serve does. An older install without the `venom` CLI runs no serve; reinstall the daemon to code from Venom Cloud.

## Admin API {#api}

The dashboard uses the orchestrator's admin API (admin token), on a daemon started by `venom-daemon` only:

| Endpoint | What it does |
|---|---|
| `GET /admin/v1/daemon/projects` | `{folders: [{path, exists}], max, serve: {running, url?, error?}, managed, workspaces?: {root, items: [{id, name, kind, path, origin, created_by?, git_url?, created_at}], scratch_ttl_hours}}`. |
| `POST /admin/v1/daemon/projects` | `{path}`: add a folder, restart `venom serve`, return the list. `400 invalid_project` with the reason. |
| `DELETE /admin/v1/daemon/projects?path=` | Remove a folder and restart `venom serve`. `404 project_not_found`. |
| `DELETE /admin/v1/daemon/projects?workspace=` | Delete a workspace and its files (serve keeps running). `404 workspace_not_found`. |

All of them answer `404 not_managed` on an orchestrator `venom-daemon` did not start.

## Related

- [The desktop daemon](/docs/deploy/desktop-daemon.md)
- [Sessions over HTTP](/docs/server-api/sessions.md): what a client of `venom serve` can do.
- [Permissions](/docs/security/permissions.md)
