Skip to main content
The Perfai appliance is a ready-made virtual machine image. You launch it in your own AWS account. It installs the full platform by itself on first start, and your data stays in your account.

What you need

Launch the instance

  1. Subscribe to Perfai in AWS Marketplace and choose Launch.
  2. Choose the instance type, a key pair, a subnet with a public IP, and a security group with the ports above.
  3. Attach an IAM role to the instance that allows Bedrock access (bedrock:InvokeModel, bedrock:InvokeModelWithResponseStream and bedrock:Converse). The appliance uses the instance role, so you do not store AWS keys on the machine.
  4. Set the disk size to 100 GB or more, then launch.
First start takes about 15 to 20 minutes. The appliance finds its own address, creates all of its secrets, and installs the platform. Nothing that identifies a customer is built into the image, so every instance gets its own keys.

Check progress

Open http://<instance address>:9080 for the status page, or sign in over SSH (user ubuntu) and run:
The status is starting while it installs and healthy when every service is ready. Port 9080 shows status only. Open it just to the people who need it.

Sign in

By default the appliance uses the address <ip-with-dashes>.sslip.io and a certificate it created itself, so your browser shows a warning until you add your own certificate (next section).
  1. Open https://cloud.<your domain>.
  2. Sign in as admin@perfai.ai. The generated password is the GLOBAL_WEBAPP_ADMIN_PASSWORD value in /opt/perfai/lifecycle/config/perfai-secrets.env (readable by root only):
  1. Change the password when the console asks you to.
Keep a copy of that file in a safe place. It holds the keys for your data.

Use your own domain and certificate

  1. Create two DNS records that point to the instance: <your domain> and *.<your domain> (a wildcard).
  2. Put the domain in /etc/perfai/appliance.env before first start, or switch later with the command below.
  3. Get a certificate that covers *.<your domain>. A wildcard certificate from a public authority works, and so does one from your own CA.
  4. Load it:
If your certificate comes from a private CA, add --ca ca.pem. Without it, the services inside the platform cannot trust each other.

Back up

Backups are saved in /var/lib/perfai/backups. Copy them off the machine. Take one before every upgrade.

Upgrade without losing data

You choose how to upgrade.
  • New image and restore (recommended). Launch the new image, copy your data keys and a backup to it, and restore. This also updates the operating system and security hardening. You keep the old machine until you switch your users over, so you can go back at any time.
  • Upgrade in place. Install a signed release folder with sudo perfai-upgrade --release <folder>. The appliance checks the release signature and every file checksum, backs up first, upgrades, and then checks that no database collection lost any documents. If a check fails, it stops and tells you how to put the previous release back.
  • Automatic upgrade (optional, off by default). Turn it on with sudo perfai-auto-upgrade --enable. Every night it reads the signed Perfai release feed and installs a newer release only if the signature is valid. It never goes down to an older release.
Plan for 10 to 30 minutes of downtime. Scans that are running when an upgrade starts are interrupted. In-place upgrades need 30 GB of free disk space. Your data is protected by three keys (FIELD_ENCRYPTION_SECRET, SECRET_KEY and IV). A restore refuses to run if the new machine’s keys do not match the backup, so encrypted data is never restored unreadable. Export the keys with sudo perfai-backup --export-secrets <file>. Never put these keys in instance user data.

Get help

Contact Perfai support through your account team, and include the output of sudo perfai-health --print.