Environment & Limits

GitHub API usage, rate limits, environmental considerations. Updated: April 2025.

GITHUB API USAGE

How Vant interacts with GitHub APIs.

What Vant Uses

When configured with GitHub sync, Vant interacts with:

API	Purpose	Method
Repositories	Brain storage	GET, POST, PUT
Contents	File read/write	GET, PUT
Commits	Version history	GET, POST
Branches	Isolation	GET, POST
Git Data	Sync operations	GET, POST

Not Used

Vant does NOT use:

Issues (for storage)
Pull requests (as data)
Wiki (as storage)
Releases (for storage)
Projects (as database)

Rate Limits

GitHub API has rate limits:

Plan	Requests/Hour	Burst
Unauthenticated	60	60
Authenticated	5,000	5,000
GitHub Actions	1,000	1,000

Source: GitHub Rate Limits

Token Scopes

Recommended minimal scopes:

repo
  - repo:status    (check)
  - repo_deployment (read)

Avoid:

admin:org
delete_repo
write:discussion

POLLING CONSIDERATIONS

Timing and rate limit details.

GitHub.com ToS Prohibition

Automated polling of GitHub.com is prohibited. Self-hosted GitLab/Gitea is fine.

“Using GitHub as a database or for purposes unrelated to source code management.” — GitHub Acceptable Use Policies

What This Means

Allowed	Not Allowed
Manual sync (`vant sync`)	Polling every N seconds
`git clone/fetch`	Checking every minute
On-demand sync	Scheduled background sync
User-initiated	Automated by default

Vant’s Approach

Vant defaults to:

Manual sync — Run vant sync when you want
No polling — Must explicitly opt-in
Opt-in warnings — Clear GitHub ToS warnings
Two confirmations — Env var OR stdin

DATA CONSIDERATIONS

How your data is handled.

What Gets Synced

Your brain files:

Memory files (models/public/*.md)
Configuration (non-secret)
Settings

NOT synced:

.env files (gitignored)
Tokens
Local state
Cache files

Repository Size

GitHub soft limit: 1GB per repo GitHub hard limit: 2GB per repo

Best practices:

Keep brain files concise
Don’t commit binaries
Use .gitignore

See: GitHub Large Files

Privacy

Your brain is:

Stored on YOUR GitHub account
Visible to who you share with
Public or private - YOUR choice

TOKEN SECURITY

Keeping your GitHub token safe.

Best Practices

Use Fine-Grained Tokens
- Created October 2022+
- Minimum permissions
- Expiration dates
Rotate Regularly
- Every 90 days
- After suspicious activity
- When leaving organization
Never Commit
- Add .env to .gitignore
- Don’t paste in issues
- Don’t share in chat

Use .env Files

# .env (gitignored)
VANT_GITHUB_TOKEN=ghp_xxxx

Token Exposure

If exposed:

Immediate: Revoke token
- GitHub → Settings → Developer → Tokens
- Or: Settings → Tokens (classic)
Check Audit Log
- GitHub → Settings → Audit log
- Look for suspicious activity
Generate New
- Minimal scopes only
- Set expiration
Update Vant
- Update .env
- Restart node

SYSTEM REQUIREMENTS

What you need to run Vant.

Minimum

Resource	Requirement
Node.js	18+
RAM	512MB
Disk	100MB
Git	2.x

Resource	Requirement
Node.js	20+
RAM	1GB
Disk	500MB
Git	2.x

Dependencies

Vant uses:

express - HTTP server
chalk - Terminal colors
cli-progress - Progress bars
inquirer - Interactive prompts
yaml - YAML parsing
And ~30 other packages

NETWORK CONSIDERATIONS

Network requirements and behavior.

Ports Used

Port	Service
3456	MCP server (default)
3457	MCP alt port
443	HTTPS (GitHub)

Firewall Rules

For MCP server:

# Allow local only
ufw allow from 127.0.0.1 port 3456

# Or specific IPs
ufw allow from 192.168.1.0/24 port 3456

Proxy Support

Set HTTP proxy:

export HTTP_PROXY=http://proxy:8080
export HTTPS_PROXY=http://proxy:8080

ENVIRONMENT VARIABLES

Configuration via environment.

Required

Variable	Purpose
None	Works standalone

Optional

Variable	Purpose
`VANT_GITHUB_TOKEN`	GitHub sync
`VANT_GITHUB_REPO`	Repository
`VANT_MCP_PORT`	MCP port
`VANT_AGREE_AUTO_SYNC`	Opt-in polling

Security

Store in .env (gitignored)
Never in code
Never in logs

ERROR HANDLING

How errors are managed.

Common Errors

Error	Cause	Fix
`401`	Bad token	Regenerate token
`403`	No permission	Check scopes
`404`	No repo	Create or check
`429`	Rate limit	Wait, reduce sync
`500`	GitHub	Check status

Recovery

Token issues: Regenerate, update .env
Rate limit: Wait 1 hour, use manual sync
GitHub down: Use offline, wait
Conflict: Pull rebase or merge manually

LIMITATIONS

Known limitations and workarounds.

Vant Limitations

Single brain per instance
No built-in encryption
Git-based sync only
No multi-user auth

GitHub Limitations

Not a database
Not for real-time apps
Rate limited
Can revoke access

Alternative Backends

Future support (not implemented):

GitLab
Gitea
Self-hosted Git
File system only

MONITORING

Tracking Vant health and activity.

Local Monitoring

Monitor Vant health locally.

# Check resource usage
top
htop

# Check Node processes
ps aux | grep node

# Check disk usage
du -sh models/public/

GitHub Monitoring

Tokens: Settings → Developer → Tokens
Audit Log: Settings → Audit log
Usage: Settings → Repositories

COMPLIANCE CHECKLIST

Before using Vant with GitHub: