Deployment

Foreground Process

aleph-server doctor
aleph-server start

The Gateway listens on 127.0.0.1:18790 by default. Its WebSocket endpoint is /ws.

System Service

service install writes the current platform's user-level service descriptor, enables it, and starts it immediately:

aleph-server service install
aleph-server service status

Supported management actions:

aleph-server service enable
aleph-server service disable
aleph-server service uninstall

There is no aleph-server service start subcommand. The installer records the current executable's absolute path and lets the native service manager run aleph-server start.

Linux status and logs:

systemctl --user status aleph-server.service
journalctl --user -u aleph-server.service -f

Some Linux distributions require linger to start the user service before login:

sudo loginctl enable-linger "$USER"

Prefer service install over copying a hand-written plist or unit with a hard-coded binary path.

Native TLS

Remote access requires secure transport. Without a reverse proxy, enable in-process TLS:

[gateway]
host = "0.0.0.0"
port = 18790
allow_insecure_remote = false

[gateway.tls]
enabled = true
# cert_path = "/path/to/cert.pem"
# key_path = "/path/to/key.pem"
# san = ["aleph.example.com"]

When cert_path and key_path are empty, Aleph generates a self-signed certificate. Remote clients connect to wss://<host>:18790/ws; Panel presents a TOFU certificate approval on first connection.

Reverse Proxy

The proxy must forward the HTTP application and WebSocket upgrades on /ws. The Gateway can remain bound to loopback:

[gateway]
host = "127.0.0.1"
port = 18790

[gateway.trusted_proxy]
enabled = true
trusted_ips = ["127.0.0.1", "::1"]

Only immediate peers in trusted_ips may supply trusted X-Forwarded-For and X-Forwarded-Proto headers.

Nginx

upstream aleph_gateway {
    server 127.0.0.1:18790;
}

server {
    listen 443 ssl;
    server_name aleph.example.com;

    ssl_certificate     /etc/letsencrypt/live/aleph.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/aleph.example.com/privkey.pem;

    location / {
        proxy_pass http://aleph_gateway;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 86400s;
    }
}

Caddy

aleph.example.com {
    reverse_proxy 127.0.0.1:18790
}

Containers

The current source tree does not maintain a Dockerfile or Compose file, so this guide does not present an example recipe as an officially supported artifact. A custom image must at least:

1. build aleph-server with Rust 1.95+;
2. persist ALEPH_HOME;
3. set [gateway].host = "0.0.0.0" inside the container;
4. publish the port only on host loopback or place a TLS proxy in front;
5. explicitly run aleph-server start.

Verification and Monitoring

aleph-server status
aleph-server gateway call health

File logs live under ~/.aleph/logs/; exact filenames depend on the current logging configuration. For managed services, prefer launchd, journald, or Task Scheduler status and logs.

Backup

The safest strategy is to stop writes and back up the entire ALEPH_HOME. At minimum, preserve:

• config.toml and defaults.toml
• data/, memory/, and artifacts/
• user-installed skills/ and plugins/

Do not depend on database filenames copied from older documentation; use the directories actually created by the running version.

Security Checklist

• Keep gateway.host = "127.0.0.1" for local-only use
• Use native TLS or a trusted TLS reverse proxy for remote access
• Keep allow_insecure_remote = false
• Use aleph-server pair for a single-use pairing ticket; do not put the shared token in URLs
• Preserve the [sandbox.command_policy] hard floor and choose exec_tier for the deployment risk
• Configure channel allowlists and pairing policies

Next Steps

• Configuration — current configuration structure
• Security — security model
• Gateway Protocol — WebSocket JSON-RPC API