Running your own agent
One of the two ways a filed piece of feedback becomes a change — see Feedback to fix for the other.
An agent you run
Section titled “An agent you run”You can run an agent on your own machine that connects to your workspace, receives feedback the moment it’s filed, works the problem with a coding assistant, and streams the result back into the conversation.
To wire one up, provision a token: API tokens → New token, with the
platform:dispatch scope. The raw token is shown exactly once, on
the page right after you create it — there’s no way to recover it
later, only to revoke and issue a new one. Put it in the agent’s
environment.
Once it’s connected, a Dispatch card on your Dashboard and on the API tokens page shows live status: online with the age of its last heartbeat and what it’s currently doing, or “Not connected”. The agent pings every 20 seconds, and the card polls, so you can see it drop without refreshing.
What you see in the conversation while it works: progress chips as the agent uses tools, and its replies as normal messages. A reply can carry a proposed code change, which renders as a badge with a summary and how the change is routed — “quick fix” when it will commit to the base branch, “PR” when it will open a pull request for review. Hovering tells you why it chose that: the file count, the line count, or a path you’ve marked as always-reviewed. That routing is your ship policy, not the agent’s decision.
Applying a proposal isn’t a workspace control today — the badge tells you one was made and what would happen to it.
Revoking the token cuts the agent off on its next reconnect.
The same agent also sits in a room of its own, so you can ask it questions directly instead of only through a feedback ticket — see Code agents.
Installing one
Section titled “Installing one”The agent is open source at VroxyAI/vroxy, the same repository as the CLI and the same one-line installer:
curl -fsSL https://raw.githubusercontent.com/VroxyAI/vroxy/main/install.sh | bashSay yes when it asks about a dispatch agent and it walks you through
the rest: the workspace host, the platform:dispatch token from above,
and which checkout on this machine the agent may work in. It
confirms the workspace by name before wiring anything to it —
installing an agent against the wrong token is the kind of mistake you
find a week later in somebody else’s rooms.
It installs a systemd unit, so the agent comes back after a reboot and you can manage it the usual way:
./install.sh --dispatch # add another workspace to this machine./install.sh --list # what's installed, and whether it's up./install.sh --update # pull, reinstall deps, restart everything./install.sh --remove ID # stop, disable and forget one instanceOne process per workspace. The channel streams for exactly one workspace, so running agents for two of them is two units rather than one process holding two connections — which is why adding the second costs one environment file and no extra configuration.
It needs Python 3.9+, git, and whichever coding CLI you want it to
drive (Claude Code or Codex).
Several agents on one machine
Section titled “Several agents on one machine”A single machine can run several agents — each its own process, its own room, and its own @-mentionable name in the workspace. That’s how one workspace gets an agent for its backend and another for its frontend, each answering only its own room.
If what you want is one agent across several checkouts rather than several agents, see a checkout per room below — that’s usually the lighter answer on a machine that keeps a checkout per branch.
Every instance is a separate systemd unit
(vroxy-dispatch@<id>.service) with its own environment file at
/etc/vroxy-dispatch/<id>.env. Two things in that file keep instances
apart:
VROXY_INSTALL_ID— a random id written once at install, and the instance’s identity on the server. Two agents sharing one are the same agent (one room), so never copy one instance’s environment file to make another — run the installer again and let it mint a fresh id.CODE_ROOT/PROJECT— which checkout this instance works in, resolved asCODE_ROOT/PROJECT. Two shapes work: a folder holding several repos (CODE_ROOT=/home/you/code,PROJECT=backend), or a single repo pointed at directly (CODE_ROOT=/home/you/code/backend), which the installer lifts to the parent-plus-name form for you.
Two agents on one box is just the installer twice:
./install.sh --dispatch # agent one → "Backend", /home/you/code + backend./install.sh --dispatch # agent two → "Frontend", /home/you/code + frontend./install.sh --listThe second run notices the workspace already has an agent and offers to
add another under a distinct instance id rather than overwriting it.
Each agent lands in its own room on first connect; mention one by name
(@Frontend) to route a message to it specifically, even in a room
whose default is the other.
A checkout per room
Section titled “A checkout per room”One agent answers every room it’s in, and by default all of them run in the same checkout. On a machine that keeps a separate checkout per branch, that used to mean one agent per checkout. A room can instead pick which checkout it works in, so one agent covers them all.
In any room the agent answers:
/project/project brev81Bare lists where this room works and what else it could, with each
candidate’s current branch. With a name, that room’s next run happens
in that checkout. /cd and /repo do the same thing.
Unlike /harness, typing a bare checkout name is not a switch —
otherwise mentioning brev81 in conversation would move the room.
You decide which checkouts are reachable. The allowlist is
PROJECTS in the agent’s environment file, naming folders under
CODE_ROOT:
CODE_ROOT=/home/you/code/brevitasPROJECT=brevitasPROJECTS=brevitas,brev72true,brev734,brev81Leave PROJECTS out and the agent stays on PROJECT alone, which is
how an agent behaves if you never touch this. PROJECTS=* allows
every git checkout directly under CODE_ROOT. Commas or spaces both
separate names.
Nothing outside that list is reachable — not by a room, and not by the
workspace. Take a name back out and the rooms still pinned to it fall
back to PROJECT rather than staying on a checkout you’ve withdrawn.
./install.sh --doctor tells you if an entry isn’t actually a
checkout, which otherwise just looks like a missing option in the
room.
Two things worth knowing:
- Every room-and-checkout pair keeps its own session. Moving a
room to another checkout and back doesn’t blend what was said about
two different trees.
/resetin a room clears the session for the checkout that room is currently on. - Switching needs no restart and no root. The binding is the agent’s own state, like the harness choice, so a room can move between checkouts mid-conversation.
Waking a sleeping box
Section titled “Waking a sleeping box”A local agent on a machine that isn’t always on can still take work: when the agent is offline, vroxy holds the message and POSTs its Wake URL (set on the agent’s Configure page) to ask the box to start. The held work is sent the moment the agent reports in.
The wake request is a JSON POST:
POST <wake url>X-Vroxy-Wake-Token: <the token you set on the agent>{"agent": "<agent hashid>", "reason": "queued_work"}The URL can front anything that boots the box — a Lambda, a webhook, a Wake-on-LAN trigger; vroxy doesn’t care what’s behind it. A Lambda function URL is authless unless the function checks something, so treat the token as the only thing standing between a stranger and your box — verify it before starting anything.
Boot an EC2 box with the AWS CLI
Section titled “Boot an EC2 box with the AWS CLI”If the agent runs on an EC2 instance, a Lambda that calls
ec2 start-instances is the smallest thing that turns that POST into a
boot. First confirm the instance’s InstanceInitiatedShutdownBehavior
is stop, not terminate, or an OS poweroff destroys the box
instead of stopping it:
aws ec2 describe-instance-attribute \ --instance-id i-0123456789abcdef0 \ --attribute instanceInitiatedShutdownBehaviorCreate an IAM role Lambda can assume, allowed to start only that one instance:
aws iam create-role --role-name vroxy-dispatch-waker \ --assume-role-policy-document '{ "Version": "2012-10-17", "Statement": [{ "Effect": "Allow", "Principal": {"Service": "lambda.amazonaws.com"}, "Action": "sts:AssumeRole" }] }'
aws iam put-role-policy --role-name vroxy-dispatch-waker \ --policy-name start-dispatch-box --policy-document '{ "Version": "2012-10-17", "Statement": [ {"Effect": "Allow", "Action": "ec2:DescribeInstances", "Resource": "*"}, {"Effect": "Allow", "Action": "ec2:StartInstances", "Resource": "arn:aws:ec2:REGION:ACCOUNT:instance/i-0123456789abcdef0"} ] }'
aws iam attach-role-policy --role-name vroxy-dispatch-waker \ --policy-arn arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRoleThe Lambda (boto3 is preinstalled in the Python runtime) checks the
token with a constant-time compare and starts the box only when it is
actually stopped:
import hmacimport jsonimport osimport urllib.request
import boto3
ec2 = boto3.client("ec2")
HEADER = "x-vroxy-wake-token"ALREADY_AWAKE = {"pending", "running"}WEBHOOK_TIMEOUT = 5
def handler(event, _context): expected = os.environ.get("WAKE_TOKEN", "") if not expected: return {"statusCode": 500, "body": json.dumps({"error": "not configured"})}
headers = {k.lower(): v for k, v in (event.get("headers") or {}).items()} if not hmac.compare_digest(headers.get(HEADER, ""), expected): return {"statusCode": 401, "body": json.dumps({"error": "unauthorized"})}
instance_id = os.environ["INSTANCE_ID"] body = _json_body(event) agent = body.get("agent", "") reason = body.get("reason", "")
described = ec2.describe_instances(InstanceIds=[instance_id]) state = described["Reservations"][0]["Instances"][0]["State"]["Name"]
if state in ALREADY_AWAKE: _notify(agent, reason, instance_id, state, started=False) return {"statusCode": 200, "body": json.dumps({"instance_id": instance_id, "state": state, "started": False})} if state != "stopped": _notify(agent, reason, instance_id, state, started=False) return {"statusCode": 409, "body": json.dumps({"instance_id": instance_id, "state": state, "started": False})}
ec2.start_instances(InstanceIds=[instance_id]) _notify(agent, reason, instance_id, "pending", started=True) return {"statusCode": 202, "body": json.dumps({"instance_id": instance_id, "state": "pending", "started": True})}
def _json_body(event): raw = event.get("body") if isinstance(raw, dict): return raw if isinstance(raw, str) and raw: try: return json.loads(raw) except ValueError: return {} return {}
def _notify(agent, reason, instance_id, state, started): url = os.environ.get("WEBHOOK_URL", "") if not url: return action = "boot started" if started else f"already {state}" text = f"vroxy wake: {agent or '?'} ({reason or 'no reason'}) — instance {instance_id} {action}" try: request = urllib.request.Request( url, data=json.dumps({"text": text}).encode(), headers={"Content-Type": "application/json"}, method="POST", ) with urllib.request.urlopen(request, timeout=WEBHOOK_TIMEOUT) as response: response.read() except Exception: passThe WEBHOOK_URL environment variable is optional. When set, the Lambda
posts a one-line {"text": "vroxy wake: …"} to it on every authenticated
call — handy for wiring the wake into a room. Any vroxy incoming webhook
URL (https://<host>/wh/in/<token>) works as the target: the notification
lands as a room message. The post is best-effort and never blocks the
boot, so a dead webhook can’t stop a wake.
Ship and expose it:
zip waker.zip index.py
WAKE_TOKEN="$(openssl rand -hex 24)"
aws lambda create-function \ --function-name vroxy-dispatch-waker \ --runtime python3.12 \ --role arn:aws:iam::ACCOUNT:role/vroxy-dispatch-waker \ --handler index.handler \ --zip-file fileb://waker.zip \ --timeout 15 \ --environment "Variables={INSTANCE_ID=i-0123456789abcdef0,WAKE_TOKEN=$WAKE_TOKEN,WEBHOOK_URL=https://<host>/wh/in/<token>}"
aws lambda create-function-url-config \ --function-name vroxy-dispatch-waker --auth-type NONE
aws lambda add-permission \ --function-name vroxy-dispatch-waker \ --statement-id function-url \ --action lambda:InvokeFunctionUrl \ --principal '*' --function-url-auth-type NONE
aws lambda add-permission \ --function-name vroxy-dispatch-waker \ --statement-id function-url-invoke \ --action lambda:InvokeFunction \ --principal '*' --invoked-via-function-url
aws lambda get-function-url-config \ --function-name vroxy-dispatch-waker --query FunctionUrl --output textBoth add-permission statements are required — since October 2025 a
function URL needs lambda:InvokeFunctionUrl and
lambda:InvokeFunction in its resource-based policy or every request
returns 403 Forbidden, even with NONE auth.
Paste the function URL as the agent’s Wake URL and $WAKE_TOKEN as
the Wake token. Role creation is eventually consistent — if
create-function says the role does not exist, wait a few seconds and
retry. Work is held until the box boots and the agent’s first heartbeat
picks it up — nothing is dropped.
Choosing who dispatch runs as
Section titled “Choosing who dispatch runs as”Because Copilot bills the authorizing account, a workspace has to say which member’s authorization to use. Pick one under GitHub → Dispatch identity. The list offers members who have authorized GitHub; their Copilot seat is the one that pays, and their access decides which repositories are reachable.
Without a designated identity, dispatches started from the browser still run as the person clicking. API dispatches have nobody to run as and are refused — see below.
Dispatching. On a feedback ticket, pick a linked, enabled repo and send it. Vroxy then:
- Opens a GitHub issue in that repo containing the feedback context, filed with the App’s installation token.
- Starts a Copilot agent task on that repo against its base branch, asking for a pull request — using your personal authorization.
- If the agent-task API isn’t available to that account, falls back to assigning the issue to Copilot, which is the same work by a different door.
- Marks the ticket
triaged.
Progress comes back into the feedback’s conversation as messages: when Copilot opens a PR (with the link), when the task completes, when it fails and why, and when it’s waiting on you.
Only one dispatch to the same repo can be in flight for a given ticket at a time — sending it twice tells you it’s already running.
Dispatching without a browser
Section titled “Dispatching without a browser”The same thing works over the REST API, so a script or your own admin can dispatch without anyone opening the workspace:
curl -X POST https://vroxy.ai/api/v1/feedback/<feedback-id>/dispatch \ -H "Authorization: Bearer $VROXY_TOKEN" \ -H "Content-Type: application/json" \ -d '{"repo": "<repo-id>"}'GET /api/v1/repos lists the repositories you can target and reports
dispatch_ready — check that first, because an API token authenticates
a workspace rather than a person, so this path needs a designated
dispatch identity and fails clearly without one.
Then poll GET /api/v1/feedback/<feedback-id> and watch the
dispatches array. The token needs tenant:write.
What leaves your database. The issue body contains the feedback note, the reporter’s label, role and email, the page URL, path and controller#action, the viewport, the ordered list of rendered partials (up to 40), the picked element’s selector, tag, text and the first 400 characters of its outer HTML, and the linked conversation’s title. Screenshots are not sent. Nothing beyond what the feedback page already shows goes to GitHub — but the issue does land in your repo, so treat it as you’d treat any issue your team can read.