VeloxSaarthi

Appearance

Security ​

An honest account of the VeloxSaarthi security model — what is and is not protected, and what you need to know before giving the agent credentials.

Bootstrap credentials ​

VeloxSaarthi's own infrastructure credentials (ADO_PAT, TELEGRAM_BOT_TOKEN, TELEGRAM_GROUP_CHAT_ID, and the Anthropic API key) live in host environment variables only. They are never passed through any agent channel, never stored in state.db, and never visible to the LLM.

This is the bootstrap-creds rule: provider/infrastructure credentials belong to host identity, not to the agent.

Credential relay (the plaintext caveat) ​

When an actor needs a credential during a build (e.g., a read-only API token to investigate something), it calls mcp__vlx__RequestCredential(name, operation, justification) via the MCP bridge.

What actually happens:

  1. The MCP bridge posts the request to the story's Telegram thread.
  2. You type the credential into the Telegram reply.
  3. The orchestrator persists your reply in clarifications.answer in plaintext in state.db.
  4. The credential is delivered into the resumed agent session as the next user message — it appears in the agent's conversation transcript.

No secret store in v0

There is no encryption, no capability broker, and no pino redaction in the current version. A credential provided this way:

  • Sits unencrypted in state.db.
  • Appears in the agent's ACP session transcript (stored in ~/.claude/projects/<project>/<session-id>.jsonl).
  • Can leak through logs, commit messages, PR descriptions, error dumps, or any tool the agent calls.

Practical guidance:

  • Use RequestCredential only for low-value, short-lived, or easily-rotated credentials.
  • Provision least-privilege only: read-only tokens, Reader roles, read-only replicas.
  • Rotate after use when in doubt.
  • Do not provide production database passwords, signing keys, or any credential whose compromise has broad impact.

Future work: An encrypted secret store (AES-256-GCM, host master key) plus a brokered capability model was implemented but never wired into any live path and was removed rather than left as false assurance. If agent-access credentials become a recurring need, the proper fix is to re-introduce the brokered model end-to-end (VLX-012b), not to use the current plaintext path for sensitive values.

Egress model ​

The agent runs inside an ACP subprocess on the host machine. It does not run in a Docker container or any network sandbox by default.

Network calls made by the agent are subject to the permissions.allowed_hosts list in vlx.yaml. Calls to hosts not in the list are posted to Telegram for a one-tap approve/deny. Deny propagates as a stage failure.

No egress enforcement at the network layer

allowed_hosts is an advisory allowlist enforced by the ACP permission classifier, not by iptables or a network sandbox. A compromised package or skill could make calls that bypass the classifier. Treat the permission gating as an audit + friction layer, not a hard guarantee.

For sensitive projects, consider running the daemon on an isolated VM with an outbound firewall configured independently of VeloxSaarthi.

Agent-brain PR gate ​

The agent cannot modify the agent brain directly. The correction flow is:

  1. Reflector produces reflection.json with proposed_corrections[].
  2. The deterministic extractor (src/core/brain/extract-corrections.ts) filters to corrections tied to ground-truth signals.
  3. A [brain] PR is opened against the VeloxSaarthi repo.
  4. Vinit reviews and merges. Nothing lands in agent-brain/CLAUDE.md without a human PR review.

This gate prevents runaway self-modification. The agent cannot promote bad corrections by bypassing the review step.

Branch namespace ​

The agent pushes only to branches matching vlx-bot/<storyId>. The worktree manager and the SCM adapter refuse to operate on branches outside this namespace. Human-pushed branches are never touched.

ACP session isolation ​

Each pipeline stage starts a fresh ACP session with the appropriate actor's system prompt. Sessions are not reused across stages — cross-stage handoff is via committed artifacts (spec.md, plan.md, etc.). A compromised or misbehaving stage session cannot affect other stages directly.

Permission classifier categories ​

The ACP permission handler auto-approves these operation classes:

  • File reads/writes within the run's worktree.
  • bun test, bun install (with allowed_registries check).
  • Git operations on vlx-bot/ branches.
  • Reads of spec.md, plan.md, and project memory files.
  • gstack skill invocations.

The following route to Telegram for one-tap approval (or auto-deny on timeout):

  • Network calls to hosts not in allowed_hosts.
  • Package installs from registries not in allowed_registries.
  • git push without an explicit vlx-bot/* refspec.
  • File writes outside the worktree.

What VeloxSaarthi does NOT manage ​

  • Project (application) secrets — the built app's own runtime config (DB credentials, app API keys, etc.). These are loaded by the project's own startup scripts. VeloxSaarthi does not know about them.
  • Anthropic API key — held in host environment by the claude-agent-acp subprocess, not injected by VeloxSaarthi.

Internal Veloxcore tool — not a public product.