Create custom apps in

Complete technical guide to develop, configure and publish Python applications inside a server. Designed for human developers and AI assistants who need to generate working apps from these instructions.

How the system works

Each custom app is a record of the CustomApp that contains:

nameApp display name (e.g. 'Sales Analysis')
descriptionBrief description shown in the Store and window
iconEmoji or URL of an uploaded image (desktop icon)
source_codeComplete Python code executed on Cloud Run
config_fieldsArray of configurable parameters (automatically generated form)
is_publishedtrue = visible on desktop and in server Store

When the user opens the app, the OSAppRunner displays a form generated from config_fields, replaces the placeholders {{PARAM_NAME}} in the code with the entered values, and sends the code to Cloud Run via the executeCodeReal.

Creation flow

1Open the Neuralai OS server and launch the "App Store" app
2Click the "Create App" button in the top right
3Choose an icon (emoji or uploaded image)
4Enter the app name and description
5Write the Python code in the "Python Code" field
6Click "Publish to Store" — the app appears on the desktop
7Open the app, fill in the parameters and press "Run"

Configurable parameters (config_fields)

The config_fields are an array of objects that define the form fields shown to the user. Each entered value is injected into the code by replacing the placeholder {{field_name}}.

Structure of each field:

{

"field_name": "API_KEY", // nome del placeholder {{API_KEY}} nel codice

"field_label": "Chiave API", // etichetta visibile nel form

"required": true, // campo obbligatorio

"placeholder": "inserisci qui...",// testo segnaposto

"description": "La tua chiave" // help sotto il campo

}

Complete example of config_fields for a CSV analysis app:

[

{

"field_name": "FILE_NAME",

"field_label": "Nome file CSV",

"field_type": "text",

"required": true,

"placeholder": "vendite.csv",

"description": "File caricato nel File Manager"

{

"field_name": "CHART_TYPE",

"field_label": "Tipo grafico",

"field_type": "text",

"required": false,

"placeholder": "bar",

"description": "line, bar, pie o scatter"

}

]

Note: the file field in field_type allows selecting a file from the File Manager. The injected value will be sandbox:/filename.ext and the content is accessible via SERVER_FILES.

Variables and special markers

SERVER_FILES

Automatic dictionary with the text content of File Manager files. Accessible without import.

csv = SERVER_FILES.get("dati.csv", "")

print(csv[:200])

SAVE_FILE

Save a text file to the File Manager by printing the special marker to stdout.

print("===SAVE_FILE:report.txt===")

print(contenuto)

print("===END_FILE===")

SAVE_IMAGE_URL

Save an image from URL to the File Manager (automatic download).

print(f"===SAVE_IMAGE_URL:logo.png:{url}===")

SAVE_FILE_URL

Save a URL link as a file in the File Manager (without downloading the content).

print(f"===SAVE_FILE_URL:video.mp4:{url}===")

Available Python libraries

Libreria	Utilizzo
`pandas`	DataFrames, CSV/Excel, data analysis
`numpy`	Numerical calculations, arrays, linear algebra
`matplotlib`	Graphs, visualizations, charts
`requests`	Synchronous HTTP calls, REST APIs
`beautifulsoup4`	HTML web scraping, DOM parsing
`httpx`	Asynchronous HTTP client, HTTP/2
`openpyxl`	Reading/writing Excel files (.xlsx)

Complete code examples

Example 1 — CSV Analysis with Chart

App with one parameter (file name) that reads a CSV, calculates statistics and saves a PNG chart.

config_fields:

[

{

"field_name": "FILE_NAME",

"field_label": "Nome file CSV",

"field_type": "text",

"required": true,

"placeholder": "vendite.csv"

}

]

source_code:

import pandas as pd

import io

import matplotlib

matplotlib.use("Agg")

import matplotlib.pyplot as plt

# {{FILE_NAME}} viene sostituito con il valore del form

csv_text = SERVER_FILES.get("{{FILE_NAME}}", "")

if not csv_text:

print("File non trovato nel File Manager")

else:

df = pd.read_csv(io.StringIO(csv_text))

print("Righe:", len(df))

print(df.describe())

# Genera grafico e salva come PNG

num_col = df.select_dtypes(include="number").columns[0]

df[num_col].plot(kind="bar", title=num_col)

plt.tight_layout()

plt.savefig("/tmp/chart.png")

print("===SAVE_IMAGE_URL:grafico.png:file:///tmp/chart.png===")

print("Grafico salvato nel File Manager")

Example 2 — External API call + report

App that calls a public API, processes the response and saves a TXT report.

config_fields:

[

{

"field_name": "CITY",

"field_label": "Citta",

"field_type": "text",

"required": true,

"placeholder": "Rome"

}

]

source_code:

import requests

# {{CITY}} viene sostituito con il valore del form

citta = "{{CITY}}"

url = f"https://wttr.in/{citta}?format=j1"

resp = requests.get(url, timeout=15)

if resp.ok:

data = resp.json()

current = data["current_condition"][0]

report = f"Meteo {citta}\n"

report += f"Temperatura: {current['temp_C']} C\n"

report += f"Umidita: {current['humidity']}%\n"

report += f"Descrizione: {current['weatherDesc'][0]['value']}\n"

print(report)

# Salva il report nel File Manager

print("===SAVE_FILE:meteo.txt===")

print(report)

print("===END_FILE===")

else:

print("Errore API:", resp.status_code)

Example 3 — Web scraping with BeautifulSoup

App that extracts title and paragraphs from a web page.

config_fields:

[

{

"field_name": "URL",

"field_label": "URL pagina",

"field_type": "url",

"required": true,

"placeholder": "https://example.com"

}

]

source_code:

import requests

from bs4 import BeautifulSoup

url = "{{URL}}"

resp = requests.get(url, timeout=15, headers={

"User-Agent": "Mozilla/5.0"

})

soup = BeautifulSoup(resp.text, "html.parser")

titolo = soup.find("title")

print("Titolo:", titolo.text if titolo else "N/D")

paragrafi = soup.find_all("p")[:5]

contenuto = f"Pagina: {url}\n\n"

contenuto += f"Titolo: {titolo.text if titolo else 'N/D'}\n\n"

for i, p in enumerate(paragrafi, 1):

contenuto += f"[{i}] {p.get_text(strip=True)}\n\n"

print(contenuto)

print("===SAVE_FILE:scraping.txt===")

print(contenuto)

print("===END_FILE===")

Instructions for AI assistants

An AI assistant can create a working app by following these rules:

1Write pure Python code, executable on Cloud Run (no shebang, no main guard needed)
2Use only libraries from the list above (pandas, numpy, matplotlib, requests, bs4, httpx, openpyxl)
3Define user parameters as config_fields and reference them in code with {{FIELD_NAME}}
4For server files use SERVER_FILES.get("name.ext", "") — never direct open() to read
5To save output use markers ===SAVE_FILE:name=== / ===END_FILE=== (text) or ===SAVE_IMAGE_URL:name:url=== (images)
6Everything printed with print() appears in the app output
7Handle errors with try/except and print clear messages (the user sees them)
8Code must be self-contained: no local file imports, no unlisted external dependencies

Custom app billing

Le app personalizzate usano lo stesso billing di tutte le app del server: 1 token/minuto di esecuzione e 2 token/file creato nel File Manager. L'uptime del server (5 token/ora con Cloud Run ON) è già attivo. Non ci sono costi extra per la creazione o la pubblicazione di un'app.