Application Manifest (app.toml)

Every application deployed to MicroFly must contain an app.toml configuration file in its root directory. MicroFly strictly parses and validates this file prior to staging any release.

Unknown fields or invalid values cause immediate deployment rejection to prevent configuration drift.

---

Full Example Manifest

schema_version = 1
name = "api-service"
type = "binary"
domain = ["api.example.com", "*.api.internal.net"]

[runtime]
args = ["./bin/server", "--config", "config.json", "--port", "{PORT}"]
workdir = "."
env = { "LOG_LEVEL" = "info", "CACHE_ENABLED" = "true" }

[scale]
scale_to_zero = true
idle_timeout = "2m"
min_instances = 0
max_instances = 1

[health_check]
path = "/healthz"
expected_status = 200
interval = "150ms"
timeout = "5s"
initial_delay = "0s"

[storage]
mounts = [
  { source = "sqlite.db", target = "data/app.db" },
  { source = "uploads", target = "public/uploads" }
]

[preview]
ttl = "48h"

[resources]
memory_limit = "512MB"
memory_soft = "384MB"
cpu_quota = 1.5
pids_max = 200
nofile = 2048
request_body_limit = "15MB"
storage_limit = "2GB"

[deploy]
release_command = ["./bin/server", "migrate"]

[webhook]
enabled = true
repository = "my-org/api-service"
branch = "main"
secret = "env:WEBHOOK_SECRET"

[[cron]]
name = "daily-cleanup"
schedule = "0 3 * * *"
command = ["./bin/server", "cleanup-cache"]

[[cron]]
name = "hourly-sync"
schedule = "0 * * * *"
command = ["./bin/server", "sync-metrics"]

---

Field Reference

Root Fields

Field	Type	Required	Default	Description
schema_version	Integer	Yes	-	Must be 1.
name	String	Yes	-	Application identifier (1-63 lowercase alphanumeric chars and hyphens).
type	String	Yes	"binary"	Workload type: "binary", "java" (JAR), or "static" (static web app / SPA).
domain	Array of Strings	Yes	-	List of hostnames or wildcard domains (*.example.com) routed to this app.

---

[static]

Configures static file hosting and HTTP cache headers for type = "static".

Field	Type	Default	Description
directory	String	"."	Path to static assets relative to release root (e.g. "dist", "public").
index	String	"index.html"	Default directory index file name.
spa	Boolean	false	When true, routes missing non-file paths to index.html for client-side routers.
clean_urls	Boolean	false	When true, resolves extensionless paths like /about to /about.html.
cache_control	String	"public, max-age=3600"	Default Cache-Control header for standard assets.
asset_cache_control	String	"public, max-age=31536000, immutable"	Long-term immutable Cache-Control for fingerprinted assets.
html_cache_control	String	"no-cache, must-revalidate"	Cache-Control applied to HTML entrypoints and SPA fallback routes.
asset_patterns	Array of Strings	["/assets/*", "*.js", ...]	Glob patterns matching fingerprinted assets.
headers	Table	{}	Custom HTTP response headers (e.g. security headers).

---

[runtime]

Controls process execution and startup parameters.

Field	Type	Default	Description
args	Array of Strings	Required	Command line arguments. The token {PORT} is dynamically replaced with the assigned unprivileged port.
workdir	String	"."	Working directory relative to the release root.
env	Table	{}	Static environment key-value pairs.
uid	Integer	0 (Auto)	Explicit POSIX UID. If 0, MicroFly resolves a stable system account (microfly-app).
gid	Integer	0 (Auto)	Explicit POSIX GID. If 0, matches UID.

---

[scale]

Controls scale-to-zero and automatic lifecycle behavior.

Field	Type	Default	Description
scale_to_zero	Boolean	false	When true, stops the application when idle.
idle_timeout	Duration String	"5m"	Inactivity duration before stopping the process (e.g. "30s", "5m", "1h").
min_instances	Integer	0	Minimum active instances (0 for scale-to-zero, 1 for always running).
max_instances	Integer	1	Maximum active instances per application (currently fixed to 1 on single-host).

---

[health_check]

Configures the pre-flight health probe required before traffic switches to a new release.

Field	Type	Default	Description
path	String	""	HTTP path to probe (e.g., "/healthz"). If empty, TCP socket connect is used.
expected_status	Integer	200	HTTP response code required to declare the workload healthy.
interval	Duration String	"100ms"	Frequency of health check polling during startup.
timeout	Duration String	"10s"	Maximum duration allowed for the app to become healthy before rolling back.
initial_delay	Duration String	"0s"	Grace period to wait before initiating the first probe.

---

[storage]

Configures persistent storage volumes that persist across releases and rollbacks.

[storage]
mounts = [
  { source = "database", target = "data/db" }
]

• source: Path relative to the application's persistent storage root (/var/lib/microfly/apps/<app>/shared/storage/).
• target: Path inside the release directory where the volume will be mounted.

---

[preview]

Configures ephemeral branch preview environments.

Field	Type	Default	Description
ttl	Duration String	"48h"	Time-to-live before preview applications are automatically swept by the cleaner.

---

[resources]

Enforces kernel-level resource limits via Linux cgroups v2.

Field	Type	Default	Description
memory_limit	String	Unlimited	Hard memory limit (e.g., "256MB", "1GB"). Exceeding triggers Linux OOM killer.
memory_soft	String	Unlimited	Soft memory limit (cgroup memory.high) triggering memory reclamation.
cpu_quota	Float	Unlimited	CPU cores quota (e.g., 1.0 = 1 full core, 0.5 = 50% of one core).
pids_max	Integer	Unlimited	Maximum concurrent threads/processes allowed in the unit.
nofile	Integer	1024	Maximum open file descriptors (ulimit -n).
request_body_limit	String	"10MB"	Maximum HTTP upload body size accepted by ingress.
storage_limit	String	Unlimited	Maximum disk usage allowed for the application's persistent storage.

---

[network]

Configures kernel-level eBPF socket filtering and network isolation via systemd (IPAddressAllow= / IPAddressDeny=).

Field	Type	Default	Description
allow_outbound	Boolean	true	When false, blocks all outbound network connections; the application can only receive ingress traffic on localhost.
deny_private_networks	Boolean	false	When true, blocks egress to RFC 1918 private subnets (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, 169.254.0.0/16).
allowed_egress	Array of Strings	[]	Explicit list of CIDR prefixes allowed for outbound connections (e.g. ["1.1.1.1/32"]).
denied_egress	Array of Strings	[]	Explicit list of CIDR prefixes denied for outbound connections.

---

[deploy]

Field	Type	Default	Description
release_command	Array of Strings	[]	One-off command executed inside the candidate release before health checks (e.g., database migrations). If it exits non-zero, deployment aborts immediately.

---

[webhook]

Configures Git webhook automation (GitHub / GitLab).

Field	Type	Default	Description
enabled	Boolean	false	Enables the webhook endpoint (POST :8082/api/webhooks/<app>).
repository	String	""	Expected repository name (e.g. "owner/repo").
branch	String	"main"	Monitored branch for automatic deployments.
secret	String	""	Webhook HMAC secret reference (e.g. "env:WEBHOOK_SECRET").

---

[[cron]]

Defines scheduled tasks executed in the background inside the application environment. Multiple [[cron]] tables can be defined.

Field	Type	Required	Description
name	String	Yes	Name of the scheduled job.
schedule	String	Yes	Standard 5-field cron expression in UTC (e.g., "*/15 * * * *").
command	Array of Strings	Yes	Command line arguments to execute.