AIgency 2.0
A multi-model AI chat you run on your own hosting and sell with your own brand, prices and plans.
Overview
The package contains:
| Folder | What it is |
|---|---|
aigency/ | Version 2.0, ready to upload. Dependencies and the compiled interface are included: you do not need SSH, Composer or Node. |
documentation/ | This guide. |
THIRD-PARTY-LICENSES/ | The licenses of the libraries, font and images included (see Third-party licenses). |
Your customers chat with models from OpenAI, Anthropic and Google (and OpenAI-compatible providers such as xAI, DeepSeek and OpenRouter), can compare two models side by side, and pay with credits. You decide which models are offered, how much each one costs and how credits are sold.
Support and custom work: willian@polargames.com.br. Please include your purchase code and what you see (a screenshot and the text of the error help a lot).
Requirements
- PHP 8.3 or newer, with the latest security patch of your branch (8.3.36, 8.4.27 or 8.5.12 or newer). PHP 8.4 is recommended. Older PHP (8.2 or below) cannot run 2.0. Most hosting panels let you pick the PHP version per site (Hostinger: Websites → Advanced → PHP Configuration; cPanel: Select PHP Version). An older patch of 8.3/8.4 still installs: the installer only warns you to update it.
- MySQL 8 or MariaDB 10.6+, one empty database.
- PHP extensions: ctype, curl, dom, fileinfo, filter, hash, mbstring, openssl, pcre, pdo, pdo_mysql, session, tokenizer, xml. Recommended: intl, zip, gd.
- Apache or LiteSpeed with
.htaccess(standard shared hosting) or Nginx. - Shared PHP hosting is enough. A VPS is not required.
The installer checks every item and tells you what to change before anything is written.
Installation
- Create an empty MySQL database and a user for it in your hosting panel. Write down host, database name, user and password.
- Upload the contents of
aigency/to the folder where the site will live: the domain root (for examplepublic_html/) or a subfolder (public_html/chat/). Uploading a ZIP and extracting it with the panel's file manager is fastest. - Open the site in the browser. You are sent to
/install. - Check the requirements list. Red items must be fixed; yellow items are recommendations.
- Fill in the database details and your admin account (name, e-mail, a password of at least 12 characters) and click Install. Tables are created and example models and assistants are added.
- Sign in with the admin account. The installer is disabled from now on (it answers "not found").
public/ (optional, recommended when your panel allows
it). The package works when the whole folder is uploaded to the web root: the included index.php
and .htaccess send every request to public/ and block access to configuration files.
If your panel lets you choose the document root, point it to the public/ folder instead.Nginx
root /path/to/aigency/public;
location / { try_files $uri $uri/ /index.php?$query_string; }
location ~ \.php$ { include fastcgi_params; fastcgi_pass unix:/run/php/php8.4-fpm.sock; # your PHP version
fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
fastcgi_buffering off; } # answers are streamed word by word
Speed
public/.htaccess compresses text and lets browsers keep the built files for a year (their names change with
every version) and images for a week. Specialist photos have 160 and 320 px copies next to them, used where the photo is
shown small; after adding or replacing portraits in public/assistants/specialists by hand, run
php artisan aigency:avatar-sizes to make their copies (photos uploaded in the admin work without them).
Shared hosting notes (Hostinger, cPanel)
- Upload: upload
aigency.zip'saigency/contents as one ZIP in the panel's File Manager and use Extract; uploading thousands of files one by one is slow and can stop halfway. - PHP version: 8.3 is the minimum, 8.4 is recommended. Choose it for the domain in the panel (Hostinger: Websites → Advanced → PHP Configuration).
- PHP per folder: if the domain must stay on an older PHP because other sites use it, add this as the
first line of the
.htaccessin the AIgency folder (Hostinger and other CloudLinux/LiteSpeed hosts):AddHandler application/x-httpd-alt-php83___lsphp .php
(usephp84for PHP 8.4). The installer's requirements list then shows "Running 8.3.x". Uploading a new version replaces.htaccess: add the line again after every update. - Database host: prefer
127.0.0.1tolocalhostwhen your host accepts it. On Hostinger,localhost(a socket) refused some connections with many chats at once ([2002] Operation not permitted);127.0.0.1did not. Use the database name and user exactly as the panel shows them (usually with a prefix, e.g.u123456789_aigency). - Command line: the
phpcommand in SSH may be older than the site's PHP (Hostinger: 8.0). Call the right one by its path, e.g./opt/alt/php83/usr/bin/php artisan …. You only need SSH for the optional commands in this guide; installing and updating work in the browser. - No cron job needed: renewals, expiries and clean-ups run as pages are opened and webhooks arrive.
- E-mail: on Hostinger, "This server (sendmail)" in Admin → Brand → E-mail delivers to the inbox with a sender at your own domain; SMTP is only needed for another mailbox.
- Streaming and capacity: Hostinger's own CDN passes streamed answers through untouched. A Business
plan handled about 30 answers being written at once before queueing; the PHP process limit is shared by every site on
the hosting account, so the default
AIGENCY_MAX_STREAMS=12is safe. exec,proc_openand similar functions may be disabled by the host: AIgency does not need them.
AI providers and models
Go to Admin → Models.
- Paste the API key of each provider you want to use and click Test connection. Keys are stored
encrypted with your site's
APP_KEY; after saving, only the last four characters are shown. - Activate the models you want to offer. A model without prices cannot be activated.
- Adjust the margin of each model (see the next section).
| Provider | Where to get a key |
|---|---|
| OpenAI | platform.openai.com → API keys |
| Anthropic (Claude) | console.anthropic.com → API keys |
| Google (Gemini) | aistudio.google.com → Get API key |
| xAI, DeepSeek, OpenRouter | The provider's console. These use the OpenAI-compatible adapter; add prices before activating. |
Image generation uses an image model (for example gpt-image-2.5-flare) and is charged by the real usage reported by the provider.
Credits and pricing
Customers spend credits. Each answer costs:
credits = provider cost in US$ × credits per US$ × model margin (rounded up)
- Provider cost comes from the real token counts returned by the provider and the model's price per million tokens.
- Credits per US$: how many credits correspond to one dollar of provider cost. Default 10,000
(setting
AIGENCY_CREDITS_PER_USD). - Margin: per model, default 3×. With 3×, an answer that costs you US$ 0.001 at the provider charges the customer the credits worth US$ 0.003.
Before an answer starts, the maximum possible cost is reserved; when it ends, only the real cost is charged and the rest returns to the balance. A failed or cancelled answer that produced nothing costs nothing. The Admin → Models page shows the credits of a typical message for each model so you can check your prices.
Billing: packs, plans, mixed
In Admin → Plans & billing choose how you sell:
| Mode | How it works |
|---|---|
| Credit packs | Customers buy credits once. Purchased credits do not expire. Every active model is available. |
| Subscription | Monthly or yearly plans that grant credits each cycle and define which models are included. Unused plan credits expire, carry over up to a cap, or accumulate, as you configure per plan. |
| Mixed (default) | Plans plus packs. Plan credits are spent first. A model outside the customer's plan can still be used with purchased credits (the chat shows a lock and explains why). |
Packs may include bonus credits. Every movement is recorded in an append-only ledger that customers see on their Usage page.
What each plan opens
In Admin → Plans & billing → Prices, each plan says:
- Models: which models are included.
- Areas this plan opens: all areas, or some. This only matters for areas marked Only for plans that open this area in Admin → Areas; areas open to everyone stay available on any plan.
- Specialists one by one: a specialist ticked here opens on this plan even in an area the plan does not open. A specialist with the lock in Admin → Specialists (Only for plans that include it) opens only on the plans that tick it (or on plans set to "Every specialist marked only for plans").
- Tools: web reading, web search, images, files and pages, per plan.
- AI employees of their own (see Knowledge base).
A locked specialist shows "On the X plan" in the catalog, and opening it shows an upgrade card with the plans that include it. Purchased credits do not unlock it: it is an upgrade. In "credit packs only" billing nothing is locked.
Monthly and yearly prices
A plan can be charged monthly, yearly or both. Turn on Charge yearly and set a Yearly discount (%): the yearly price is worked out as 12 monthly payments minus the discount, and you can still type the exact yearly price (the saved yearly price is what customers pay). Each interval has its own credits per cycle. The pricing page and your home page show a Monthly / Yearly switch with "Save N%" and the price per month billed yearly. Turning an interval off hides it from new customers; current subscribers keep it.
Stripe
- In the Stripe dashboard, copy your secret key (
sk_live_…, orsk_test_…while testing). - Create a webhook endpoint pointing to
https://your-site/webhooks/stripewith these events:checkout.session.completed,invoice.paid,invoice.payment_failed,customer.subscription.updated,customer.subscription.deleted. Copy its signing secret (whsec_…). - Paste both in Admin → Plans & billing → Payments → Stripe and save. They are stored encrypted;
the page shows the webhook URL and the event list to copy into Stripe. (Alternatively, set
STRIPE_SECRET_KEYandSTRIPE_WEBHOOK_SECRETin.env; values saved in the admin take precedence.) - In Admin → Plans & billing → Prices, create your packs and plans with prices.
Bank transfer (manual payment)
No gateway account needed. Open Admin → Transfers, turn it on and write the details customers should use (bank, account, Pix or IBAN, notes); you can add one text per language. Customers then see a "Bank transfer" button on every plan and credit pack, pay from their bank and upload the receipt (JPG, PNG, WebP or PDF, up to 5 MB).
Each order waits in the same page: open the receipt, then Approve (credits are added once, never twice) or Refuse with a reason. The customer gets an e-mail either way, so set up outgoing e-mail in Admin → Brand → E-mail first. A plan paid by transfer covers one period and does not renew by itself.
PayPal (credit packs and plans)
- At developer.paypal.com, create a REST app (Sandbox to test, Live to sell) and copy its Client ID and Secret. Selling plans needs a PayPal Business account.
- Paste them in Admin → Plans & billing → Payments → PayPal, choose the environment and save.
- For plans, add a webhook in the same PayPal app pointing to
https://your-site/webhooks/paypalwith the events shown on that card:BILLING.SUBSCRIPTION.ACTIVATED,BILLING.SUBSCRIPTION.CANCELLED,BILLING.SUBSCRIPTION.EXPIRED,BILLING.SUBSCRIPTION.SUSPENDED,BILLING.SUBSCRIPTION.PAYMENT.FAILEDandPAYMENT.SALE.COMPLETED.
Credit packs need no webhook: the customer approves the payment on PayPal and the order is captured when they come back, after the owner and amount are checked. A payment PayPal holds for review shows as pending and is credited when it clears (checked again when the customer opens Plans & credits).
Plans: the PayPal product and plan are created for you the first time a customer subscribes (and again if you change the price, currency or interval). Each renewal is credited once, by the webhook or, if a webhook is missed, the next time the customer opens Plans & credits. The webhook only says which subscription changed; everything is re-read from PayPal's API, so a forged call credits nothing. PayPal has no customer portal: customers use Cancel subscription on Plans & credits and keep access until the end of the period they paid. One renewing subscription per customer at a time: to change plan on PayPal, cancel and subscribe again.
Safe crediting: credits are never granted from what the browser sends. When the customer comes back from Stripe, your server reads the payment from Stripe's API; the signed webhook does the same in the background. Both use the same unique key, so a purchase or renewal is credited once even if the customer reloads the page, the webhook arrives late or Stripe sends it twice. The paid amount is checked against the price. Subscribers manage or cancel their plan with Manage subscription on Plans & credits, which opens Stripe's own customer portal (turn the portal on once in the Stripe dashboard → Settings → Billing → Customer portal).
Testing a purchase before you go live
Before selling for real, buy something on your own site in test mode. No money moves, and you see the whole path: payment page, return to your site, credits on the Usage page and the e-mail.
- Stripe: in the Stripe dashboard turn on Test mode, copy the test secret key
(
sk_test_…) and create the webhook in test mode too (it has its ownwhsec_…). Save both in Admin → Plans & billing → Payments → Stripe. Sign in as a customer, open Plans & credits, choose a plan or a credit pack and pay with Stripe's test card4242 4242 4242 4242, any future date, any CVC and any name. To see a refused payment use4000 0000 0000 9995; for a card that asks for 3-D Secure,4000 0025 0000 3155. Test subscriptions renew in Stripe's test clock, and the customer portal (Manage subscription) works in test mode as well. - PayPal: choose Sandbox in the PayPal card and paste the sandbox app's Client ID and Secret. At developer.paypal.com → Sandbox accounts you will find a test buyer (a "Personal" account; set its password there). Buy on your site and log in to PayPal with that test buyer.
- Bank transfer: turn it on, buy as a customer with any image as the receipt, then approve it in Admin → Transfers.
Test purchases add real credits on your site: remove them in Admin → Customers (adjust credits) or
use a test account. Going live: replace the Stripe keys with sk_live_… and a webhook created
in live mode (new whsec_…), and switch PayPal to Live with the live app's keys. For a public demo of
your site you can keep test mode on and tell visitors the test card (see Public demo mode).
Free preview (chat before signing up)
Visitors can talk to a specialist a few times before creating an account: on the public site, Chat opens the preview. When the free messages run out, a "Continue your conversation" window lets them sign up or sign in without leaving the page, and the conversation moves to their new account. Settings are in Admin → Plans & billing → Preview without account:
- Free messages per visitor (default 5) and the answering model (default: the cheapest active model with a price). Visitors never see the model name or credits.
- Daily cost cap (default US$ 2, so at most about US$ 60 a month): the preview's provider cost of the day, including answers still being written. Past it, visitors see the invitation to sign up instead of answers. At most 3 preview answers are written at the same time, so paying customers always have room on shared hosting.
- New visitors per IP in 24 h (default 3) and 20 messages per IP per hour. reCAPTCHA, when set up, is asked on the first message.
- Site behind Cloudflare: turn this on only if your domain goes through Cloudflare; the visitor's real IP is then read from Cloudflare's header, and only for requests that come from Cloudflare's addresses.
- The card shows the last 30 days: visitors, messages, sign-ups that came from the preview, conversion rate and cost. If welcome credits are 0, people who sign up from the preview need to buy credits to continue; the card warns you.
An answer that fails at the provider gives the free message back. In the preview the specialist makes no files and keeps no memory, and says so if asked. Free images are off by default: set "Free images per visitor" (for example 1 or 2) and, if you like, the preview's image model (default: the cheapest active image model with a key). Each image costs that model's price and counts toward the daily cap; an image the provider fails to make is given back.
Sign-up bonus per network: next to the welcome credits, "Bonuses per network (IP) in 30 days" (default 3, 0 = no limit) stops one person from making many accounts to collect the bonus. Schools and offices share one network, so raise it if your customers sign up from the same place.
For your privacy policy: the preview sets one functional cookie (aigency_preview,
30 days) that links the browser to its conversation; it is needed for the chat to work and is not used for analytics
or advertising, so it does not depend on the cookie notice. The visitor's messages and the answers are stored on
your server, with any images made there. The visitor's IP address is stored only as a keyed hash, to apply the
limits above. Conversations and images of visitors who never create an account are deleted after 30 days; when the
visitor signs up from the preview, the conversation and its images become part of their account. Suggested text: "You can try our specialists before creating
an account. We store that conversation and a functional cookie for up to 30 days so you can continue it; if you
create an account from it, the conversation is kept in your account."
Your brand
- Name:
APP_NAMEin.env(set by the installer). It appears in the title, menus, e-mails and pages. - Accent color and logo: Admin → Brand. The color is used for buttons, links and highlights in light and dark mode; the logo (PNG, JPG or WebP, up to 1 MB) replaces the default mark and the browser tab icon. Changes apply on the next page load; nothing needs to be rebuilt.
- Terms of use and privacy policy: in Admin → Brand → Pages, written in Markdown.
They are published at
/termsand/privacyand linked from the sign-in and sign-up screens; an empty page stays offline and its link is hidden. AIgency does not ship legal text: write what applies to your business and your country, ideally with a lawyer. The page already shows its title, so start your text with the first section. - Search description: one or two sentences in the same card, used as the page description for search engines.
- Google Analytics: paste your GA4 measurement ID (
G-…) in Admin → Brand → Integrations. A cookie notice then appears for visitors, and Analytics loads only for those who click Accept. Leave it empty and there is no notice and nothing from Google. - reCAPTCHA on sign-up: create reCAPTCHA v2 "I'm not a robot" checkbox keys in the Google reCAPTCHA admin console (add your domain) and paste both keys in the same card. The sign-up page then loads Google's script and shows the checkbox. The secret key is stored encrypted and never sent to the browser; leave the secret field empty to keep the saved one.
Outgoing e-mail
Sign-up confirmation, password reset, bank transfer notices and receipts are sent by e-mail. A fresh install only writes e-mails to a log file, so set this up before you open the site: Admin → Brand → E-mail.
- SMTP (recommended): the server, port, security, user and password of an e-mail account. On
Hostinger create a mailbox (e.g. noreply@yourdomain.com) and use
smtp.hostinger.com, port 465 with SSL. Services such as Brevo, Mailgun or Amazon SES also work (port 587 with TLS). - This server (sendmail): uses the hosting's own mail function, when it has one.
- The sender e-mail should belong to your domain, or providers may mark messages as spam.
- Click Send a test e-mail: it goes to your admin address. If it fails, the mail server's own answer is shown so you can fix the setting. The password is stored encrypted and never shown again.
- Requiring e-mail confirmation on sign-up (Admin → Plans & billing → Sign-up) can only be switched on once the site can send e-mail, so new customers are never locked out waiting for a link.
Forgot password
"Forgot password?" on the login page sends a 6-digit code by e-mail. The customer types it on the
same page together with the new password; there is no link to click. The e-mail carries your site name
(APP_NAME) and brand colour and is written in the language the customer is using.
- A code lasts 15 minutes, works once, and asking for a new one cancels the old one. After 5 wrong tries a new code is needed. One code per address per minute and 5 per hour, plus a limit per visitor IP.
- The page answers the same whether or not the e-mail has an account, so nobody can use it to find out who is registered.
- After the reset the customer is signed out on every other device and logs in with the new password.
- If outgoing e-mail is not set up, the page says so ("This site cannot send e-mail yet") instead of pretending
a code was sent. If the mail server refuses the message, the customer is told to try again later and the error goes
to
storage/logs. - On the public demo (
AIGENCY_DEMO) the demo accounts cannot reset their password.
Languages
The interface ships in 14 languages: English, Español, Português (Brasil), Français, Deutsch, Italiano, Nederlands, Русский, Türkçe, العربية (right to left), हिन्दी, Bahasa Indonesia, 简体中文 and 日本語.
- Each visitor sees their browser's language when it is available; signed-in users can choose another in the user menu, and the choice is saved to their account.
- The site's default language is set in Admin → Plans & billing → Sign-up (Default site language).
- Models answer in the language the customer writes in.
- Interface texts live in
resources/js/lib/i18n/<code>.ts; server messages (validation, e-mails, error pages) inlang/<code>/. Editing the interface texts requires rebuilding the frontend (npm ci && npm run build).
Areas (niche packs)
The same site can serve different audiences at once. An area is a group of specialists with its own banner: customers see a tab per area in the catalog (when two or more are on), with the area's headline and team photo. The installer installs the four areas below and asks which one the home page uses; switch off or delete in Admin → Areas the ones you do not want. Four areas ship with AIgency:
- AI Agency (default): 113 specialists for companies and creators (marketing, sales, design, technology, business…), with the site's standard headline in 14 languages.
- Education: 15 AI tutors, one teacher per subject (philosophy and sociology included), Spanish and French teachers, a speaking partner (talk with the microphone, it answers by voice), a pronunciation coach and a study coach. They guide with hints and exercises instead of doing homework. If your audience includes minors, consent and children's data rules in your country are your responsibility.
- Wellness: 11 coaches for training, walking, running, yoga, healthy eating and recipes, sleep, meditation, habits, posture and everyday emotional balance. They never diagnose or prescribe and send health questions to a professional; the emotional guide points to crisis lines.
- Career & money: 11 coaches for a first job or internship, résumé and LinkedIn, mock interviews, salary, career change, budget, debt, money basics, beginner investing, a first business and freelancing. Financial education only: they never recommend a specific product or promise returns.
- Area on / off: switching an area off hides its specialists and their conversations from the lists; nothing is deleted, old conversations still open by their link, and switching it on brings everything back (specialists you hid one by one stay hidden).
- Use on the home page: installs the area's missing specialists (your edits are kept), switches it on and shows its headline on the home page. Other areas do not change.
- Only for plans that open this area: customers whose plan does not open the area see its specialists with a lock and "On the X plan"; opening one shows an upgrade card with the plans. Purchased credits do not unlock it: it is an upgrade. In Admin → Plans & billing, each plan says which areas it opens (all, or some). In "credit packs only" billing nothing is locked.
- Specialists you create yourself, imported ones and your customers' own AI employees are in no area: always shown, never locked.
Managing areas
- New area: give it a name (e.g. Health, Legal, Real estate). It starts empty.
- Specialists (button on each area): tick who belongs to it. A specialist is in one area at most: ticking one here moves it from its current area.
- Rename or Delete area. Deleting removes the area's specialists that nobody has talked to yet; those that already have conversations are hidden instead, so customers can still open their history.
- Ready-made packs: a pack that is not installed (or one you deleted) can be installed again as a
new area; the home page does not change. With SSH,
php artisan aigency:install-packsinstalls every pack's missing specialists at once and keeps your edits. - Specialists' texts: after an update brings better texts, the card shows how many specialists still have an older factory text. Update texts replaces their title, description, welcome, suggestions and instructions; texts you edited are kept unless you tick the option to replace them too. Visibility, order and photos you uploaded never change.
New specialists come in the language you are using in the admin when the pack has it (English and Brazilian Portuguese ship), else English.
Making your own pack
Create a folder database/packs/<key> (key: lowercase letters, digits and dashes) with a pack.json
and, optionally, a photos/ folder (WebP, JPG or PNG; copied to public/assistants/packs/<key>/
when applied). Copy database/packs/school/pack.json as a starting point. Each text can be a plain
string or an object by language ({"en": "…", "pt_BR": "…"}). A long description, welcome or
instructions text can also be a list of pieces (["You are …, ", "and you …"]), as in the shipped packs: the
pieces are joined with nothing in between, so keep the space at the end of a piece.
{
"key": "clinic",
"name": {"en": "Clinic"},
"description": {"en": "Health information assistants."},
"site": {"badge": {"en": "…"}, "title": {"en": "A *specialist* for every question"}, "subtitle": {"en": "…"},
"hero": {"team": "assistants/packs/clinic/team.webp", "teamHero": "assistants/packs/clinic/team-arc.webp"}},
"specialists": [
{"slug": "clinic-nutrition", "sort": 1, "photo": "assistants/packs/clinic/nutrition.webp", "voice": "female",
"name": {"en": "Nutritionist"}, "title": {"en": "Nutrition"}, "category": {"en": "Health"},
"description": {"en": "…"}, "welcome": {"en": "…"}, "suggestions": {"en": ["…", "…"]},
"skills": {"en": ["…"]}, "instructions": "You are … (in English; models answer in the user's language)"}
]
}
Slugs must be unique across all packs (prefix them with the pack key). *word* in the title is highlighted.
Without site, the standard headline is used; give it in as many of the 14 languages as you can (missing
ones fall back to your English). A broken pack.json is listed in Admin → Areas with the reason and
is never installed. A new pack appears there as an area that is not installed yet.
site gives the home page headline (used when the pack is the home's area) and the catalog banner. To give
an area a catalog banner without touching the home page, use "banner": {"badge": …, "title": …, "subtitle": …}
instead: the banner wins in the catalog, and site stays the home headline. An optional
previous.json next to pack.json lists older factory texts and photos
({"slug": {"instructions": […], "photo": […]}}) so Update texts can tell an old factory text
from one you edited; you do not need it for a new pack.
Customers
Admin → Customers lists everyone with an account (preview visitors are not customers): plan, free credits, conversations, messages, last activity and sign-up date, with search by name or e-mail. Open a customer to:
- Edit the name and e-mail (a new e-mail must be confirmed again).
- Block the account: the customer is signed out at once and cannot sign in until you unblock it. Admin accounts cannot be blocked here. Blocking does not cancel a subscription: cancel it in your Stripe dashboard if needed.
- Adjust credits: add (e.g. compensation, a courtesy or credits to test the site) or remove (with a minus sign). Credits you add can have an expiry (7, 30 or 90 days, or never): they leave the balance on that date, without touching what the customer bought. Every adjustment is a ledger entry with its reason, which the customer sees on their Usage page. Credits held by answers being written are never removed, and the balance never goes negative.
- See the statement (latest 50 entries) and the customer's conversations, read-only. Files and pages the specialist made show only their names.
For your privacy policy: administrators can read customers' conversations to provide support and prevent abuse. Every opening is recorded (which admin, which customer and conversation, when). Say this in your privacy policy, e.g. "Our staff may access your conversations to provide support or investigate abuse; each access is logged."
Admin overview
Admin → Overview is the first admin page: sign-ups and active customers per day, answers and the credits they used, recurring revenue per month (yearly plans count 1/12), active subscribers, purchases and renewals, provider cost and margin, where granted credits came from, top specialists and a live feed of recent activity. Each chart can be shown as a table. Amounts in other currencies are listed apart, not added.
Sample data: to see the admin full before you have customers (or for screenshots), run with SSH:
php artisan aigency:sample-data --customers=40 --days=30
It creates up to 40 sample customers (addresses at sample.example.com, a password nobody knows) with
conversations, purchases and plans over the last days, through the real ledger, so they appear in Overview, Customers and
Usage like real ones. No AI provider is called. Remove them before you open the site:
php artisan aigency:sample-data --remove
Specialists
Specialists are ready-made personas (instructions, welcome message, suggested questions, skills, voice and portrait) that work with any model. 150 come installed, grouped in four areas. A conversation started with a specialist keeps its instructions on every message, whichever model answers.
Edit them in Admin → Specialists: each row opens a side panel (texts, photo, category, voice, tools, visibility). The lock on a row makes that specialist only for plans that include it (see Plan access); the book icon opens its Knowledge page. You can create your own specialists; they belong to no area until you put them in one.
Knowledge base and AI employees
A specialist can answer from files and texts instead of general knowledge: Admin → Specialists, the book icon on a row opens its Knowledge page. Upload PDF, Word, Excel, PowerPoint, CSV or text files, or write questions and answers. Nothing is trained: on every question the passages that match are found and given to the model, and the answer cites them (customers click a source to see the passage). With Only from the base, a question the base does not answer gets your "I don't know" message with your contact, never a made-up answer.
- Search: by words with MySQL or MariaDB, on every host. With an OpenAI or Gemini key, also by meaning
(embeddings stored in your database; about US$ 0.003 for a 300-page PDF on OpenAI). Turn the search by meaning off with
AIGENCY_KNOWLEDGE_EMBEDDINGS=off. - Test it: the page has a free search test and lists the real questions it could not answer.
php artisan aigency:knowledge-eval --example --answersmeasures a base end to end. - Your customers' own AI employees: set AI employees of their own per plan in Admin → Plans & billing (and a default for credit packs or no plan; 0 = off). A customer then sees My AI employees, creates one from guided fields and teaches it with their files. It is private to them: it never appears on your site, in the preview or to other customers. Its search by meaning is charged in their credits. If their plan later allows fewer, the newest ones are paused in the chat until they upgrade or delete some.
For your privacy policy: files and texts in a knowledge base are sent to your AI provider in the passages of each answer (and, for the search by meaning, once when uploaded). Anything in a base can be told to whoever talks to that specialist. Administrators can open a customer's AI employee and its files from the admin (to provide support). Deleting a source, an employee or the account removes the files, passages and photo at once; past answers keep the text they already contained. Say this in your privacy policy, e.g. "Files you add to your AI employee are processed by our AI provider to answer questions and are deleted when you remove them."
Chat on your website
A specialist with a knowledge base can answer on any website: a chat button in the corner that opens the conversation in a small window. You can do it for your own specialists, and your customers can do it for their AI employees.
- Where: the specialist's Knowledge page (Admin → Specialists, book icon; for a customer, My AI employees), tab On your site. Turn it on there.
- The key: turning it on creates a random public key used in the code. New key retires the code already pasted on sites; turning it off stops the chat at once.
- Allowed sites: one address per line (
https://www.example.com). The chat only opens inside those sites; on any other site the browser refuses to show it, and its server calls are refused. No sites listed means nowhere. This keeps others from showing your specialist, paid with your credits, on their pages. - Limits: messages per day for the specialist (default 200, up to 5,000), 30 per visitor a day, 5 new visitors per network a day and 2 answers being written at once on the whole site (shared hosting keeps PHP workers free). Over a limit, the visitor sees a short "try again later" message.
- Who pays: each answer costs credits like a chat message, from whoever created the specialist: your site for your own specialists, the customer for their AI employee. Without credits the visitor gets the specialist's "I don't know" contact instead of an answer.
- The code: copy one line,
<script src="…/widget.js" data-key="…" async></script>, and paste it before</body>. Options:data-color,data-label,data-side="left", anddata-inline="#element"to show the chat inside a page element. There is also an iframe code to place the chat inside a page. - Site conversations: the same section lists the latest conversations from the site, read-only: what visitors asked and what was answered. Questions the base could not answer also appear in the Knowledge page list.
- What visitors do not get: no account, no tools (images, files, pages), no memory and no attachments. They talk to the specialist and its knowledge base only, in their browser's language. No cookies are set on your customer's site.
For your privacy policy: what visitors type on a website is stored as that specialist's site conversations and can be read by whoever owns the specialist. Your customers who put the chat on their sites should say so in their own privacy policy.
Chat features
- The web, with any model. When a customer pastes a link ("what do you think of my shop's site?") the
specialist opens it and answers from the real page: it runs from your server (public addresses only, never your hosting's
own network) and costs only the tokens of the text read. With a Google Gemini key saved and at least one Gemini chat
model active with a price, specialists also search the web for news, prices and recent facts: the
cheapest active Gemini model searches with Google and the specialist answers with any model. The sites used show below
the answer. The search's own tokens are added to that answer's credits, at the Gemini model's price and margin.
Google includes a monthly allowance of free grounded searches on Gemini 3; AIgency stops at 4,500 searches a
month by default, so you stay inside it. To change the cap, run once with SSH (0 = no limit):
php artisan tinker --execute="DB::table('settings')->updateOrInsert(['key'=>'web_search_limit'],['value'=>'10000','updated_at'=>now()])"Without SSH, run the same in phpMyAdmin:INSERT INTO settings (`key`, value, created_at, updated_at) VALUES ('web_search_limit', '10000', NOW(), NOW()) ON DUPLICATE KEY UPDATE value = '10000';Turn web reading or web search off per plan (Admin → Plans & billing, Tools) or per specialist (Tools in its panel). - Side-by-side comparison of two models in one message; the customer keeps the better answer.
- Answers stream word by word and survive connection drops (the browser resumes where it stopped).
- Edit, regenerate and cancel. Safe Markdown rendering.
- Memory: facts the customer chooses to keep, given to every model. Customers can see, edit and turn it off.
- Specialists create images, Word/PDF files and working web pages or SVGs on request ("make me a logo", "build a landing page"), with no mode to switch. Pages open in a side panel with preview, code, phone view and download. When the page tool is offered, an answer may use up to 16,000 output tokens (held in credits first; without enough balance the tool is not offered).
- Listen: every answer has a "Listen" button. By default it uses the visitor's browser voice,
at no cost. In Admin → Brand → Voice you can switch on a natural AI voice from your provider
(OpenAI
gpt-4o-mini-ttsor Gemini 2.5 Flash TTS, using the key you already set): about US$ 0.015 of provider cost per minute of speech, charged to the customer in credits with your margin (the card shows the credits per minute). Audio is cached on your server, so hearing the same answer again is free; long answers are read in parts; a daily limit of new audios per customer applies (default 100). If the AI voice fails or the customer has no credits, the browser voice reads it instead. Each specialist's voice gender (Admin → Specialists) picks a female or male voice. - Dictation: the microphone button turns speech into text. With a Gemini key it uses Gemini
3.5 Flash-Lite (cheaper), otherwise OpenAI
gpt-4o-mini-transcribe; the customer pays the transcription in credits. - Documents: customers attach a PDF, Word, Excel, PowerPoint, CSV or text file (up to 10 MB,
AIGENCY_DOCUMENT_MAX_KB) and talk about it. The text is read on your server and sent to the model with each message (up toAIGENCY_DOCUMENT_TOKENS, 30,000 tokens). A file bigger than that sends its beginning plus the pages that match the question. A spreadsheet gets exact answers: the model asks for totals, averages, counts or filtered rows and your server computes them over every row. A scanned PDF (only images, up to 20 pages) goes whole to models that read PDFs (Claude, GPT and Gemini); other models say they cannot see it. If no active model reads PDFs, scanned files are refused with a message. - Export a conversation as TXT, Markdown, DOCX or PDF. Share a read-only link that can be revoked.
- Customers can download all their data (profile, conversations, memories, credit history and files) as a ZIP in Settings → Profile, and delete their account there, which also deletes their files. This covers the access and portability requests of laws such as GDPR and LGPD.
Moving from 1.x
Version 1.x is deprecated and no longer included in the package. 2.0 is a new product: your 1.x data (customers, passwords, credits and assistants) moves in with the importer below.
Install 2.0 in a new folder and database (your 1.x site keeps working meanwhile). Then, with SSH access, run from the 2.0 folder:
LEGACY_DB_PASSWORD='your 1.x database password' php artisan aigency:import-legacy your_1x_database --dry-run
Options: --host=, --port=, --username=; --credits=paid (default:
one old credit becomes one new credit) or --credits=usage --divisor=N (N old credits become one new
credit). Remove --dry-run to import for real. A JSON report is saved in storage/app/private/.
root) and, if the
php command is older than 8.3, call PHP by its path:
LEGACY_DB_PASSWORD='…' /opt/alt/php83/usr/bin/php artisan aigency:import-legacy u123_old1x --username=u123_old1x --dry-runBoth databases must be reachable from the 2.0 site (usually the same hosting account, host
127.0.0.1).
Without SSH, ask your host to run the command, or contact support. After importing, Admin → Areas → Update
texts gives the imported 1.x personas the rewritten 2.0 texts and portraits (your own edits are kept).| 1.x | 2.0 |
|---|---|
| Customers | Users. Their 1.x passwords keep working: on the first sign-in the password is checked once and stored with modern hashing. E-mails that already exist in 2.0 are listed in the report and skipped. |
| Credit balances | An opening entry in the ledger. |
| Prompts (personas) | Assistants, with category and suggestions. A persona with the same slug as an example replaces it. |
| Credit packs | Imported hidden: check prices and credits, then activate them. |
| Chat history | Conversations, with the old tone/style suffix removed from the messages. |
| Tone, writing style and output language menus | Not needed in 2.0: every model answers in the language the customer writes in; a lasting preference ("always answer formally") goes in the customer's Memory and applies to every model; a persona's style goes in the assistant's instructions. |
The 1.x database is only read. Running the command again skips users imported before.
Advanced settings
Optional lines in .env:
| Setting | Default | Meaning |
|---|---|---|
APP_NAME | set by installer | Site name in the title, e-mails and pages. |
AIGENCY_CREDITS_PER_USD | 10000 | Credits per US$ 1 of provider cost. |
AIGENCY_PROFILE | shared | vps raises the limits below. |
AIGENCY_MAX_STREAMS | 12 (shared), 100 (vps) | Answers being generated at once on the whole site. Shared hosting allows a limited number of PHP processes; extra requests wait their turn. |
AIGENCY_PER_USER_ACTIVE | 2 | Answers one user can generate at once. |
AIGENCY_CONTEXT_TOKENS | 24000 | How much recent conversation history (estimated tokens) is sent with each message. Older turns are left out, which keeps long conversations cheap and inside every model's limit. |
AIGENCY_SILENCE_TIMEOUT | 90 | Seconds without data from a provider before the answer is stopped and refunded. |
AIGENCY_DOCUMENT_MAX_KB | 10240 | Largest document a customer can attach, in KB. |
AIGENCY_DOCUMENT_TOKENS | 30000 | How much of a document's text goes to the model on each message. |
AIGENCY_KNOWLEDGE_EMBEDDINGS | auto | off keeps knowledge base search by words only. |
AIGENCY_AUTO_MIGRATE | true | false stops the automatic database update on
the first visit after an upload (then run php artisan migrate --force yourself). |
AIGENCY_CA_BUNDLE | empty | Path to a CA certificate file, for hosts whose SSL certificate list is too old to reach the AI providers. |
AIGENCY_DEMO… | off | See Public demo mode. |
Public demo mode
To show your site to prospects without risk, turn on demo mode in .env. It is off by default.
| Setting | Default | Meaning |
|---|---|---|
AIGENCY_DEMO | false | true turns demo mode on. |
AIGENCY_DEMO_ADMIN | empty | E-mail of an existing admin account. The login page shows Sign in as the demo admin (no password). It opens the whole admin, but nothing can be saved there (keys, payments, e-mail, brand, customers) and its password cannot be changed or reset. |
AIGENCY_DEMO_CUSTOMER | empty | E-mail of an existing customer account. The login page shows Sign in as the demo customer: each visitor gets an account of their own, made on the spot with your welcome credits, so visitors never see each other's chats. The browser keeps it (a cookie) and comes back to it. |
AIGENCY_DEMO_VISITORS_PER_IP | 5 | New visitor accounts per network per day; past it, the shared demo customer account is used. |
AIGENCY_DEMO_ACCOUNTS | empty | More read-only accounts, comma-separated e-mails. |
AIGENCY_DEMO_DAILY_MESSAGES | 20 | Messages each account may send per day (0 = no limit). |
AIGENCY_DEMO_MODELS | anthropic.haiku-5-5 | The only chat models demo users may pick, comma-separated model keys as listed in Admin → Models (empty = all). Other models answer "turned off in the demo". |
AIGENCY_DEMO_IMAGES | false | Off: no image is created or charged; the specialist says image creation is turned off in the demo and describes what it would show. |
In demo mode the AI voice of "Listen" (the browser voice reads instead) and dictation are also off, and demo accounts cannot open other people's conversations, receipts or knowledge files; e-mail addresses and key endings are masked.
Create the two accounts first: the admin with the installer or an existing admin, the customer by signing up. Then
add the lines to .env. Set welcome credits and the preview limits low, and use a
provider key with a spending limit: visitors chat with your real AI keys.
Source code and rebuilding
The full source code is included. You only need the steps below if you change the interface (screens, texts in
resources/js/, styles); PHP changes need no build.
Path (inside aigency/) | What it is |
|---|---|
resources/js/ | Interface source: Vue 3 + TypeScript pages, components and the 14 language files. |
resources/css/ | Tailwind CSS source. |
package.json, package-lock.json | Interface dependencies, locked to the versions we tested. |
vite.config.ts, tsconfig.json, tailwind.config.js | Build configuration. |
public/build/ | The compiled interface the site serves. Shipped unminified and readable. |
- Install Node.js 20 or 22 (LTS) on your computer.
- In the
aigency/folder runnpm ci(installs the exact locked versions intonode_modules/). - Run
npm run build. It replacespublic/build/with a new, minified build (smaller files). For an unminified build, runnpm run build -- --mode packageinstead (the shipped copy was also reformatted for reading; both work the same). - Upload the new
public/build/folder to your hosting. Do not uploadnode_modules/.
While editing, npm run dev serves the interface with instant reload (needs a local PHP server for the site).
Optional checks: npx vue-tsc --noEmit (types) and npm run format (code style).
Updating
- Back up the database, the
.envfile, thestorage/folder and your uploads inpublic/branding/(logo) andpublic/assistants/custom/(specialist photos you uploaded). - Upload the new files over the old ones, keeping
.env,storage/and those two folders. - If you added an
AddHandlerline to.htaccess(see Shared hosting notes), add it again. - Open the site. The first visit applies the database updates of the new version automatically (no SSH needed).
With SSH you can run them yourself:
php artisan migrate --force. - If the version brings new specialist texts, Admin → Areas → Update texts applies them; new packs appear under Ready-made packs.
- Clear the caches (below).
Clearing the cache after an update
The interface files get new names with every version, but a browser, a CDN or the server may still hold the old pages for a while. If something looks broken or unchanged after updating (a blank page, an old screen, a button that does nothing):
- Your browser: reload without the cache:
Ctrl + F5(Windows/Linux) orCmd + Shift + R(Mac). If it persists, clear this site's data (Chrome: the icon left of the address → Site settings → Delete data; Safari: Settings → Privacy → Manage Website Data) or try a private window. - CDN or cache of your host: purge it. Hostinger: hPanel → Websites → your site → Performance → CDN → Flush cache (and LiteSpeed Cache, if on). Cloudflare: Caching → Configuration → Purge Everything.
- Server cache (optional, with SSH):
php artisan optimize:clear. - Tell your customers the same first step if they report an old screen: one hard reload fixes it.
Troubleshooting
| Symptom | Cause and fix |
|---|---|
| Answers appear all at once instead of word by word | Something between PHP and the browser buffers
the response (a proxy, a CDN, gzip). The installer tests this. On Cloudflare, make sure the site is not cached;
on Nginx use fastcgi_buffering off. |
| "Server busy" while chatting | The simultaneous answer limit was reached; the chat retries automatically.
Raise AIGENCY_MAX_STREAMS only if your plan allows more PHP processes. |
| Test connection fails | Check the key and the provider account balance. If the error mentions SSL
certificates, ask your host to update the CA bundle, or set AIGENCY_CA_BUNDLE to the path of a CA file
(see Advanced settings). |
| Blank page or error 500 | See the latest file in storage/logs/. Check that storage/
and bootstrap/cache/ are writable. |
| Payment succeeded but credits did not arrive | Check the webhook in the Stripe dashboard (URL and events) and the signing secret in Admin → Plans & billing → Payments. Stripe retries failed deliveries. |
Support
Write to willian@polargames.com.br or use the Support tab of the item
page on CodeCanyon. Please include your purchase code, your site address, your PHP version and what you see (a
screenshot and the text of the error, or the latest file in storage/logs/).
Security notes
- Keep
.envprivate and back it up: it holdsAPP_KEY, which encrypts the provider keys. Changing it makes stored keys unreadable (re-enter them in the admin). - Keep PHP updated in your hosting panel.
- Model output is shown as text with safe Markdown; HTML from answers never runs in the chat itself, only in the isolated page preview below.
- Shared conversation links use random tokens, are not indexed by search engines and can be revoked.
- Web pages written by a specialist run isolated (a sandboxed frame with its own origin): they cannot read the customer's session, call the site as the customer or see other conversations. Their images use signed links that expire.
- Pages send a Content Security Policy that only runs the site's own scripts. Google's hosts are allowed only when you turn on Analytics or reCAPTCHA, which is why there is no free-form "paste a script" field.
Third-party licenses
Every library, font and image included is listed with its license in the THIRD-PARTY-LICENSES/ folder of
the download: php-packages.txt (everything in vendor/), javascript-packages.txt
(the packages compiled into public/build/ and the build tools), plus-jakarta-sans-OFL.txt and a
README.txt. The PHP and JavaScript libraries are under permissive licenses (MIT, BSD, Apache 2.0, ISC), except:
| Library | License | Used for |
|---|---|---|
| smalot/pdfparser | GNU LGPL 3.0 | Reading the text of PDF files |
| dompdf, php-font-lib, php-svg-lib | GNU LGPL 2.1 / 2.1+ / 3.0+ | PDF export of conversations |
| PHPWord | GNU LGPL 3.0 | Word export |
| nette/schema, nette/utils | BSD-3-Clause (offered as BSD-3-Clause or GPL; used under BSD-3-Clause) | Used by the framework's Markdown library |
| DOMPurify | Apache 2.0 (offered as MPL 2.0 or Apache 2.0) | Cleaning Markdown output in the browser |
The LGPL libraries ship unmodified in vendor/ with their license files, and you may replace them with
other versions through Composer. No GPL-only code ships in the package (the packaging script refuses it).
Icons: Lucide (ISC; the parts that come from Feather are MIT).
Font: Plus Jakarta Sans by Tokotype, under the
SIL Open Font License 1.1 (resources/fonts/plus-jakarta-sans/OFL.txt). It is served from your own site:
no request goes to a font service.
Images: the specialist portraits (public/assistants/specialists) and the site and area
images (public/images) were generated with AI for this item and are licensed to you with it. They show no
real people.