Agent Deployment Guide

Welcome to Infraveil! This guide breaks down everything you need to know to get your custom backend agent running. We've designed this process to be as simple and secure as possible, helping you get a production-ready backend live in just a few minutes.

The entire process revolves around a single, intelligent Python agent that you run on your own server. This gives you full control over your data and environment, while we handle the complex backend logic for you.

Don't worry if you make a mistake during setup. If an agent fails to connect or you run into issues, our system automatically invalidates it and emails you a new one. You have unlimited attempts to get it right.

This documentation was created to be fully AI-parsable so you can send it to a LLM of your choice.

DISCLAIMER: The agent itself is a Python script, but it acts as a bootstrapper. This means it can run backend logic written in any language—it's not limited to Python.

Prerequisites

Before we start, make sure you have these things ready:

  1. A Linux server. We highly recommend a recent LTS (Long Term Support) version of Debian or Ubuntu, as they are stable and well-documented. Your server should have Python 3 and its package installer, Pip, already installed.
  2. Root or sudo access to your server. This is just for the initial setup tasks, like creating users and installing software.
  3. The agent delivery email from Infraveil. This email contains your secure, one-time download link for the agent script.
  4. A registered domain name that you can point to your server's IP address (e.g., api.yourdomain.com).
  5. A way to transfer files to your server. Tools like FileZilla (for Windows/macOS/Linux) or WinSCP (for Windows) are great graphical options. If you're comfortable with the command line, you can use scp on macOS or Linux.

Step 1: Server Preparation

First, we'll set up a secure spot on your server for the agent to live. For security, it's crucial to run the agent as its own, limited user instead of as root. This isolates the agent and prevents it from accessing things it shouldn't.

1. Create a Dedicated User

We'll use infraveil-agent as the username in this guide. This command will also prompt you to create a secure password for the new user.

sudo adduser infraveil-agent

2. Create a Dedicated Directory

This is where the agent script and its assets will live. We'll create it and give ownership to our new user.

sudo mkdir -p /home/infraveil-agent/app
sudo chown -R infraveil-agent:infraveil-agent /home/infraveil-agent/app

Your server is now prepped and ready for the agent.

Step 2: Deploying the Agent

Your agent is delivered via a secure, one-time link. You'll download it to your local computer first, then securely transfer it to your server.

1. Download the Agent Locally

Open the email from Infraveil and click the secure download link. Save the agent.py file to a familiar location, like your Downloads folder.

This download link is ephemeral and valid for only one use. Please download the file promptly.

2. Transfer the Agent to Your Server

Use an SCP (Secure Copy) client to upload agent.py to the directory we created in Step 1. From a terminal on your local machine, run the following command, replacing the example paths and IP with your own.

For macOS or Linux:

scp /path/to/your/downloads/agent.py infraveil-agent@your_server_ip:/home/infraveil-agent/app/

For Windows, we recommend a graphical tool like WinSCP. Simply connect to your server and drag-and-drop the file into the /home/infraveil-agent/app directory.

3. Set Permissions on the Server

Now, connect to your server via SSH. We need to switch to our new user and make the agent script executable so it can be run.

# Switch to the new user
sudo su - infraveil-agent

# Navigate to the app directory
cd app

# Make the agent executable
chmod +x agent.py

Step 3: First Run & Initial Config

Running the agent for the first time kicks off a sequence to fetch and set up your application package. The agent will automatically install its own dependencies, like the requests and cryptography libraries.

1. Run the Agent

./agent.py

On its first run, the agent will:

  1. Send a secure heartbeat to our servers to validate itself.
  2. Fetch your unique, encrypted application package.
  3. Decrypt the package and extract its contents into a new Customization directory.
  4. Launch your backend logic.

2. Customize Your Configuration

After a moment, press Ctrl+C to stop the agent. You can now list the contents of the new directory (ls -l Customization/) to see your configuration files. The main file is typically config.json.

Let's open it with a simple text editor called nano:

nano Customization/config.json

You can now edit runtime parameters like the port. The contents will be specific to your build, but an example might look like this:

{
  "port": 5050,
  "endpoint": "/infratest",
  "message": "Infraveil Agent Test Passed!",
  "rate_limit": "5 per minute"
}

After editing, save the file and exit. In nano, press Ctrl+X, then Y to confirm, and finally Enter.

Step 4: Testing Your Agent (Local)

Before exposing your agent to the world, it's a good idea to test it locally on the server. This confirms the agent itself is working correctly before we add the complexity of a domain name and firewall.

1. Run the Agent Again

Start the agent manually one more time from the infraveil-agent user's session.

./agent.py

Leave this terminal window running.

2. Test with cURL

Open a second SSH connection to your server. In this new terminal, use the curl command to send a request directly to the agent. We use 127.0.0.1 (also known as "localhost") because the agent is only listening for connections from the server itself.

Use the port and endpoint from your config.json:

curl http://127.0.0.1:5050/infratest

If everything is working, you should see the success message from your config file printed in the terminal:

Infraveil Agent Test Passed!

Once you see this, you can go back to the first terminal and press Ctrl+C to stop the agent. The local test is complete!

Step 5: Domain & SSL Setup

Now we'll point your domain to the server and secure it with an SSL certificate. This enables encrypted https traffic, which is essential for production.

1. Point Your Domain's A Record

Log in to your domain registrar (where you bought your domain name). Go to the DNS management panel and create a new 'A' record.

  • Host/Name: Set this to your desired subdomain (e.g., api for api.yourdomain.com).
  • Value/Points to: Enter your server's public IP address.
  • TTL (Time to Live): You can usually leave this at the default setting.
DNS changes can take anywhere from a few minutes to a few hours to propagate across the internet.

2. Install Certbot for Let's Encrypt Certificates

Certbot is a fantastic tool that automates getting and renewing free SSL certificates from Let's Encrypt. We'll install it and the plugin for your web server (we'll use NGINX in this example).

# Exit the infraveil-agent session if you are still in it
exit

# Install certbot and the nginx plugin
sudo apt update
sudo apt install certbot python3-certbot-nginx -y

3. Obtain the SSL Certificate

Before running Certbot, you need to have a basic NGINX configuration file for your domain so Certbot knows what to do. We will create a more complete one later, but for now, a temporary one is needed.

# Create a basic config file
sudo nano /etc/nginx/sites-available/api.yourdomain.com

# Paste this inside, replacing the domain name:
server {
    listen 80;
    server_name api.yourdomain.com;
}

# Enable the site
sudo ln -s /etc/nginx/sites-available/api.yourdomain.com /etc/nginx/sites-enabled/

# Reload nginx to apply the change
sudo systemctl reload nginx

# Now, run certbot
sudo certbot --nginx -d api.yourdomain.com

Certbot will ask you a few questions, like your email address for renewal notices. It will then automatically obtain the certificate, update your NGINX configuration to use it, and set up a redirect from HTTP to HTTPS. Your connection is now ready to be secured!

Step 6: Production Service Setup

For production, we need the agent to run continuously as a background service (or "daemon"). This ensures it starts automatically when the server boots and restarts if it ever crashes.

1. Create a systemd Service File

Make sure you are logged in as your main user with sudo privileges, not the infraveil-agent user.

sudo nano /etc/systemd/system/infraveil.service

2. Add the Service Configuration

Paste the following configuration into the file. This template is pre-filled with the user and directory we created. It tells the system how to run and manage the agent securely.

[Unit]
Description=Infraveil Agent Service
After=network.target

[Service]
Type=simple
User=infraveil-agent
Group=infraveil-agent
WorkingDirectory=/home/infraveil-agent/app
ExecStart=/usr/bin/python3 /home/infraveil-agent/app/agent.py
Restart=on-failure
RestartSec=5s

[Install]
WantedBy=multi-user.target

Save and exit the editor (Ctrl+X, then Y, then Enter).

3. Enable and Start the Service

These commands tell the system to load, enable, and start your new service.

sudo systemctl daemon-reload
sudo systemctl enable infraveil.service
sudo systemctl start infraveil.service

4. Check the Status

Verify that it's running correctly.

sudo systemctl status infraveil.service

You should see an "active (running)" status in green. Your agent is now running persistently in the background.

Step 7: Reverse Proxy Configuration

Your agent is running on a local port (e.g., 127.0.0.1:5050). The final step is to use a web server like NGINX as a "reverse proxy." This securely forwards public traffic from your domain (https://api.yourdomain.com) to the local agent port.

NGINX Configuration

Certbot already created and configured our NGINX file for SSL. Now we just need to add the reverse proxy instructions to it.

sudo nano /etc/nginx/sites-available/api.yourdomain.com

Inside that file, find the server { ... } block that has listen 443 ssl; in it. Add the location / { ... } block shown below inside of it. This tells NGINX where to forward the traffic.

server {
    server_name api.yourdomain.com;

    # Add this location block
    location / {
        proxy_pass http://127.0.0.1:5050; # Make sure this port matches your config.json
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }

    # These lines were added by Certbot
    listen 443 ssl;
    ssl_certificate /etc/letsencrypt/live/api.yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/api.yourdomain.com/privkey.pem;
    include /etc/letsencrypt/options-ssl-nginx.conf;
    ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem;
}

# This server block was also added by Certbot to redirect HTTP to HTTPS
server {
    if ($host = api.yourdomain.com) {
        return 301 https://$host$request_uri;
    }

    listen 80;
    server_name api.yourdomain.com;
    return 404;
}

Finally, test the NGINX configuration for syntax errors and restart the service to apply the changes:

sudo nginx -t
sudo systemctl restart nginx

Step 8: Configuration & Updates

Your agent is designed to be flexible. This section covers how to change its runtime configuration and how core logic updates are handled.

Changing Runtime Configuration (Example: Port)

You can easily change any parameter in your config.json. Let's walk through changing the agent's port from 5050 to 4040.

  1. Stop the services. We need to stop both the agent and the NGINX web server before making changes. 
    sudo systemctl stop infraveil.service
sudo systemctl stop nginx
  2. Edit the agent config. Switch to the agent's user, navigate to the app directory, and open the config file. 
    sudo su - infraveil-agent
cd app
nano Customization/config.json
    Change the port value from 5050 to 4040, then save and exit (Ctrl+X, Y, Enter).
  3. Edit the reverse proxy config. The web server needs to know the new port. Switch back to your sudo user and edit the NGINX file. 
    # Exit the agent user's session
exit

# Open the NGINX config file
sudo nano /etc/nginx/sites-available/api.yourdomain.com
    Find the line proxy_pass http://127.0.0.1:5050; and change it to proxy_pass http://127.0.0.1:4040;. Save and exit.
  4. Restart and verify. Test the NGINX syntax, then start both services again. 
    sudo nginx -t
sudo systemctl start nginx
sudo systemctl start infraveil.service
    You can check the status of the agent with sudo systemctl status infraveil.service to ensure it started correctly.

Requesting Core Updates

To add new features or modify the core logic of your backend, a new application package must be engineered by our team. Please contact us with your requirements. We will build, test, and deliver an updated agent to you via a new secure email link.

Agent Recovery

If your agent goes offline for an extended period or your trial expires, our system will automatically lock the instance for security. You will receive an email containing a one-time recovery code. You can use this code on our website to request a fresh agent, which will be delivered to your email, allowing you to redeploy in seconds.

Step 9: Going Live

Congratulations. Your setup is complete.

You can now make requests to your new backend from anywhere. Based on our example configuration, sending a request to https://api.yourdomain.com/infratest will return the success message defined in your config file.

Your backend is now fully operational, secure, and managed. You can focus on building your frontend application while we ensure your backend infrastructure is always performing optimally.