Docs
AI Docs
Crystal Agents
a) GitHub accounts for agents

a) GitHub accounts for agents

#Claude.ai

I’ll read the plan document too before answering.Good, I have a thorough picture of the whole stack now. Here are my answers:

-–

## a) GitHub Account(s) for Agents

**One GitHub account is the right call** — specifically a dedicated machine/bot account separate from your personal one (e.g. crystal-agent-bot). Do not use your personal account for automated pushes.

As for traceability — it is very clear who did what because the workflow is structured, not because of different accounts:

- Every branch is prefixed ai/ and named after the task slug (e.g. ai/fix-navbar-bug)

- Your config/config.json already tracks workspace\_root and github\_repo per run

- The Phase 2 plan stores every run under runs/run\_<date>/manifest.json with step metadata — you can see exactly which agent (developer, devops, tester) handled which step

- Your logs/approvals.jsonl gives you a full audit trail of every approved file write

- The daily report will list all branches created, with token spend per run

The VPS git identity tip at the bottom of your plan doc is spot on — set git config user.name "Crystal Agent" and user.email "crystal-agent@yourdomain.com" globally on the VPS so commits are clearly machine-authored on GitHub’s contribution graph.

-–

## b) PAT for the Agent

**Yes, one Fine-Grained PAT** scoped as tightly as possible. Specifically:

- **Resource owner**: your org or personal account

- **Repository access**: only the 4–5 repos the agent is allowed to touch — not “All repositories”

- **Permissions needed**: Contents: Read \& Write (branch + push), Pull requests: Read \& Write (draft PR creation), Metadata: Read (required baseline)

- **Nothing else** — no Actions, no Secrets, no Admin

Store it as GITHUB\_TOKEN in the VPS environment (e.g. in /etc/environment or the Docker --env-file) and never in config.json. Your Phase 2 plan already calls this out correctly. Rotate it every 90 days — GitHub will email you a reminder.

-–

## c) Workspace Folder & Recommended Workflow

**Yes, a dedicated workspace directory is essential.** Your plan doc already proposes the right structure:


/home/eshwar/crystal-agents/      ← the orchestrator (never edited by agents)

/home/eshwar/workspace/

&#x20;   repo-alpha/

&#x20;   repo-beta/

&#x20;   repo-gamma/

The git.workspace\_root in config.json should point to /home/eshwar/workspace and the CEO router should resolve the specific sub-repo from the task context (your plan already discusses the /task \[RepoName] \[Instructions] pattern).

**Recommended coding workflow for each task:**


1\. PLAN     → CEO agent reads task, identifies repo + scope

2\. BRANCH   → DevOps agent runs git\_ops(action="branch") → ai/<slug>

3\. CODE     → Developer agent edits files via repo\_writer (workspace-relative paths only)

4\. TEST     → Tester agent runs tests (sandboxed, read-only result)

5\. REVIEW   → Reviewer agent checks diff, flags issues back to Developer if needed

6\. PUSH+PR  → DevOps agent commits + pushes ← PAUSES for your Telegram/Dashboard approval

7\. MERGE    → You do this manually on GitHub after reviewing the Draft PR

Steps 6 and 7 are the two human gates. You never let the agent merge to main — that’s your job.

-–

## d) OpenCode on the VPS

**Don’t have the agent launch OpenCode as a GUI.** That approach will cause you pain — OpenCode is an interactive TUI designed for humans, not for programmatic invocation by an agent process.

What you actually want (and what Phase 2 already implements) is better:

- repo\_reader tool reads files into the agent’s context

- repo\_writer tool writes file patches back to disk

- git\_ops tool handles all branch/commit/push/PR operations via subprocess.run

This is fully headless, scriptable, and auditable. The Developer agent produces FILE: <path>\\nCONTENT:\\n<body> blocks (as described in your plan), repo\_writer applies them, and git\_ops handles the rest.

If you want a smarter code-editing capability later, look at integrating **Aider** (a headless AI coding tool) as a tool wrapper — it can be called from Python subprocess with a prompt and a repo path, no UI needed.

-–

## e) Security Guardrails for Antigravity

Here is a concrete checklist to hand to them:

**Secrets management**

- GITHUB\_TOKEN, LLM API keys, and Telegram bot token must live in environment variables or a secrets manager (Doppler, Vault, or at minimum /etc/environment with 600 permissions) — never in any config file or repo

- Add .env, \*.env, and config/secrets\* patterns to .gitignore across all repos

- Enable GitHub’s secret scanning on all repos so accidental commits are caught immediately

**Git / repo guardrails**

- Enable **branch protection rules** on main (and dev if you use it) on every GitHub repo: require PR review, no direct pushes, no force pushes — this makes it structurally impossible for the agent to push to main even if something goes wrong

- The agent’s PAT should have zero ability to delete branches or repos

- \_validate\_workspace() in git\_ops.py must hard-reject any path outside allowed\_script\_roots — Antigravity should write a test that tries a path traversal (../../) and confirms it throws

**Tool permission hardening**

- policy.json must use an allowlist pattern (deny by default, explicitly grant per agent) — confirm Antigravity implements it this way, not a denylist

- The Developer agent should only have repo\_reader, repo\_writer, git\_ops — no web\_search, no crm\_api, no shell exec

- The repo\_writer tool must enforce that all paths are relative to the configured workspace\_root — absolute paths or .. traversals must be rejected at the tool level, not just the agent level

**Execution environment**

- Run agents inside Docker with no host volume mounts except the specific workspace/ directory

- Drop all Linux capabilities except what’s needed; no --privileged

- The container should have no outbound internet access except to your LLM provider API and GitHub API — Antigravity should configure a firewall rule or Docker network policy for this

**Approval gates**

- requires\_approval: true for every git push, PR creation, bulk email, any CRM write, and any database modification — this is already in your plan but make sure it’s in the written spec you give Antigravity

- Approval keys in ApprovalStore should expire (suggest 24 hours) — stale pending approvals should auto-deny, not auto-approve

**Audit & monitoring**

- logs/approvals.jsonl should be append-only (no tool or agent should be able to delete it)

- Set up log rotation but archive, don’t delete

- Add a daily alert if any workflow run ends in an error state without a corresponding approval decision

#ChatGpt

Your documents describe a controlled multi-agent dev system where agents run on the VPS, use Git to create branches, run tests, and open PRs while the human approves the result.

The key design principle throughout the docs is “structured workflows + approval gates + restricted tools” rather than fully autonomous coding agents.

Below are direct answers to your questions with recommended practices.

You should NOT create a GitHub account per agent.

Use one GitHub bot identity.

Example:

github.com/crystal-ai-bot

Reasons:

  1. Simpler credential management
  2. Easier audit logging
  3. Avoids GitHub security flags
  4. Matches how most CI systems operate

Your repo history will still clearly show which agent worked.

Example commit history:

Author: crystal-ai-bot
Commit message:
[Developer-Agent] Implement login validation

Author: crystal-ai-bot
Commit message:
[Tester-Agent] Add login unit tests

Author: crystal-ai-bot
Commit message:
[Reviewer-Agent] Refactor validation logic

You identify the agent via:

commit message prefix
branch naming
PR description

Example branches:

ai/dev/login-validation
ai/test/login-validation
ai/review/login-validation

So no need for multiple GitHub accounts.

b) Should you create a PAT?

Yes.

The VPS worker agents need a GitHub Personal Access Token.

Use a fine-grained PAT with minimum permissions.

Recommended permissions:

Repository access: specific repos only

Permissions:
Contents: Read + Write
Pull Requests: Read + Write
Metadata: Read

Do NOT enable:

Admin
Actions
Secrets
Workflows

Store the PAT in:

.env

Example:

GITHUB_TOKEN=ghp_xxxxxxxxx

And inject it into containers using Docker Compose.

This matches your deployment pattern where secrets are provided via .env and injected into services.

c) Workspace folder and workflow

Yes — create a dedicated workspace directory on the VPS.

Example:

/opt/ai-workspace

Inside:

/opt/ai-workspace
    repos/
        erp-main
        erp-website
        erp-docs

    temp/
        runs/

    artifacts/
        reports/

    logs/

Your agents should never edit repos outside this workspace.

Recommended dev workflow

This is the safest autonomous coding loop.

1. Task created

Telegram:

/task add GST validation to invoice

2. Dev Agent

Actions:

git checkout main
git pull
git checkout -b ai/gst-validation

Then edits code.

3. Tester Agent

Runs:

unit tests
lint
build

Outputs:

test_report.md

4. Reviewer Agent

Checks:

code quality
security
naming
architecture rules

5. Agent pushes branch 

git push origin ai/gst-validation

6. Draft PR created

Title:

AI: GST validation feature

7. Human approval

Telegram:

Approve / Reject

This HITL flow is exactly what your PRD describes.

d) Should opencode run on the VPS?

Yes.

Correct architecture:

Laptop
   ↓
Orchestrator
   ↓
VPS
   ↓
OpenCode / Antigravity agents
   ↓
Git + repo editing

The agent will execute commands like:

git clone
git checkout
edit files
run tests
git commit
git push

This is already implied in your Autonomous Git Workflow design where the VPS worker performs Git operations and opens the PR.

So yes:

Install on VPS:

opencode
python agent runtime
git
docker

The agent will run shell commands to edit code.

e) Critical security guardrails

This is the most important part.

Your Antigravity setup should enforce these controls.

1. File system sandbox

Agents must only access:

/opt/ai-workspace

Never allow:

/etc
/root
/home
/var

Implement:

allowed_paths = ["/opt/ai-workspace"]

2. Tool permission model

Agents must only access specific tools.

Example policy:

Developer agent:

repo_reader
repo_writer
test_runner

Tester agent:

repo_reader
test_runner
coverage_tool

Research agent:

web_search

Never give agents shell unrestricted access.

3. Git approval gates

Agents must NOT:

merge PR
deploy
modify secrets

Require human approval for:

git push
git merge
deploy
database migrations

Your system already includes an approval file and dashboard gate before push/merge actions.

4. Secret isolation

Never allow agents to read .env.

Implement:

.env permissions:
chmod 600

In Docker:

secrets mounted as runtime env vars
not files

Block reading:

.env
config.json
ssh keys

5. Network restrictions

Agents should not call arbitrary URLs.

Allowlist:

github.com
api.openai.com
bedrock.amazonaws.com

Block:

random curl
wget
data exfiltration

6. Token budget guardrail

Limit LLM usage.

Example:

max_tokens: 4096
daily_budget: $5

Your config already supports token limits for this purpose.

7. Command safety filter

Block commands:

rm -rf /
chmod -R
useradd
passwd
iptables

Allow only:

git
python
pytest
npm
dotnet

8. Branch protection

GitHub settings:

Enable:

require PR review
require CI pass
disable direct push to main

Agents should never commit to main.

Recommended final architecture

Laptop
   CEO Router
   Telegram bot
   Orchestrator

        │

        │ Tailscale

        ▼

VPS
   Docker
   OpenCode agents
   Workspace
   Git repos
   Test runners

        │

        ▼

GitHub
   AI branches
   Draft PRs
   Human approval

One important strategic suggestion for your system

Because your core product is a Blazor ERP, configure the reviewer agent with coding standards memory:

memory/coding_standards.md

Include:

Blazor rules
C# naming conventions
MudBlazor patterns
SQL performance rules

This dramatically improves code quality.

If you want, I can also show you something extremely useful next:

The “AI Dev Team Operating System”

It defines:

  • exact agent roles
  • branch naming
  • PR templates
  • review checklist
  • testing pipeline

It turns your system into something very close to a self-running dev team for your ERP.

Crystal Agentic Team - Implementation Roadmap