Documentation

Git & Webhooks

Enable auto-deployment by connecting a process to a git repository. oxmgr pull fetches the latest code and reloads/restarts only when the commit changed.

Configure in oxfile.toml

oxfile.toml

[[apps]]
name = "api"
command = "node server.js"
git_repo = "git@github.com:org/api.git"
git_ref = "main"
pull_secret = "super-secret-token"

Manual Pull

oxmgr pull api       # pull specific process
oxmgr pull           # pull all git-tracked processes

Pull Behavior

Pull is idempotent — running it multiple times on the same commit has no side effects.

State	Action
Commit unchanged	No restart or reload — idempotent
Commit changed + process running	reload
Commit changed + process stopped	restart (to match desired state)
Commit changed + desired state stopped	Checkout only, no restart

Webhook Endpoint

The daemon exposes an HTTP API. Point your CI/CD or GitHub Actions to this endpoint to trigger automatic deploys on push.

# Trigger pull via webhook
curl -X POST http://localhost:PORT/pull/api \
  -H "X-Oxmgr-Secret: super-secret-token"

Pull endpoint	POST /pull/<name\|id>
Metrics endpoint	GET /metrics
Auth header	X-Oxmgr-Secret: <pull_secret>
Alt auth	Authorization: Bearer <pull_secret>
Bind address	OXMGR_API_ADDR env var (default: high localhost port)

GitHub Actions Integration

Trigger a pull from GitHub Actions on push to main. Store the webhook secret as a repository secret.

.github/workflows/deploy.yml

# .github/workflows/deploy.yml
name: Deploy
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Trigger Oxmgr pull
        run: |
          curl -fsS -X POST https://your-server.com/pull/api \
            -H "X-Oxmgr-Secret: ${{ secrets.OXMGR_SECRET }}"

Prometheus Metrics

The GET /metrics endpoint returns Prometheus text exposition format. Exposed metrics include process state, restart count, CPU, memory, PID, health-check status, and timestamps.

prometheus.yml

# Prometheus scrape config
scrape_configs:
  - job_name: oxmgr
    static_configs:
      - targets: ["127.0.0.1:51234"]
    metrics_path: /metrics

Security

—Keep the API bound to localhost unless you intentionally expose it externally.
—Use long random secrets and rotate on incident response.
—Prefer SSH deploy keys with read-only repository access.
—If exposing remotely, protect with reverse-proxy auth or source IP filtering.

Still have questions?

Open an issue or browse the source on GitHub.

Open an Issue ↗