Are you a system administrator or a web developer (backend, frontend, or fullstack) looking for a project that goes beyond the usual stack?
apXtri is an open-source infrastructure designed to create a decentralized economy around hosting, development, and community management.

With apXtri, you can:

Host web apps, APIs, and pages for groups (tribes) on your own servers (towns).
Manage encrypted identities via PGP for users (pagans), ensuring anonymity and security.
Define and enforce nested rules (tribe → town → nation) automatically recorded on a blockchain.
Generate and exchange tokens to pay for hosting, dev, or community services.
Create traceable digital contracts and handle disputes through decentralized arbitration.

👉 In short: apXtri is your toolbox to launch a decentralized SaaS platform.

⚙️ Tech stack (100% open source & auditable)

Ubuntu LTS (desktop for dev, server for production)
Caddy: native HTTPS & reverse proxy
Node.js / Express.js: RESTful endpoints
JSON Schema: structured data management
Internal blockchain: rules & traceability

🏗️ Architecture Overview

Multi-tenant Hierarchy

🌍 Nation (Network)
 └── 🏛️ Towns (Servers)
      └── 👥 Tribes (Communities)
           └── 🔑 Pagans (Users with PGP identities)

New Directory Structure

/opt/apxtowns/{TOWN}.{NATION}/           # Code directory
├── apxtri/                              # Core runtime
│   ├── apxtri.js                        # Main entry point
│   ├── models/                          # Business logic
│   ├── routes/                          # API endpoints
│   ├── middlewares/                     # Auth middleware
│   ├── schema/                          # JSON Schema definitions
│   └── setup/                           # Installation scripts
│
/var/lib/apxtowns/{TOWN}.{NATION}/      # Data directory
├── {tribe}/                             # Tribe namespace
│   ├── objects/{objname}/itm/           # JSON database
│   └── wwws/{app}/                      # Webapp runtime
│
/opt/apxtowns/{TOWN}.{NATION}/{tribe}/  # Webapp source
└── wwws/{app}/src/                     # Templates, styles, scripts

Web Application Routing

Webapps served via path-based routing /{webapp}/* or custom DNS if dns field set in appconf.json

Example: /{app}/* → webapp in dev tribe
Each webapp has appconf.json with configuration
Caddy auto-discovers and routes traffic

🛠️ Quick Installation

Requirements:

Ubuntu LTS 22.04+ (Desktop for dev, Server for prod)
Physical or VM: 8 GB RAM / 500 GB SSD minimum
Sudo-enabled user
Public domain name (for production) that reach the IP server

For dev: see Step 3A to install a LXC container

Step 1: Create Sudo User (if needed)

# Create user (replace {user} with your username)
sudo adduser {user}
sudo passwd {user}
sudo usermod -aG sudo {user}
groups {user}  # Verify: should show "{user} : {user} sudo users"
su - {user}    # Switch to new user

Step 2: Download and Run Installer

# Download and run init.sh
sudo apt install wget -y && \
sudo wget -O init.sh https://gitea.ndda.fr/apxtri/apxtri/raw/branch/main/setup/init.sh && \
sudo chmod +x init.sh

./init.sh --town {yourtownname} --nation {yournationname} --domain {domainName}

Options:

./init.sh --town mytown --nation test - install dev without domain name
./init.sh --clean - ⚠️ Erase all data and reinstall

Step 3: Production Management

# After installation, complete setup via web interface
# Then run post-setup:
sudo /opt/apxtowns/{TOWN}-{NATION}/apxtri/setup/post-setup.sh

# Manage service
sudo systemctl {start|stop|restart} apxtri

Automated Features:

Daily blockchain backups (1:00 AM)
System updates via git pull (3:00 AM)
Auto-restart on failure
SSL certificate renewal (Let's Encrypt)

🛠️ Installation for dev

Advice to developer that use ubuntu, host on your machine a LXC container, nation name "zero" is the testing blockchain. To join you must create a town that not already exist. Get a domain name and be sure the router redirect to your machine.

sudo snap install lxd
sudo lxd init
sudo lxc image list ubuntu:
sudo lxc launch ubuntu:24.04 dev-zero
sudo lxc stop dev-zero
sudo lxc start dev-zero
sudo lxc exec dev-zero -- /bin/bash
Dans le contaiiner:
apt update && apt install -y openssh-server curl git

sudo vim /etc/ssh/sshd_config (set PermitRootLogin yes)
sudo vim /etc/hosts  (add line with LXC IP: 10.42.129.57 dev-zero)
ping dev-zero must answer

Network conf CASE 1 The dev Machine host the LXC container. Architecture: Machine H (LXC Host): 192.168.1.96 (bond0 interface) LXC X (Container): 10.31.251.161 (lxdbr0 interface)

On LXC X: Generally, no action is required if the container uses the host as its default gateway (which is the standard behavior with lxdbr0).

Network conf CASE 2 The dev Machine is outside of the server that host the LXC container Architecture: Machine C (Local Client): 192.168.1.104 Machine H (LXC Host): 192.168.1.96 (bond0 interface) LXC X (Container): 10.31.251.161 (lxdbr0 interface) On Machine C: Define the routing path

# Add the route to the LXC subnet via the host IP:
sudo ip route add 10.31.251.0/24 via 192.168.1.96

# Verify that the route is active:
ip route get 10.31.251.161
# The output should show: via 192.168.1.96 dev <your_interface>

On Machine H: Enable IP forwarding and configure the firewall

# Check forwarding status (should be 1): 
cat /proc/sys/net/ipv4/ip_forward
# If it is 0, enable it immediately:  
sudo sysctl -w net.ipv4.ip_forward=1
# 1. Allow OUTBOUND traffic (Machine C -> LXC)
sudo iptables -I FORWARD 1 -s 192.168.1.104 -d 10.31.251.0/24 -j ACCEPT
# 2. Allow INBOUND/RETURN traffic (LXC -> Machine C)
sudo iptables -I FORWARD 2 -s 10.31.251.0/24 -d 192.168.1.104 -j ACCEPT
# Make these rules persistent (requires iptables-persistent)
sudo netfilter-persistent save

Troubleshooting Tools: On Machine C: ```bash traceroute -n 10.31.251.161

The first hop should be 192.168.1.96 On Machine H: ```bash sudo tcpdump -i bond0 icmp # If packets are visible => Machine C is correctly configured sudo tcpdump -i lxdbr0 icmp # If packets are visible => Machine H is correctly configured

Step 2: Create Sudo User (inside LXC)

# Create user (replace {user} with your username)
sudo adduser {user}
sudo passwd {user}
sudo usermod -aG sudo {user}
groups {user}  # Verify: should show "{user} : {user} sudo users"
exit

# Create an authentification key for your dev machine if not already exist
ssh-keygen -t ed25519 -C "userdevfix"
sudo lxc exec dev-zero -- mkdir -p /home/phil/.ssh
sudo lxc file push ~/.ssh/id_ed25519.pub dev-zero/home/phil/.ssh/authorized_keys
sudo lxc exec dev-zero -- chown -R phil:phil /home/phil/.ssh
sudo lxc exec dev-zero -- chmod 700 /home/phil/.ssh
sudo lxc exec dev-zero -- chmod 600 /home/phil/.ssh/authorized_keys
ssh phil@dev-zero  # should open the console

Step 3: Download and Run Installer (inside LXC)

# Download and run init.sh
sudo apt install wget -y && \
sudo wget -O init.sh https://gitea.ndda.fr/apxtri/apxtri/raw/branch/main/setup/init.sh && \
sudo chmod +x init.sh
# Follow the production process to step 1 and use the same user both in host and LXC container
# ...
./init.sh --town {yourtownname} --nation {yournationname} --domain {domainName} --trusted-proxy-ips {IP4host}

🎯 Why join apXtri?

🧩 For sysadmins: a ready-to-install, auditable, and scalable project.
💻 For developers: a playground to build apps, endpoints, and interfaces in a decentralized environment.
🌍 For communities: an ecosystem outside centralization, giving power back to users.

🤖 AI-Assisted Development with OpenCode

apxtri is configured for AI-assisted development using OpenCode. The project uses agents, skills, and rules to provide contextual AI help for every part of the codebase.

Quick Start

# From the project root (/opt/apxtowns/{TOWN}.{NATION})
opencode

Available Agents

Agent	Use case
`@be-apxtri`	Backend core — routes, models, middlewares
`@schema`	Odmdb schema creation and optimization
`@be-dev`	Backend for the dev tribe

Example Prompts

@schema create a products collection with price and category
@be-apxtri add CRUD routes for products with tplstrings
@be-dev list persons from the dev tribe

How It Works

Each repo (apxtri/, dev/, etc.) contains its own .opencode/ folder with skills and agents
On server start, _syncOpenCode() merges everything into the root .opencode/
opencode.json configures OpenCode to load all AGENTS.md files

See documents/04-AIOPENCODE.md for the full documentation.

Agent Permissions

Agents ship with a strict permission profile: any bash command that is not explicitly allowed asks for confirmation, and any path outside the project directory ({DATAPATH}/**, tribe code, /etc/caddy/**) asks for approval — OpenCode's built-in external_directory default, which the strict templates do not override. Each town may relax or tighten this for its own agents with a single optional file:

{DATAPATH}/{TOWN}/opencode-permissions.json

apxtri.js::_injectAgentPermissions() injects it into the generated {NODEPATH}/.opencode/agents/*.md on every server start. The file belongs to the town's mayor: edit it to change the level, or delete it to fall back to strict. sudo always stays on approval.

Nation zero — experimental convention

Nation zero is the one exception, by convention: it is declared hackable and at risk, its token carries no value, and this is known by everyone on purpose. It is the playground where the protocol can be broken safely, and its towns ship a relaxed agent permission profile (ordinary shell work runs without prompts, reads and writes outside the project directory run without prompts, destructive commands are denied, /etc/caddy/** and sudo still ask, /root/ and ~/.ssh/ are denied).

Every other nation is production-grade and keeps the strict profile. Never rely on nation zero for anything of value, and never copy its settings to another nation without an explicit decision by that nation's mayor.

external_directory rules are matched against the parent directory of the accessed path (dirname(<path>) + "/*"), not the file itself, so a rule that names a file directly inside a directory — /etc/shadow*, for instance — never matches. Gate the directory (/etc/*) instead. See AGENTS.md.

❓ FAQ

Q: Do I need blockchain expertise to run apXtri?
A: No. The blockchain is managed automatically by each town node. You only need basic sysadmin skills.

Q: Can I use apXtri for private projects?
A: Yes. Tribes can be public or private (invite-only).

Q: What happens if my server goes offline?
A: Each town manages its own data. If your node goes offline, your hosted tribes become unavailable, but other towns remain unaffected.

Q: Can I integrate my own apps or APIs?
A: Absolutely. Add webapps to {tribe}/wwws/{app}/ and they'll be auto-discovered.

Q: Is there a way to contribute as a developer?
A: Yes. Build web interfaces, extend APIs, or improve the core. Contributions welcome!

Ready to build your digital nation? 👉 Start here