Server & Deployment Reference
What a BYOS server must provide, what the guided installation puts on it, how traffic reaches the agent, and how to verify or recover the deployment.
Server & Deployment Reference
This page covers the technical side of the Web BYOS flow: what the server you supply must be able to do, what the guided installation places on it, and how to check the result.
Details vary by runtime, app version and account. Treat what your client displays during installation as authoritative; this page explains the shape of the process so you can tell a real problem from an expected step.
Server requirements
| Requirement | What it means in practice |
|---|---|
| Debian/Ubuntu-family Linux | The installation uses apt/dpkg and installs .deb packages. A distribution without them is not supported. |
| x86_64 (amd64) | Published runtime and tunnel binaries are built for amd64. ARM servers are not interchangeable here. |
| Reachable over SSH | You supply the host address and administrator credentials — either a password or a key. A non-default SSH port is supported where the client offers that field. |
| Administrative access | Installation writes system-level units and installs packages, so the account you supply must be able to do that. |
| Working outbound internet | Packages and runtime binaries are fetched from public sources during installation. |
Use a server you created for this purpose. The installation manages system services and packages, and is not designed to coexist with unrelated workloads on the same host.
Network requirements
Outbound access is required. During installation the server downloads packages and runtime binaries from public sources. A host that blocks outbound traffic, or sits behind a proxy that intercepts it, will fail partway through.
Inbound ports are usually not required. Where the deployment uses a Cloudflare Tunnel, a tunnel agent is installed on the server and makes an outbound connection to Cloudflare; traffic reaches your agent through that connection. In that configuration you do not need to open an inbound port, and doing so does not help.
The services the installation runs listen on the server's own loopback or local interfaces — they are reached through the tunnel, not by exposing them to the internet directly.
If you are tempted to "fix" a connection problem by opening ports in the hosting provider's firewall, check first whether your deployment uses a tunnel. Opening inbound ports adds exposure without addressing the cause.
What the installation puts on the server
Depending on the runtime you select and the version of the flow, the installation can place some combination of:
- An agent runtime — the CLI agent you selected. Several are supported, and which ones appear depends on the current app and account.
- A gateway service that supported clients connect through.
- A small management service used for runtime operations such as status and restart.
- A tunnel agent, where the deployment uses one, connecting outbound to expose the gateway without inbound ports.
- A local web server in front of the gateway in some configurations.
These run as system services so they survive a reboot. Their exact names differ by version; read them from the installation output rather than assuming.
Verifying a deployment
- Watch the installation output to completion. It reports the steps and any failure. Duration depends on the server, the package sources and the network.
- Confirm the client can reach the agent — open it from a supported AgentAura client and send a request that exercises the model provider you configured.
- Confirm it survives a restart. Reboot the server from your hosting provider's console and check the agent is reachable again without manual intervention. This is the difference between "it is running" and "it is installed".
When installation fails
Work through these in order — each rules something out:
- Is the server actually up and accepting SSH? A server that was created moments ago may not be ready yet. This is the single most common cause: the host exists in the provider's console but is still booting or has not finished its own first-boot setup. Wait, confirm you can SSH in yourself, then retry.
- Do the credentials work from your own machine? Connect manually with the same address, port, username and credential. If that fails, the problem is the credential or the provider's firewall, not the installation.
- Is outbound traffic allowed? If SSH works but the installation stalls while fetching packages, the host is likely blocking or intercepting outbound connections.
- Is another process holding the package manager? Cloud images often run unattended
upgrades on first boot, which locks
apt. The installation tolerates this for a while, but a long-running upgrade can outlast it. Wait for the server to settle and retry. - Is the distribution actually Debian/Ubuntu-family and amd64? A mismatch here fails in ways that look unrelated.
A failed installation does not cancel the server. It stays in your hosting account and keeps incurring charges until you delete it there.
Ongoing operation
Reconnecting an expired credential. Credentials you configure for a model provider can expire or be revoked. When that happens the agent stops responding to requests even though the server and services are still running — the failure looks like the agent is broken rather than like an authentication problem. Where the client offers a reconnect or re-authorise control for the agent, use it; it refreshes the credential on the server without redeploying.
Updating. Runtime updates are applied through the flow in your client rather than by editing files on the server by hand. Manual changes to the installed services can be overwritten by a later operation.
The server remains yours. Operating-system updates, firewall rules, storage, backups and deletion stay with you in the hosting provider's console. Removing an agent in AgentAura does not cancel or erase the server.
Boundaries worth knowing
- The agent runtime executes on your server, but that does not make every data flow local. Platform services participate in account, installation and connection flows.
- Your selected model provider receives the prompts and responses you send through the agent and processes them under its own terms.
- A tunnel provider, where used, carries the connection between your clients and the server.
Questions? Use the support page or email service@allianceinterstellar.com.