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.
Set up
Section titled “Set up”# ~/.config/vendetta/config.toml
[machines]
runtime = "docker" # or "podman"
memory = "2g"[plugins.claude-proxy] # your Claude login for every machine, without a copyvendetta machine project add --existing ~/projects/groceries # or --new NAME, --clone URLproject 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.
Container projects
Section titled “Container projects”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.
Configuration
Section titled “Configuration”| 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.
Commands
Section titled “Commands”| 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. |
The image
Section titled “The image”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 = "".
Your Claude login
Section titled “Your Claude login”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/loginin your own Claude. vendetta claude-proxy statusshows 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
/loginuntil you runvendetta machine recreate NAME --stop, which also deletes that copy. machine image buildchecks 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_HOMEshort.
Your git login
Section titled “Your git login”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 = falsetakes clones and fetches only. - A machine made with the git login has its clone’s
originset to your repo’s own remote when that remote is on one of the hosts, so agents cangit push origin. An older machine’soriginstays your repo’s path. vendetta claude-proxy statuscounts each machine’s git requests and refusals.- Without the plugin’s git table, git in a machine has no login, as before.
Skills and MCP servers
Section titled “Skills and MCP servers”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.
Branches
Section titled “Branches”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.
The image
Section titled “The image”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 or Podman
Section titled “Docker or Podman”| 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.
What differs from local agents
Section titled “What differs from local agents”- 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
--reuseprompts the conversation its first run started there, resumed once exited and replaced only once the machine no longer has it. An exact--session-idis the host’s only. - An agent’s
vendetta alertandvendetta timerstay inside its machine, and[auto_delete]deletes the host’s conversations only. vendetta diffworks 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.