MicroFly

Appearance

Admin REST API ​

The MicroFly daemon exposes a comprehensive REST API over a root-only Unix domain socket located at: /run/microfly/admin.sock

Authentication & Security ​

  • Transport: Unix domain socket only. No unauthenticated TCP sockets are opened for the Admin API.
  • Peer Credentials: MicroFly uses Linux kernel SO_PEERCRED checks to verify that connecting processes run with UID 0 (root). Unprivileged processes receive immediate connection termination.
  • Curl Usage: Use curl --unix-socket /run/microfly/admin.sock http://microfly/<endpoint>.

Endpoints Summary ​

System Health & Diagnostics ​

Health Check ​

http
GET /healthz
  • Response: 200 OK (text/plain: ok) if the daemon is operational.

System Information ​

http
GET /api/system
  • Response: 200 OK
    json
    {
  "version": "0.1.0",
  "go_version": "go1.27.0",
  "os": "linux",
  "arch": "amd64",
  "runner": "systemd",
  "ingress_address": "127.0.0.1:8000",
  "admin_socket": "/run/microfly/admin.sock",
  "webhook_address": "127.0.0.1:8082",
  "metrics_address": "127.0.0.1:9090",
  "data_dir": "/var/lib/microfly/apps",
  "apps_count": 5,
  "previews_count": 2
}

Applications ​

List Applications ​

http
GET /api/apps
  • Response: 200 OK with a JSON array of all registered applications:
    json
    [
  {
    "name": "my-app",
    "type": "binary",
    "status": "running",
    "release": "20260903T101530-000001",
    "port": 3000,
    "pid": 78912,
    "memory_rss": 5368709,
    "domains": ["api.example.com"],
    "restart_count": 0
  }
]

Application Details ​

http
GET /api/apps/{name}
  • Response: 200 OK with the application status object.

Deploy Release (Tarball or Git Ref) ​

http
POST /api/apps/{name}/deploy
Content-Type: application/x-tar  (or application/json for Git refs)
  • Payload (Git Ref):
    json
    {
  "git_ref": "3f8a1d4...",
  "branch": "feature/login"
}
  • Response: 200 OK
    json
    {
  "app": "my-app",
  "release": "20260903T101530-000001"
}

Restart Application ​

http
POST /api/apps/{name}/restart
  • Response: 200 OK

Stop Application ​

http
POST /api/apps/{name}/stop
  • Response: 200 OK

Start Application ​

http
POST /api/apps/{name}/start
  • Response: 200 OK

Rollback Application ​

http
POST /api/apps/{name}/rollback
  • Payload (Optional): {"release_id": "20260903T101530-000000"}
  • Response: 200 OK

List Application Releases ​

http
GET /api/apps/{name}/releases
  • Response: 200 OK
    json
    {
  "app": "my-app",
  "current": "20260903T101530-000001",
  "releases": [
    "20260903T090000-000000",
    "20260903T101530-000001"
  ]
}

Destroy Application ​

http
DELETE /api/apps/{name}
  • Response: 200 OK

Environment & Secrets ​

Get Environment Variables ​

http
GET /api/apps/{name}/env

Update Environment Variables ​

http
PUT /api/apps/{name}/env
Content-Type: application/json

{
  "LOG_LEVEL": "debug",
  "FEATURE_FLAG": "true"
}

Get Secret Names (Masked) ​

http
GET /api/apps/{name}/secrets
  • Response:
    json
    {
  "DB_PASS": "******",
  "API_KEY": "******"
}

Update Secrets ​

http
PUT /api/apps/{name}/secrets
Content-Type: application/json

{
  "DB_PASS": "new-secret-password"
}

Online Master Key Rotation ​

http
POST /api/secrets/rotate-key
  • Response: 200 OK
    json
    {
  "reencrypted_apps": 4,
  "status": "success"
}

Custom Domains ​

List Domains ​

http
GET /api/apps/{name}/domains
  • Response: 200 OK
    json
    {
  "app": "my-app",
  "domains": [
    "api.example.com",
    "example.com"
  ]
}

Add Custom Domain ​

http
POST /api/apps/{name}/domains
Content-Type: application/json

{
  "domain": "api.example.com"
}
  • Response: 200 OK

Remove Custom Domain ​

http
DELETE /api/apps/{name}/domains?domain=api.example.com
  • Response: 200 OK

Generate Platform Domain ​

http
POST /api/apps/{name}/domains/generate
  • Response: 200 OK
    json
    {
  "app": "my-app",
  "assigned": "my-app.apps.mycompany.com",
  "domains": [
    "my-app.apps.mycompany.com"
  ]
}

Preview Environments ​

List Previews ​

http
GET /api/previews

Promote Preview ​

http
POST /api/previews/{preview-app-name}/promote

Sweep Expired Previews ​

http
POST /api/previews/sweep

Webhook API (TCP 127.0.0.1:8082) ​

External Git platforms trigger deployments through the dedicated webhook listener:

http
POST http://127.0.0.1:8082/api/webhooks/{app}
Content-Type: application/json
X-GitHub-Event: push
X-GitHub-Delivery: <delivery-uuid>
X-Hub-Signature-256: sha256=<hex-digest>
  • MicroFly validates the HMAC-SHA256 signature using the secret stored under WEBHOOK_SECRET.
  • Valid requests return 202 Accepted and trigger asynchronous background deployment.
  • Invalid signatures return 401 Unauthorized.

Released under the MIT License.

Copyright © 2026 MicroFly Contributors