Skip to content
Docs menu

Projects on the desktop daemon

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.

View .md

A project is a folder on the computer running the desktop daemon 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).
  • 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

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:

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

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:

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

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).

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

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

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.