Flux Specification Reference

Complete reference for the Flux deployment specification format (version 8)

Basic Structure

Complete Spec Example (Version 8)json

{
  "version": 8,
  "name": "myapp",
  "description": "Application description",
  "owner": "ZELID_ADDRESS",
  "instances": 3,
  "staticip": false,
  "enterprise": "",
  "compose": [
    {
      "name": "component1",
      "description": "Component description",
      "repotag": "username/image:tag",
      "ports": [3000],
      "containerPorts": [3000],
      "domains": [""],
      "environmentParameters": [
        "KEY=value"
      ],
      "commands": [],
      "containerData": "/appdata",
      "cpu": 2.0,
      "ram": 4000,
      "hdd": 10,
      "tiered": false
    }
  ]
}

Field Reference

versionnumberrequired

Specification version. Use 8 for latest features (instances, staticip, enterprise).

Example: 8

namestringrequired

Unique application name. Must be unique across Flux network. Alphanumeric characters only (a-z, A-Z, 0-9). No hyphens, underscores, or spaces.

Example: "myapp"

instancesnumberrequired

Number of redundant copies of your app. Minimum is 3. Additional instances cost ~$0.50 for small apps or basePrice/3 for larger apps.

Example: 3

staticipbooleanrequired

Restrict deployment to nodes with static IP addresses. Increases deployment cost based on application resources. Useful for apps requiring consistent external IP.

Example: false

enterprisestringrequired

Deploy to ArcaneOS enterprise nodes with enhanced security: OS-level encrypted volumes where node operators cannot access your data, support for private Docker images, and encrypted environment secrets. Set to 'enabled' or empty string ''. Increases deployment cost based on application resources.

Example: ""

descriptionstringrequired

Human-readable description of your application.

Example: "My awesome blockchain application"

ownerstringrequired

Your ZelID address from Zelcore wallet. This identifies you as the app owner.

Example: "1ABC...xyz"

composearrayrequired

Array of component specifications. Each component represents a Docker container.

Component Fields

namestringrequired

Component name. Used in internal DNS: flux{name}_{appname}

Example: "postgres"

repotagstringrequired

Docker image reference. Must be publicly accessible.

Example: "postgres:15-alpine" or "username/myapp:latest"

portsarray of numbersrequired

Array of external port numbers exposed to the internet. Valid range: 0-65535. Ports <1024, 8080, 8443, or 9090 require enterprise mode and add $2/port.

Example: [3000, 8080]

containerPortsarray of numbersrequired

Array of ports your application listens on inside the container. Valid range: 0-65535. Must match the length of 'ports' array.

Example: [3000, 8080]

domainsarray of stringsrequired

Array of custom domains for each port. Leave as empty strings to use Flux-assigned domains. Must match the length of 'ports' array.

Example: ["", "mydomain.com"]

cpunumberrequired

Number of CPU cores. Minimum 0.5, increment by 0.5.

Example: 2.0

ramnumberrequired

Memory in megabytes (MB). Minimum 512.

Example: 4096

hddnumberrequired

Disk space in gigabytes (GB). Minimum 1.

Example: 10

environmentParametersarray

Array of environment variables in KEY=value format.

Example: ["NODE_ENV=production", "PORT=3000"]

containerDatastringrequired

Path to persistent data volume inside container. Required field. Use '/appdata' for general apps or specific paths like '/var/lib/postgresql/data' for databases.

Example: "/appdata"

commandsarray

Override container CMD. Usually empty to use Dockerfile CMD.

Example: []

tieredboolean

Whether to allow deployment on different node tiers. Usually false.

Example: false

Common Patterns

Multi-Component Internal Communication

Components use internal DNS to communicate. For app named "myapp" with components "db" and "api":

# API connects to database using:
DB_HOST=fluxdb_myapp
DB_PORT=5432

# Full connection string:
postgresql://user:pass@fluxdb_myapp:5432/dbname

Container Data Volume Prefixes

Flux supports special volume prefixes that enable data synchronization and sharing across instances. Understanding these prefixes is crucial for multi-instance deployments.

g:/

Global Syncthing (Primary/Standby)

Enables data synchronization with a primary/standby (master/slave) architecture. Only ONE instance acts as the primary writer, while others maintain read-only synchronized replicas.

• Sync mode: Primary (write) + Standby (read-only replicas)
• Use case: Single-writer databases, applications requiring data consistency
• Auto-restart: No (uses restart policy "no")
• Pricing: 20% discount on base price
• Failover: If primary fails, a standby can be promoted

Examplejson

{
  "containerData": "g:/var/lib/postgresql/data"
}

r:/

Read-Write Syncthing (Replica)

Enables bidirectional data synchronization. All instances can read and write to their local copies, with changes propagating to all other instances.

• Sync mode: Bidirectional (all instances can write)
• Use case: Distributed file systems, shared application data
• Auto-start: No (containers not automatically started)
• Conflict resolution: Handled by Syncthing

Examplejson

{
  "containerData": "r:/app/shared-data"
}

s:/

Standard Syncthing

Basic Syncthing synchronization with standard behavior.

• Sync mode: Bidirectional synchronization
• Auto-restart: Yes (unless-stopped)

Examplejson

{
  "containerData": "s:/data"
}

0:/ 1:/ 2:/

Component Volume Mounting

Mount volumes from other components within the same multi-component application. The number represents the component index to mount from.

• Requirements: Version 4+ applications (compose apps only)
• Limitation: Components can only mount from lower-numbered components
• Use case: Sharing data between microservices (e.g., API accessing database files)
• Syntax: Separate multiple volumes with |

Example: Multi-volume setupjson

{
  "compose": [
    {
      "name": "database",
      "containerData": "g:/var/lib/postgresql/data"
    },
    {
      "name": "api",
      "containerData": "/app/data|0:/db-data"
    }
  ]
}

In this example, component 1 (api) mounts component 0's (database) volume at /db-data

No prefix

Standard Local Volume

Standard Docker volume with no synchronization. Each instance has independent, isolated data.

• Sync mode: None (independent volumes per instance)
• Auto-restart: Yes (unless-stopped)
• Use case: Stateless apps, cache directories, temporary data
• Warning: Data is lost if instance is destroyed

Examplejson

{
  "containerData": "/appdata"
}

Volume Prefix Comparison

Prefix	Syncthing	Sync Mode	Auto-Restart	Discount
`None`	No	None	Yes	-
`s:/`	Yes	Bidirectional	Yes	-
`r:/`	Yes	Bidirectional	No	-
`g:/`	Yes	Primary/Standby	No	20%
`0:/ 1:/ etc.`	N/A	Component mount	N/A	-

Important Notes:

• Using g:/ prefix provides a 20% discount on your base deployment cost
• Component mounting (0:/, 1:/, etc.) only works in multi-component applications (version 4+)
• Higher-numbered components can only mount volumes from lower-numbered ones
• Syncthing prefixes provide data redundancy across instances
• Without a sync prefix, data is isolated per instance and lost if the instance fails

Validation Rules

• App name must be unique across the entire Flux network
• App name must contain only alphanumeric characters (a-z, A-Z, 0-9) - no hyphens, spaces, or special characters
• Component names must be unique within the app
• Minimum 3 instances required
• Enterprise field must be either "enabled" or empty string ""
• ports, containerPorts, and domains arrays must have matching lengths
• Privileged ports (<1024, 8080, 8443, 9090) require enterprise mode
• CPU can increment by 0.1 (e.g., 0.1, 0.5, 1.0, 2.5, etc.)
• RAM increments by 100 MB (e.g., 100, 1000, 2000, 4000, etc.)
• Storage (hdd) must be at least 1 GB
• Docker image must be publicly accessible (unless using enterprise mode)
• Port numbers must be valid (1-65535)
• Environment variables must be in KEY=value format
• containerData path is required (use /appdata if unsure)

Enterprise Mode & ArcaneOS Nodes

What is Enterprise Mode?

Enterprise mode deploys your application exclusively to ArcaneOS nodes - specialized Flux nodes that provide enhanced security features for sensitive applications.

Set enterprise: "enabled" in your spec to enable enterprise mode. Enterprise mode increases deployment cost based on application resources.

🔒 OS-Level Encrypted Volumes

ArcaneOS nodes run a specialized operating system with full-disk encryption. Your application data is encrypted at the OS level, meaning:

• Node operators cannot access your data - Even the physical server owner cannot read your encrypted volumes
• Automatic encryption - All containerData volumes are encrypted without additional configuration
• Protection at rest - Data is encrypted when stored on disk
• Decrypted only in memory - Your application accesses unencrypted data in RAM during execution

🔐 Encrypted Environment Secrets

Environment variables containing sensitive data (API keys, passwords, database credentials) are encrypted when stored on ArcaneOS nodes:

Environment secrets are encryptedjson

{
  "environmentParameters": [
    "DATABASE_PASSWORD=supersecret123",
    "API_KEY=sk-proj-abc123xyz",
    "JWT_SECRET=my-signing-key"
  ]
}

These secrets are encrypted at rest and only decrypted when passed to your container at runtime.

📦 Private Docker Images

Enterprise mode allows you to use private Docker images from registries like:

• GitHub Container Registry (ghcr.io)
• GitLab Container Registry
• Private Docker Hub repositories
• Self-hosted registries

Using private imagesjson

{
  "name": "privateapp",
  "enterprise": "enabled",
  "compose": [{
    "repotag": "ghcr.io/yourorg/private-app:latest",
    ...
  }]
}

When to Use Enterprise Mode

Consider enterprise mode for applications that handle:

✓ Sensitive user data (PII, health records, financial information)
✓ Private business logic in proprietary Docker images
✓ API keys and credentials that must remain confidential
✓ Compliance requirements (GDPR, HIPAA, SOC 2)
✓ Applications where node operator trust is a concern

Cost: Enterprise mode increases deployment cost based on application resources (scales with CPU, RAM, and storage).

Pricing Calculation

Base pricing formula (per month):

basePrice = (CPU × $0.15 × 10) + (RAM_MB × $0.05 ÷ 100) + (HDD × $0.02)

Additional costs:

• Static IP: Increases cost based on application resources
• Enterprise: Increases cost based on application resources
• Additional instances (small apps <$1.50): +$0.50 per instance
• Additional instances (larger apps): +(basePrice ÷ 3) per instance

Tier discounts:

• Small apps (CPU <3, RAM <6000 MB, HDD <150 GB): 20% discount
• Medium apps (CPU <7, RAM <29000 MB, HDD <370 GB): 10% discount

* When paying with FLUX tokens, you get an additional 5% discount. Prices are calculated in USD then converted to FLUX using current market rates.