Gatevo
A self-hosted gateway between your apps and any AI model. It shows what each AI feature costs and earns, keeps personal data away from the provider, and makes AI agents ask a person before risky actions.
Prompts and answers are never stored: Gatevo keeps only metadata (time, feature, model, tokens, cost, latency, which kinds of data were masked).

Requirements
| PHP | 8.3 or newer, with the extensions bcmath, ctype, curl, dom, fileinfo, json, mbstring, openssl, pdo, tokenizer, xml |
|---|---|
| Database | MySQL 8.0+ or MariaDB 10.6+ (pdo_mysql), or SQLite (pdo_sqlite, nothing to set up) |
| Web server | Apache (cPanel, Plesk), Nginx, LiteSpeed or any host that runs Laravel. HTTPS strongly recommended. |
| Not needed | Node.js, Composer or SSH: the download contains everything prebuilt. |
Installation
Shared hosting (cPanel and similar)
- Create a subdomain, for example
ai.example.com, and set its document root to thepublicfolder of Gatevo (cPanel → Domains → Document Root). - Upload the contents of the
gatevofolder from the download (File Manager → Upload the zip → Extract). - If you want MySQL: create an empty database and a user in cPanel → MySQL Databases. For SQLite skip this step.
- Open
https://ai.example.com. The installer starts on its own:- Requirements: every line should say OK.
- Database: choose MySQL/MariaDB (enter the details) or SQLite.
- Admin account: name, address, language, your login. Tick Load demo data to explore with 30 days of sample traffic; leave it unticked for a clean start.

Step 1: requirements 
Step 2: MySQL/MariaDB or SQLite 
Step 3: admin account, language and demo data - Sign in. The installer locks itself after the first run (
storage/app/installed.json); visiting/installagain shows 404.
VPS (Nginx)
server {
server_name ai.example.com;
root /var/www/gatevo/public;
index index.php;
location / { try_files $uri $uri/ /index.php?$query_string; }
location ~ \.php$ {
include fastcgi_params;
fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
fastcgi_pass unix:/run/php/php8.3-fpm.sock;
# Streaming answers must not be buffered:
fastcgi_buffering off;
}
}
Make storage, bootstrap/cache, database and .env writable by the PHP user (for example chown -R www-data:www-data storage bootstrap/cache database .env).
Behind Cloudflare or a reverse proxy
Most servers put a proxy in front of PHP: Cloudflare, Caddy, Nginx, or the Apache/LiteSpeed proxy of a hosting panel. Two settings in .env make sure every link and redirect stays on https://. Without them, browsers block the sign-in redirect as "mixed content":
APP_URL=https://ai.example.com: when it starts withhttps://, Gatevo builds every link, redirect and asset address with https, whatever the proxy forwards.TRUSTED_PROXIES=127.0.0.1,::1(the default) trusts a proxy running on the same server, such as Caddy or Nginx in front of PHP-FPM or FrankenPHP. If the proxy is on another machine, list its IP or range, for exampleTRUSTED_PROXIES=10.0.0.5. Use*only when the PHP port cannot be reached from the internet.
With Cloudflare, set SSL/TLS to Full (strict), not Flexible. Flexible sends plain http to your server.
After changing .env, run php artisan optimize:clear.
X-Accel-Buffering: no, which Nginx honours. If you put Cloudflare or another proxy in front, streaming still works; only very aggressive buffering proxies delay the chunks.Cron job
One cron entry runs the daily clean-up (old request logs, expired approvals):
* * * * * cd /path/to/gatevo && php artisan schedule:run >> /dev/null 2>&1
In cPanel: Advanced → Cron Jobs → "Once per minute". Gatevo works without it, but logs then grow until you clean them.
First steps
- Providers & models: add a provider (pick a preset such as OpenAI, Anthropic, Gemini or Ollama, paste its API key) and a model. The model's name apps use (for example
smart) is what your code sends; the provider model is the real ID (for examplegpt-5-mini). Enter the prices per 1 million tokens from your provider's price page, then press Test. - Keys: create one key per app or agent. Copy it right away: it is shown only once.
- Quickstart: copy the code for your language and run it. The request appears on Requests within a second.



Connect your apps
Gatevo speaks the OpenAI chat-completions API, so any OpenAI SDK works by changing the base URL and the key:
# Python
from openai import OpenAI
client = OpenAI(base_url="https://ai.example.com/v1", api_key="gk_...")
reply = client.chat.completions.create(
model="smart",
messages=[{"role": "user", "content": "Summarise ticket #8812"}],
extra_headers={"X-Gatevo-Feature": "support-reply", "X-Gatevo-Customer": "acme"},
)
// Node.js
const client = new OpenAI({ baseURL: "https://ai.example.com/v1", apiKey: "gk_..." });
# curl
curl https://ai.example.com/v1/chat/completions \
-H "Authorization: Bearer gk_..." -H "Content-Type: application/json" \
-H "X-Gatevo-Feature: support-reply" \
-d '{"model":"smart","messages":[{"role":"user","content":"Hello"}]}'

Streaming ("stream": true) works the same way. Anthropic SDK users can send the key in x-api-key; requests still use the OpenAI format.
Headers
| Request header | Meaning |
|---|---|
X-Gatevo-Feature | The feature this call serves. Cost and ROI are grouped by it. Without it the call counts as default. |
X-Gatevo-Customer | Optional end-customer ID (falls back to the OpenAI user field). |
| Response header | Meaning |
X-Gatevo-Request-Id | ID of the call (search it on Requests; send it with an outcome to link them). |
X-Gatevo-Cost-Usd | Cost of the call (non-streaming). |
X-Gatevo-Pii-Masked | Kinds of data masked, e.g. EMAIL,PHONE. |
X-Gatevo-Budget | exceeded when the key is over budget in alert mode. |
Cost, budgets and ROI
Cost = prompt tokens × input price + completion tokens × output price (prices per 1M tokens, set per model). When a provider sends no token counts, Gatevo estimates them (about 4 characters per token) and marks the row with "~".
Budgets: each key can have a monthly budget. Stop requests returns HTTP 429 budget_exceeded once it is spent; Allow, but flag keeps working and adds X-Gatevo-Budget: exceeded.
Outcomes: when an AI feature produces something worth money (a ticket closed without an agent, an order placed after a chat), your app reports it:
curl https://ai.example.com/api/v1/outcomes \
-H "Authorization: Bearer gk_..." -H "Content-Type: application/json" \
-d '{"feature":"support-reply","value":4.20,"label":"ticket resolved","request_id":"(optional X-Gatevo-Request-Id)"}'
Features & ROI then shows each feature as profitable, losing (costs more than it returns) or unmeasured (spend but no outcomes). The value you put on an outcome is your business's own estimate: minutes of staff time saved, margin on an order, and so on.


Personal-data shield
Per key, choose:
| Mask | Values are replaced with placeholders such as [EMAIL_1] before the provider sees them, and put back into the answer (also while streaming). The model can still refer to them ("I will email [EMAIL_1]"). |
|---|---|
| Block | Requests that contain such data are refused with HTTP 400 personal_data. |
| Off | No checks. |
Detected: email addresses, phone numbers, card numbers (Luhn-checked), IBANs (checksum-verified), IPv4 addresses, national IDs (Egyptian 14-digit, Gulf 10-digit, US SSN) and secrets (OpenAI/Anthropic-style keys, GitHub tokens, AWS keys, Google API keys, Slack tokens, JWTs).
Injection guard
Checks user, tool and document messages (not your own system prompt) for patterns such as "ignore previous instructions", role-token smuggling, system-prompt extraction, safety bypass, secret exfiltration and markdown-image exfiltration, in English and Arabic. Each rule adds to a score; at the threshold (Settings, default 50) the request is blocked with HTTP 400 prompt_injection in Block mode, or only logged in Flag mode.

Agent approvals
Before an agent does something risky (refund, purchase order, deleting data, changing prices) it asks Gatevo:
POST /api/v1/actions
{ "agent": "support-bot", "action": "refund.create", "amount": 189.00,
"params": {"order": "A-10391"}, "reason": "Damaged item",
"callback_url": "https://your-agent.example.com/gatevo-hook" }
→ 201 {"id": "…", "status": "approved" | "denied", …}
→ 202 {"id": "…", "status": "pending", "expires_at": "…"}
Policies are checked from the lowest priority number up; the first match decides. Patterns use * as a wildcard (refund.*, support-*); optional amount ranges let small refunds pass and hold big ones. When nothing matches, the default decision applies (Settings; "Ask a human" is recommended). The Try it box on the Policies page shows what would happen to an action.

A pending action waits on the Approvals page. The agent either polls GET /api/v1/actions/{id} or receives a signed webhook when a person decides. After acting it reports the result with POST /api/v1/actions/{id}/result {"success": true, "output": "refund r_123"}, which goes into the audit log.

Emergency stop: pause agents for one key (Keys page) or for everything (Settings). Paused agents receive denied with decided_by: "kill_switch". Chat requests keep working.
Webhook signatures
Each callback is a JSON POST with X-Gatevo-Timestamp and X-Gatevo-Signature: sha256=<hex>, where the hex is HMAC-SHA256 of timestamp + "." + raw body with the secret from Settings. Verify it and reject old timestamps:
// PHP
$expected = 'sha256='.hash_hmac('sha256', $_SERVER['HTTP_X_GATEVO_TIMESTAMP'].'.'.file_get_contents('php://input'), $secret);
$ok = hash_equals($expected, $_SERVER['HTTP_X_GATEVO_SIGNATURE'] ?? '')
&& abs(time() - (int) $_SERVER['HTTP_X_GATEVO_TIMESTAMP']) < 300;
# Python
import hmac, hashlib, time
expected = "sha256=" + hmac.new(secret.encode(), f"{ts}.{raw_body}".encode(), hashlib.sha256).hexdigest()
ok = hmac.compare_digest(expected, signature) and abs(time.time() - int(ts)) < 300
// Node.js
const expected = "sha256=" + crypto.createHmac("sha256", secret).update(`${ts}.${rawBody}`).digest("hex");
const ok = crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature)) && Math.abs(Date.now()/1000 - ts) < 300;
Audit log
Every block, agent action, decision, and change to keys, providers, models, policies and settings is recorded. Each entry stores the SHA-256 fingerprint of the previous one. Verify chain recomputes every fingerprint and shows the first row that was edited or deleted outside Gatevo. Export CSV downloads the full log for auditors. The audit log is never pruned.

Settings
| When no policy matches | Default decision for agent actions (recommended: ask a human). |
|---|---|
| Approvals expire after | Hours before an undecided action becomes expired. |
| Injection block threshold | 10–100; lower blocks more. 50 suits most apps. |
| Keep request logs for | Days of request history kept (the audit log is always kept). |
| Webhook signing secret | Created at installation; rotate it any time. |
| Rate limit | GATEVO_RATE_PER_MINUTE in .env (default 600 requests per minute per key). |

Languages
Gatevo ships in English and Arabic (right-to-left). Switch from the sidebar or the login page. To add a language, copy lang/ar.json to lang/xx.json (two-letter code), translate the values and keep words starting with ":" (like :name) unchanged. It appears in the switcher automatically. For server messages (validation), also copy the lang/ar folder to lang/xx.

API reference
| Endpoint | Purpose |
|---|---|
POST /v1/chat/completions | OpenAI-compatible chat, streaming or not |
GET /v1/models | Models this key may use |
POST /api/v1/outcomes | {feature, value, label?, request_id?, customer?} |
POST /api/v1/actions | {agent, action, amount?, params?, reason?, callback_url?} |
GET /api/v1/actions/{id} | Status of an action |
POST /api/v1/actions/{id}/result | {success, output?} for approved actions |
Authentication: Authorization: Bearer gk_… or x-api-key: gk_…. Errors use the OpenAI shape {"error": {"message", "type", "code"}}:
| Code | HTTP | Meaning |
|---|---|---|
invalid_api_key / key_disabled | 401 / 403 | Wrong or disabled Gatevo key |
model_not_found / model_not_allowed | 404 / 403 | Unknown model name, or not allowed for this key |
budget_exceeded | 429 | Monthly budget used (hard-stop mode) |
personal_data / prompt_injection | 400 | Blocked by the shield or the guard |
upstream_error | provider's code or 502 | The provider refused or could not be reached; its message is passed on |
Security notes
- Gatevo keys are stored as SHA-256 hashes; provider API keys are encrypted with your
APP_KEY. Keep.envprivate and backed up. - There is no public sign-up: only the account created at installation can sign in. Two-factor authentication and passkeys are available under your profile → Security.
- Point the web root at
public/, never at the project folder. - The injection guard and data shield reduce risk; they do not replace least-privilege design. Give agents only the tools they need.

Updating
- Back up the database and
.env. - Upload the new files over the old ones, keeping
.envandstorage/. - Run
php artisan migrate --force(or ask your host), thenphp artisan optimize:clear.
Troubleshooting
| Blank page or 500 error | Check storage/logs/laravel.log. Usually storage or bootstrap/cache is not writable. |
|---|---|
| The installer does not open | The document root must be the public folder. Check that .env could be created (folder writable). |
| Test on a model fails | The message shows the provider's own error: wrong key, wrong model ID, or the server cannot reach the provider (firewall, local Ollama on another machine). |
| Streaming arrives all at once | A proxy buffers the response. On Nginx add fastcgi_buffering off;; on Apache with mod_deflate, exclude text/event-stream. |
| Sign-in loops, a blank page after login, or a "mixed content" error | The site is behind a proxy and links come out as http://. Set APP_URL to your https:// address, check TRUSTED_PROXIES (see Behind Cloudflare or a reverse proxy), then run php artisan optimize:clear. |
| "Requires more credits" (OpenRouter) | When the app does not send max_tokens, OpenRouter reserves a large output budget and refuses accounts with little credit. Send a sensible max_tokens or add credit. |
Empty answer with finish_reason: length | Some models spend tokens on internal reasoning before answering. Raise max_tokens. |
| "The AI provider refused Gatevo's credentials" | The provider key saved in Gatevo is wrong, revoked or out of credit. Apps see only this message; the provider's exact words are on the Requests page (open the row). |
| Costs look wrong | Check the model prices (per 1 million tokens) on Providers & models. |
| Locked out | Use Forgot your password? (needs mail settings in .env), or run php artisan tinker and reset the password. |
Known limits
- The data shield recognises structured data (emails, numbers, IDs, keys), not names or street addresses.
- For Anthropic models, tool calls and images are passed as text in this version.
- Costs depend on the prices you enter per model.
Credits
Gatevo is built with these open-source projects. Thank you to their authors.
| Laravel, Laravel Fortify, Inertia.js | MIT licence |
|---|---|
| React, Tailwind CSS, Vite | MIT licence |
| Radix UI, shadcn/ui | MIT licence |
| Lucide icons | ISC licence |
| Instrument Sans (font) | SIL Open Font License 1.1 |
| IBM Plex Sans Arabic (font) | SIL Open Font License 1.1 |