Setup

Agent-Up is currently a development preview. Packaged installers and platform packages are still being hardened while signing, update behavior, and service handling evolve.

Installed Desktop artifacts are expected to run the Server as a local background service. Desktop, CLI, and MCP clients connect to that service at http://localhost:5000 unless AGENTUP_SERVER_URL points elsewhere.

If the service starts and stops repeatedly or consumes CPU while failing to become ready, check whether another application is already listening on port 5000. Packaged services restart with a 5 second backoff, but Agent-Up still needs an available local server port.

Requirements

• .NET SDK 10.0 preview or compatible SDK for the current target framework.
• Git.
• Docker and Docker Compose when managed repositories declare Docker services.
• Node.js and npm for the documentation site.
• Nix on NixOS or Linux systems that need the provided native desktop dependency shell.

Clone and Build

git clone https://github.com/themassiveone/agent-up.git
cd agent-up
dotnet restore agent-up.sln
dotnet build agent-up.sln

Start the Server

When using an installed Desktop artifact, the Server should already be running as the local agent-up-server service.

REST authentication is required by default. Set AGENTUP_ADMIN_PASSWORD before starting a protected Server, or copy .env.example to .env in the repository root and edit the value there. Server, Desktop, and CLI load that file on startup when it exists; shell environment variables still take precedence.

cp .env.example .env
# edit .env, then:
dotnet run --project AgentUp.Server

You can still export the password directly when you prefer:

export AGENTUP_ADMIN_PASSWORD='choose-a-long-password'
dotnet run --project AgentUp.Server

Desktop and Mobile prompt for this password when they connect. The Server still starts when the password is unset, but login cannot succeed until it is configured.

For a deliberately unauthenticated local installation, set AGENTUP_AUTH_DISABLED=true instead. Desktop and Mobile skip their login UI in that mode.

To expose REST to the LAN, bind the Server to your network interface and protect it with HTTPS or a TLS-terminating reverse proxy. Plain HTTP exposes the administrator password during login and bearer tokens on the wire. MCP has no login because it is intended for local tools, and the Server rejects MCP requests whose remote address is not loopback.

Remote Desktop and Mobile clients must use HTTPS when the Server URL is not loopback. Loopback HTTP remains supported for local development on http://localhost and http://127.0.0.1.

For source development:

dotnet run --project AgentUp.Server

The development launch profile currently listens on:

http://localhost:5000

Start the Desktop

On systems with the required native desktop libraries available:

dotnet run --project AgentUp.Desktop

On NixOS:

./run-desktop.sh

The script runs the desktop inside shell.nix, which provides the native libraries needed by Avalonia, SkiaSharp, and WebKitGTK.

Release Artifacts

See Downloads for current platform download links and install commands.

Configure a Repository

Add agent-up.json to the repository you want Agent-Up to manage:

{
  "name": "My App",
  "applications": [
    {
      "name": "Frontend",
      "command": "npm run dev",
      "path": ".",
      "ports": [
        { "variable": "PORT", "defaultPort": 3000 }
      ]
    }
  ]
}

Applications should read ports from environment variables supplied by Agent-Up instead of hardcoding localhost ports.

Register a Workspace

From the managed repository:

dotnet run --project /path/to/AgentUp.CLI -- start --server http://localhost:5000

This reads agent-up.json, captures the current Git branch and commit, and registers the workspace with the server.

Contributor Workflow

Contributor testing and documentation builds are covered in the Developer Guide.

Troubleshooting

• If the desktop fails to start on Linux, use ./run-desktop.sh or install the native libraries listed in shell.nix.
• If the CLI cannot reach the server, pass --server http://localhost:5000 explicitly or set AGENTUP_SERVER_URL.
• If an application does not bind correctly, confirm it reads the configured port environment variable.
• If Docker services fail, verify Docker and Docker Compose work outside Agent-Up first.