Skip to content
Docs0.9GitHubInstall

Running itProject machines

Project machines

A project can run its agents in a machine: one container per project, on a private clone of the project, never your checkout. Everything Vendetta does with an agent works for a machine’s agents too: the chooser, the CLI, schedules, Telegram, Discord, and the apps. Projects stay local unless you list them.

Inside, Claude Code runs with bypassPermissions: it never asks for approval, and the container is the boundary. It uses your Claude login through the Claude proxy, and git to your git hosts uses your git login: no token is ever inside the machine.

# ~/.config/vendetta/config.toml
[machines]
runtime = "docker"          # or "podman"
memory = "2g"
[plugins.claude-proxy]      # your Claude login for every machine, without a copy
vendetta machine project add --existing ~/projects/groceries  # or --new NAME, --clone URL

project add gets the image when it is missing or older than this install, clones the project into the machine’s folder, creates its volumes and container, and starts it. The apps do the same from a project’s settings (“Run in a container”) and “New container project”. Then start agents in groceries as usual. Each one runs inside the machine. The project’s Agents window gets one pane attached to the machine’s own tmux, and selecting an agent shows it there.

Which projects run in a machine is the worker’s list, machines/projects.json in the state directory, changed only through vendetta machine project and the apps:

Command Does
vendetta machine project add --existing DIR DIR’s git repository. A folder that is not one is refused unless --make-git, which runs git init and commits what is there.
vendetta machine project add --new NAME An empty repository with one commit in [machines] checkouts/NAME.
vendetta machine project add --clone URL [NAME] git clone URL there, with your git credentials.
vendetta machine project remove NAME [--delete-folder] Lists what goes, then removes the container, its volumes, and its clone, and the project’s folder when Vendetta made it (--new or --clone); a folder you brought (--existing) stays unless --delete-folder. Before you confirm it warns, plainly, of work that would be lost: uncommitted changes and commits on no remote in a folder that goes, and the machine’s uncommitted changes and unfetched branches. Shares of it end first. From the apps, its conversations, each listed, go too, with their chats and topics.
vendetta machine project list The container projects as JSON.

The admin adds --instance PERSON to these and to start, stop, recreate, fetch, and update: that person’s Vendetta does it as them, and the steps show here.

Each step checks before it acts (config, image, clone, claude, create, restart, ready), so running a command that failed again finishes it. claude makes the machine’s Claude proxy folder, in an instance by asking the admin’s proxy; it fails claude_unavailable with the proxy’s reason. With Podman, add enables podman-restart.service for you, so machines come back after a reboot.

Key Default Meaning
[machines] runtime "docker" docker (rootful) or podman (rootless).
[machines] runtime_path found on PATH The runtime’s CLI.
[machines] image "vendetta-machine" Local image name; builds are tagged with the Vendetta version, pulls with the commit.
[machines] registry "git.example.dev/example/vendetta-machine" Where CI publishes the image as :latest. "" builds it locally.
[machines] memory "2g" Each machine’s memory limit. A machine is never unlimited. Each idle Claude takes about 200 MiB.
[machines] prefix "vendetta-" Prefix of container and volume names.
[machines] claude_proxy "socket" How Claude reaches the Claude proxy: socket, or token for a Claude version whose socket mode broke.
[machines] checkouts "~/projects" Where new and cloned container projects are made.
[machines] instructions "" Instructions every agent in your container projects and people’s follows, as Claude’s managed CLAUDE.md (read-only at /etc/claude-code). A change reaches each machine’s next session, people’s after vendetta instance update. A machine made before this setting existed needs recreate once. A person’s Master gets none.

A name is typed as you like: capitals, spaces, and other characters fold into the machine’s name, a-z 0-9 _ . -, lowercase, with one - for each run of anything else, trimmed, at most 63 (Test 626 becomes test-626). A new or cloned project’s folder takes the folded name, so folder and machine match; an existing folder keeps its own name (~/projects/MyApp runs as myapp). Refused only when nothing usable is left, when it folds to one of Vendetta’s own names or the Master’s project, or when another container project already has it, which the refusal names.

Command Does
vendetta machine image build Gets this install’s image.
vendetta machine image build --local [--claude VERSION] Builds it here with this install’s Vendetta.
vendetta machine image refresh Gets it again when this install’s differs from the last one (keeping a pinned Claude), and recreates stopped machines onto it; running ones are named, never stopped.
vendetta machine create NAME For a listed project: clones the repo, creates the volumes, and starts the container.
vendetta machine start NAME / stop NAME Stopping ends every agent; they show as exited and resume later.
vendetta machine recreate NAME [--stop] Moves a stopped machine onto the current image, keeping its login, history, and clone.
vendetta machine remove NAME [--purge [--force]] Removes the container. --purge also deletes its volumes (login, transcripts, history) and the clone; branches not yet fetched need --force.
vendetta machine status [NAME] [--json] State, image (current only when it is what this install builds), memory, link, agents, and unfetched branches.
vendetta machine login NAME Runs claude inside, for /login: only for a person with their own Claude account.
vendetta machine fetch NAME Brings the machine’s branches into your repo as refs/remotes/machine/*.
vendetta machine update NAME [REF] Sends your REF (default: your current branch) into the machine.
vendetta machine shell NAME A shell in the clone.

CI builds the image from each push to main that changes what it is built from and publishes one tag, [machines] registry:latest, labeled with its commit and a hash of those sources (integrations/machine/sources.sh). An install pulls it and uses it only when the hash is its own, which install.sh records from a clean checkout. Otherwise it says which commit :latest is and stops: wait for CI and run vendetta machine image refresh, or build it here with vendetta machine image build --local, which an install of an unpushed commit or uncommitted changes, or a change to integrations/machine/, needs.

These always build locally: token mode, a pinned --claude, Docker as a user other than 1000, and registry = "".

The claude-proxy plugin serves your Claude login to every machine without copying it. Each machine gets its own Unix socket, mounted at /run/vendetta-claude (from ~/.local/state/vendetta/machines/NAME/claude). Claude inside runs its native socket mode (ANTHROPIC_UNIX_SOCKET, with CLAUDE_CODE_OAUTH_TOKEN=ssh-placeholder and CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1, set in the image), sends no credential, and contacts nothing else. The proxy adds your current token and forwards only Claude’s model requests (/v1/messages, count_tokens, /v1/models, and your account’s policy) to Anthropic, streamed. Everything else is refused.

  • Agents in a machine use your plan’s limits, and the proxy counts what each machine used, but they never see your token.
  • Only Claude refreshes your login. When it is about to expire and no Claude of yours is running, the proxy runs your claude auth status, which refreshes it. If that fails, machines’ Claude says your login is unavailable: run /login in your own Claude.
  • vendetta claude-proxy status shows the login’s expiry and each machine’s state, last use, requests, and tokens. The apps show the same in Settings.
  • A machine made before the proxy keeps its old /login until you run vendetta machine recreate NAME --stop, which also deletes that copy.
  • machine image build checks that the image’s Claude still works with the proxy: its Claude, with no network, must answer through a stand-in socket. If a Claude version breaks socket mode, the build fails and says so. Build with an older --claude, or set [machines] claude_proxy = "token", where Claude sends a fixed dummy token to a forwarder inside the machine, which relays it to the same socket. In token mode Claude does not fetch your account’s policy.
  • Unix socket paths are at most 107 bytes: keep XDG_STATE_HOME short.

Git to github.com uses your own GitHub when you connect it (plugins): the machine’s /run/vendetta-providers holds your providers’ sockets and gitconfig, which the image’s /etc/gitconfig includes; the token stays on the host.

With [plugins.claude-proxy.git] (see plugins), the same plugin serves your git login for the hosts it lists. Each machine’s folder gets git.sock and a gitconfig, which the image’s /etc/gitconfig includes. It rewrites each host’s https://HOST/, ssh://git@HOST/, and git@HOST: remotes to http://vendetta-git/HOST/, reached through git.sock as a SOCKS proxy. The proxy adds your token and forwards only git’s clone, fetch, and push (smart HTTP) to https://HOST. Everything else is refused, Git LFS included.

  • Agents in a machine clone, fetch, and push every repo your login can, as you. A host with push = false takes clones and fetches only.
  • A machine made with the git login has its clone’s origin set to your repo’s own remote when that remote is on one of the hosts, so agents can git push origin. An older machine’s origin stays your repo’s path.
  • vendetta claude-proxy status counts each machine’s git requests and refusals.
  • Without the plugin’s git table, git in a machine has no login, as before.

A machine’s Claude loads the plugin of what you pick for your container projects (or what the admin picks for the person whose machine it is), from /run/vendetta-claude/shared (plugins): shared servers run on the host, never inside. A machine’s own skill or server of the same name wins: the shared one is left out of that machine. A machine made before this gets it at recreate.

What agents add themselves stays when the machine is recreated: claude mcp add (user and local scope), ~/.claude/skills, and installed plugins live in the Claude volume, and ~/.local/share is a volume of its own (NAME-tools), where uv, pipx, and npm put the tools their servers need. remove --purge deletes all three.

Agents commit on the clone, at ~/.local/state/vendetta/machines/NAME/NAME. fetch copies its branches into your repo under refs/remotes/machine/, without tags. update hands the machine a bundle of your branch, and the machine fetches it from there.

The clone belongs to the container. Anything that runs git in it, or reads its config, can run what the container put there (core.fsmonitor, hooks). Vendetta only fetches from it and never runs anything inside it. Do not cd into it on the host: a shell prompt that shows git status is enough.

Debian, tmux, git, a pinned Claude Code with its autoupdater off, and Vendetta’s worker and tmux host, all root’s in /usr/local/bin. The worker runs inside with the Claude Mod. There is no sudo, so agents cannot become root inside.

There is no boundary inside a machine. Every agent there runs as the same user, in bypass mode: any one of them can act as any other, and as the machine’s worker, and use your Claude limits through the proxy’s socket. The boundary is the container’s edge. The host treats everything a machine says as untrusted, names only that machine’s agents with its keys, and never opens a path of the machine’s. The container gets the clone, three volumes (Claude’s config, Vendetta’s state, and installed tools), its Claude proxy socket, and nothing else of the host: no Docker socket, no runtime directory, no published ports. Its network reaches the internet.

Docker Podman
For your own machines yours, and people’s, which run only in Podman
Files in the clone yours (the image’s user is your uid) yours (--userns=keep-id)
Who controls machines the docker group, which is root-equivalent you alone
After a crash restarted restarted
After a reboot restarted by dockerd restarted only with linger and systemctl --user enable podman-restart.service
Memory limit always needs the memory controller delegated to the user (systemd’s default)
Runtime state dockerd’s under /run/user/UID, whatever XDG_RUNTIME_DIR says

People’s machines run in your rootless Podman, named vendetta.NAME.PROJECT and labelled with the person; each person’s Vendetta acts only on its own. [people] sets their machines’ memory, CPUs, processes, and how many each may have (people). A machine sees only its own clone, volumes, and Claude proxy socket: never another’s, a worker’s socket, or your files.

  • Teams stay on one side. A manager inside a machine leads members in that machine. A host manager cannot have machine members, nor the other way.
  • No Master, no session profiles, and only providers the image has (Claude).
  • A project file in the clone runs its agents and teams in the machine, trusted from the host.
  • No terminal placement: machine agents always run in the machine’s tmux.
  • The chooser’s preview is read-only; Enter opens the agent. Machine agents and projects carry a machine badge, and a stopped or unreachable machine’s agents show that state, dimmed.
  • A schedule in a machine project starts a new agent in the machine, or with --reuse prompts the conversation its first run started there, resumed once exited and replaced only once the machine no longer has it. An exact --session-id is the host’s only.
  • An agent’s vendetta alert and vendetta timer stay inside its machine, and [auto_delete] deletes the host’s conversations only.
  • vendetta diff works inside a machine: its worker hands the command to the host’s changes plugin, which follows the clone’s branches by fetching from it. A change’s Uncommitted view does not read a machine’s work tree.
  • Telegram, Discord, and the apps send a machine agent photos and text, not documents. A page its reply links is copied from the machine as NAME--page.
  • A stopped machine’s conversations show as exited. Resuming one, or starting an agent in the project, starts the machine.
  • When its link is down, its agents keep their last state, marked unreachable, and refuse input until it is back. Nothing is queued or repeated.